extremedb

McObject eXtremeDB bindings for Rust.

This package implements the high-level, safe Rust APIs.

For more information and samples refer to the extremedb crate documentation. Note that an existing installation of eXtremeDB 8.2 is required to build this package and run the samples. An evaluation eXtremeDB package can be requested at the McObject website.

lib.rs:

extremedb is a wrapper for the McObject's eXtremeDB database management system.

This crate currently supports the eXtremeDB SQL APIs, as well as parts of the core functionality necessary for configuring the eXtremeDB runtime, creating and opening a database, and managing database connections. Core data manipulation APIs are planned for a future release.

For more information on the eXtremeDB database management system, refer to the documentation pages.

Building

This crate depends on the extremedb_sys crate, which has some prerequisites, as well as a few environment variables to be set. Refer to the extremedb_sys crate reference for more information.

Optional Features

• sql — SQL engine.
• rsql — Remote SQL engine (SQL server and client).
• sequences — Sequences (vertical storage).

SQL Example

The example below demonstrates creating an in-memory database and using the DDL and DML SQL statements to manipulate its schema and contents.

use extremedb::connection::Connection;
use extremedb::database::{Database, Params};
use extremedb::device::{Assignment, Device};
use extremedb::runtime::Runtime;
use extremedb::sql::engine::{Engine, LocalEngine};
use extremedb::Result;

fn main() -> Result<()> {
    // Size of the memory region to allocate for the database.
    const DB_SIZE: usize = 1024 * 1024;

    // eXtremeDB runtime must be started before any operations can be performed.
    let runtime = Runtime::start(vec![]);

    // This example creates a conventional memory device, and will not work with the
    // shared memory runtime.
    assert!(!runtime.info().multiprocess_access_supported());

    // Initialize database parameters. SQL databases require these three
    // parameters to be explicitly set.
    let mut db_params = Params::new();
    db_params
        .ddl_dict_size(32768)
        .max_classes(100)
        .max_indexes(1000);

    // Allocate one in-memory device for the database.
    let mut devs = vec![Device::new_mem_conv(Assignment::Database, DB_SIZE)?];

    // Open the database using the parameters and devices defined above.
    let db = Database::open(&runtime, "test_db", None, &mut devs, db_params)?;

    // Establish a connection to the database.
    let conn = Connection::new(&db)?;

    // Create a local SQL engine on top of the database connection.
    let engine = LocalEngine::new(&conn)?;

    // Use SQL DDL to create a new table.
    engine.execute_statement("CREATE TABLE TestTable(i integer, s string);", &[])?;

    // Insert two rows into the table.
    engine.execute_statement("INSERT INTO TestTable(i, s) VALUES(?, ?);", &[&1, &"Hello"])?;
    engine.execute_statement("INSERT INTO TestTable(i, s) VALUES(?, ?);", &[&2, &"World"])?;

    // Select the rows.
    let ds = engine.execute_query("SELECT i, s FROM TestTable ORDER BY i;", &[])?;

    // The returned data source is not expected to be empty in case of a
    // SELECT statement.
    assert!(ds.is_some());
    let ds = ds.unwrap();

    // Create a cursor to iterate over the data source.
    let mut cur = ds.cursor()?;

    // Read the first row.
    {
        // Advance the cursor to the first row. It is positioned
        // before-the-first row initially.
        assert_eq!(cur.advance()?, true);

        // Get reference to the record which the cursor points at.
        // Since cur.advance() above has returned true, the current record
        // must not be None.
        let rec = cur.current_record();
        assert!(rec.is_some());
        let rec = rec.unwrap();

        // Get the references to the values in the columns at indexes 0 and 1.
        let i_val = rec.get_at(0)?;
        let s_val = rec.get_at(1)?;

        // SQL value references must be explicitly converted to target types.
        assert_eq!(i_val.to_i64()?, 1);
        assert_eq!(s_val.to_string()?, "Hello");
    }

    // The second row must be available.
    assert_eq!(cur.advance()?, true);

    // No more rows are expected.
    assert_eq!(cur.advance()?, false);

    Ok(())
}