Module extremedb::sql

The SQL API.

This module requires the sql feature to be enabled.

For information about eXtremeDB SQL syntax and features, refer to the eXtremeDB SQL reference documentation.

Local and Remote Operation

eXtremeDB SQL supports both local and remote operation.

In the former case, SQL statements are executed locally, using a local SQL engine working over a database connection.

In the latter case, a remote SQL server is bound to a local engine and exposes a network API for remote clients to use. The clients can submit arbitrary SQL statements, which are executed by the server, and the results are passed back to the clients.

Remote SQL functionality is enabled using the rsql feature.

Examples

Currently, SQL can only be used with dynamic eXtremeDB dictionary, which requires setting certain parameters when the database is created:

    let mut db_params = database::Params::new();
    db_params
        .ddl_dict_size(32768)
        .max_classes(100)
        .max_indexes(1000);

A local engine can be created using an existing database connection:

    let db = database::Database::open(
        // ...
    )?;

    let conn = connection::Connection::new(&db)?;

    let engine = sql::engine::LocalEngine::new(&conn)?;

The engine can be used to execute both DDL and DML statements:

    engine.execute_statement("CREATE TABLE TestTable(i integer, s string);", &[])?;

    engine.execute_statement("INSERT INTO TestTable(i, s) VALUES(1, 'Hello');", &[])?;
    engine.execute_statement("INSERT INTO TestTable(i, s) VALUES(2, 'World');", &[])?;

    engine.execute_query("SELECT i, s FROM TestTable ORDER BY i;", &[])?;

Any type that implements the ToValue trait can be passed as a statement parameter. This module provides implementations of this trait for many common types.

    engine.execute_statement("INSERT INTO TestTable(i, s) VALUES(?, ?);", &[&1, &"Hello"])?;
    engine.execute_statement("INSERT INTO TestTable(i, s) VALUES(?, ?);", &[&2, &"World"])?;

Queries usually return a data source, and cursors can be used to iterate over the records in the data source. Individual column values in a record can be accessed by their column numbers.

    // Execute the query and fetch the data source.
    let ds = engine.execute_query("SELECT i, s FROM TestTable ORDER BY i;", &[])?;

    // `ds` is not expected to be `None` in this example.
    assert!(ds.is_some());
    let ds = ds.unwrap();

    // Get the cursor.
    let mut cur = ds.cursor()?;

    // The cursor is initially positioned before the first element.
    // We expect `advance()` to return true, indicating availability
    // of a record.
    assert_eq!(cur.advance()?, true);

    // Fetch the record and assert it is not `None`.
    let rec = cur.current_record();
    assert!(rec.is_some());
    let rec = rec.unwrap();

    // Get the values from the columns 0 and 1.
    let i_val = rec.get_at(0)?;
    let s_val = rec.get_at(1)?;

    assert_eq!(i_val.to_i64()?, 1);
    assert_eq!(s_val.to_string()?, "Hello");

Modules

allocator	Internal SQL allocators.
data_source	Data source returned by queries.
engine	SQL engine and related types.
mcosql_error_code	SQL return codes (generated by bindgen from mcosql_error_code in sql/sqlc.h).
rsql	Remote SQL.
trans	An SQL transaction.
value	SQL values.

Structs

SqlError

An Error-compatible wrapper for the eXtremeDB SQL status codes.

Type Definitions

McoSqlStatusCode

Type alias for the eXtremeDB SQL status codes.