Crate yottadb

Expand description

YottaDB is a NoSQL Database suitable for high-performance systems.

YottaDB runs in-process, like SQLite, with no need for a daemon. This crate is a Rust wrapper around the C implementation of YottaDB.

There are two major APIs:

craw, the FFI bindings generated directly by bindgen. These are not recommended for normal use, but are available in case the Context API is missing functionality.
The main Context API, which is a safe wrapper around the C API which stores the current tptoken and an error buffer so you don’t have to keep track of them yourself. The reason this metadata is necessary is because this crate binds to the threaded version of YottaDB, which requires a tptoken and err_buffer. See transaction processing for more details on transactions and tptokens.

Most operations are encapsulated in methods in the KeyContext struct. Iteration helpers are available to iterate over values in the database in a variety of ways.

Examples

A basic database operation (set a value, retrieve it, and delete it)

use yottadb::{Context, KeyContext, DeleteType, YDBResult};

fn main() -> YDBResult<()> {
    let ctx = Context::new();
    let mut key = KeyContext::new(&ctx, "^MyGlobal", &["SubscriptA", "42"]);
    key.set("This is a persistent message")?;
    let buffer = key.get()?;
    assert_eq!(&buffer, b"This is a persistent message");
    key.delete(DeleteType::DelNode)?;
    Ok(())
}

Intrinsic Variables

YottaDB has several intrinsic variables which are documented online. To get the value of these variables, call get_st on a Key with the name of the variable.

Example

Get the instrinsic variable $tlevel, which gives the current transaction level.

use yottadb::{Context, KeyContext, YDB_NOTTP, YDBResult};

fn main() -> YDBResult<()> {
    let ctx = Context::new();
    let mut key = KeyContext::variable(&ctx, "$tlevel");
    let tlevel: usize = String::from_utf8_lossy(&key.get()?).parse()
        .expect("$tlevel should be an integer");
    assert_eq!(tlevel, 0_usize);
    Ok(())
}

Features

Since yottadb is a set of bindings to a C library, it uses bindgen to generate the bindings. There are two ways to do this:

features = ["vendor"], the default. This compiles bindgen from source.
default-features = false. This requires you to have bindgen already installed locally.

Using vendoring means you can use yottadb in any user environment, even when you don’t have admin priviledges to install programs. Using a pre-installed version means compile times are much lower.

YottaDB performs its own signal handling in addition to any signal handlers you may have set up. Since many functions in C are not async-safe, it defers any action until the next time ydb_eintr_handler is called. All YDB functions will automatically call ydb_eintr_handler if necessary, so in most cases this should not affect your application. However, there are some rare cases when the handler will not be called:

If you have a tight loop inside a Context::tp that does not call a YDB function

For example, the following loop will run forever even if sent SIGINT:

use yottadb::{Context, KeyContext};
let ctx = Context::new();
let loop_callback = |_| loop {
    std::thread::sleep(std::time::Duration::from_secs(1));
    println!("finished sleep");
};
ctx.tp(loop_callback, "BATCH", &[]).unwrap();

To avoid this, call Context::eintr_handler in the loop:

loop {
    std::thread::sleep(std::time::Duration::from_secs(1));
    ctx.eintr_handler()?;
    println!("finished sleep");
}

However, you should endeavor to keep transactions as short as possible - both for performance, since YottaDB uses optimistic concurrency control, and for reliability, since operations will not be committed until the transaction concludes.

As a last-ditch method of error-recovery, YottaDB will exit immediately if sent three interrupt signals in a row, even if eintr_handler is not called.

YottaDB does not register any signal handlers until the first time ydb_init is called, and deregisters its handlers after ydb_exit.