Crate yottadb

source ·
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.


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");

§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.


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);


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.

§Signal handling

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 {
    println!("finished sleep");
};, "BATCH", &[]).unwrap();

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

loop {
    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.

§See also



  • A wrapper for C YottaDB API (the C Raw API, CRAW)


  • Make an FFI call to M.
  • Make a FFI call to M using a cached function descriptor.
  • Create a KeyContext with the given subscripts, provided a context.
  • Provides a Key object for the given subscripts.




  • The default transaction processing token if no transaction is in progress.


  • Cleans up the process connection/access to all databases and all yottadb data structures.

Type Aliases§

  • A specialized Result type returned by a YottaDB function.