Crate mimerrust

source ·
Expand description

A Rust API for the Mimer SQL database.

§Introduction

The Mimer SQL Rust API is built as a wrapper around the Mimer C API. It consists of three crates:

  1. mimerrust-sys: This crate is responsible for the low-level wrapping of the C library into compatible Rust concepts. It is not meant for direct use, but rather as an intermediary wrapping step.
  2. mimerrust-bindings: This crate is the one that is running bindgen to generated the C bindings using by mimerrust-sys. This is put in a separate crate so we don’t have to run bindgen all the time. The reason is that bindgen requires LLVM and Clang and that is typically not installed on Windows. Instead we generate and keep the bindings, unless explicitly building this crate.
  3. mimerrust: This crate uses the raw wrappers from mimerrust-sys to create a high level, safe interface. A small example of how to use Mimer SQL Rust API can look like this:
use mimerrust::{Connection, ToSql, CursorMode};
 
fn main() {
    print!("Connecting to database\n");
    let mut conn =
        Connection::open("", "RUSTUSER", "RUSTPASSWORD").unwrap_or_else(|ec| panic!("{}", ec));
 
    conn.execute_statement("DROP TABLE test_table").ok();
    println!("Creating table");
    conn.execute_statement("CREATE TABLE test_table (id INT primary key, text NVARCHAR(30))")
        .ok();
    println!("Inserting rows");
    let insert_stmt = conn.prepare("INSERT INTO test_table (id, text) VALUES(:id, :text)", 
        CursorMode::Forward).expect("Error preparing statement");
 
    let mut text = "Hello";
    let mut id = 1;
    let params: &[&dyn ToSql] = &[&id,&text];
    insert_stmt.execute_bind(params).expect("Error inserting first row"); 
 
    text = "World!";
    id = 2;
    let params: &[&dyn ToSql] = &[&id,&text];
    insert_stmt.execute_bind(params).expect("Error inserting second row");  
 
    let stmt = conn
        .prepare("SELECT * from test_table", CursorMode::Forward)
        .unwrap();
    let mut cursor = stmt.open_cursor().unwrap();
    println!("Fetching all rows");
    while let Some(row) = cursor.next_row().unwrap() {
        let id: i32 = row.get(1).unwrap().unwrap();
        let text: String = row.get(2).unwrap().unwrap();
        println!("id: {}, text: {}", id, text);
    }
}

All examples and tests uses an ident called RUSTUSER with the password RUSTPASSWORD. To create the user in Mimer SQL, run bsql or DbVisualizer as SYSADM, or an other ident with proper privileges, and create the ident as follows:

create ident RUSTUSER as user using 'RUSTPASSWORD';
grant databank to RUSTUSER;

To run the examples you need a databank as well. Log into Mimer SQL using bsql or DbVisualizer as RUSTUSER and run:

create datank rustdb

The tests create the databanks needed.

§Requirements

This API requires the Mimer SQL C API to be installed on the system. The API is tested with Mimer SQL 11.0.8D. Furthermore, bindings to the Mimer SQL C API are generated at compile time using bindgen, which requires clang to be installed on the system. The bindings are not re-built automatically, instead a pre-generated binding is used. This is to avoid requirements on having Clang on for example Windows. To generate new bindings, go into the mimerrust-bindings and run cargo build.

Re-exports§

Modules§

  • types
    Handles datatypes and their conversions between Rust and Mimer SQL.

Structs§

  • Connection
    Represents a connection to a MimerSQL database.
  • Cursor
    An iterator for result sets from MimerSQL databases.
  • MimerError
    Represents an error occuring during communication with a MimerSQL database.
  • Row
    Represents a row in a result set.
  • Statement
    A prepared statement.
  • Transaction
    Represents a transaction on a database connection. A Transaction will roll back by default if the object is dropped. Use the commit method to commit the changes made in the transaction.

Enums§

Constants§