native_db

Native DB benchmarks compare its performance against Redb (its underlying backend) and SQLite (a lightweight relational alternative).

Key Comparison Metrics

• N:SK: Represents the number of secondary keys (or columns with secondary indexes in SQLite) for the same data. Examples include 1:SK, 10:SK, etc.
• n:T: Represents the number of operations per transaction.
  • 1:T means exactly one operation per transaction.
  • n:T means n operations are bundled within a single transaction (as defined by criterion).

Benchmark Limitations

The following overheads are ignored in these results:

• native_model overhead.
• Serialization overhead (e.g., bincode, postcard) used by native_model.
• The fact that redb can perform zero-copy writes.

Note that Redb results may show N/A for secondary key comparisons because it is a key-value database and does not natively support secondary indexes.

When upgrading Native DB to a new major version with breaking changes, existing databases cannot be opened directly. You must perform a migration using the Builder::upgrade method.

The process involves:

1. Defining dual models: Define your data structures for both the old version and the current version.
2. Implementing conversion: Implement the From trait to convert the old model into the new model.
3. Executing the upgrade: Use Builder::upgrade to open the old database, scan its contents, and insert the converted items into a new database instance.

To manage multiple versions of Native DB in a single project, use Cargo's package renaming feature in your Cargo.toml to avoid name collisions.

// Example of the upgrade flow logic
let upgraded_db = CurrentBuilder::new().upgrade(&current_models, &db_path, |new_txn| {
    // 1. Open old database using old models/builder
    let mut old_models = V08xModels::new();
    old_models.define::<V08xModel>().upgrade_context("defining old model")?;
    let old_db = V08xBuilder::new().open(&old_models, &db_path).upgrade_context("opening old database")?;

    // 2. Scan old data
    let old_txn = old_db.r_transaction().upgrade_context("creating read transaction")?;
    let scan = old_txn.scan().primary().upgrade_context("creating primary scan")?;

    // 3. Migrate items
    for item_result in scan.all()? {
        let old_item: V08xModel = item_result.upgrade_context("reading item")?;
        let new_item: CurrentModel = old_item.into(); // Uses From implementation
        new_txn.insert(new_item)?;
    }
    Ok(())
})?;

The Models struct is a collection used to define and manage multiple database models within your application. It is typically used during the database initialization phase.

Lifetime Considerations

Because models are often needed by asynchronous libraries (like Axum) that require 'static lifetimes, it is common practice to define your Models collection as a static variable using once_cell::sync::Lazy or the standard library's std::sync::LazyLock.

Usage Pattern

1. Create a new Models instance using Models::new().
2. Register each model using .define::<T>().
3. Pass the Models collection to your database builder (e.g., Builder::new().create_in_memory(&MODELS)).

Note: The lifetime of the Models collection must be longer than or equal to the lifetime of the database instance.

use native_db::*;
use once_cell::sync::Lazy;

static MODELS: Lazy<Models> = Lazy::new(|| {
    let mut models = Models::new();
    models.define::<data::v1::Person>().unwrap();
    models
});

fn main() -> Result<(), db_type::Error> {
    let db = Builder::new().create_in_memory(&MODELS)?;
    Ok(())
}

A primary key is mandatory and must be unique. You can define exactly one primary key per model using one of two methods:

1. On a Field

Use the #[primary_key] attribute directly on a struct field. The field's type will be used as the primary key type.

2. With a Custom Method

Use the #[native_db(primary_key(<method_name> -> <return_type>))] attribute on the type. You must implement a method with the specified name that returns the specified type. The return type must be explicitly stated in the attribute for runtime query checking.

If no primary key is defined, the compiler will return the error: Primary key is not set.

// Method 1: On a field
#[derive(Serialize, Deserialize)]
#[native_model(id=1, version=1)]
#[native_db]
struct Data {
    #[primary_key]
    id: u64,
}

// Method 2: Custom method
#[derive(Serialize, Deserialize)]
#[native_model(id=1, version=1)]
#[native_db(primary_key(custom_id -> u32))]
struct Data(u64);

impl Data {
    fn custom_id(&self) -> u32 {
        (self.0 + 1) as u32
    }
}

Secondary keys are optional and flexible. You can define zero, one, or multiple secondary keys. They can be defined on a field or via a custom method.

Options

• unique: (Default: false) Ensures each instance has a unique value for this key. If a duplicate is inserted, insert will return an error.
• optional: (Default: false) Allows the key to be None. When using optional, the field type must be an Option<T>.

Important Limitation for optional keys

Items with None values in optional secondary keys cannot be queried using range syntax (e.g., range(None..=None)) because None values are not indexed in the secondary key table. To find None values, you must query all items and filter in your application code or use a sentinel value.

Implementation Styles

On a Field

#[derive(Serialize, Deserialize)]
#[native_model(id=1, version=1)]
#[native_db]
struct Data {
    #[primary_key]
    id: u64,
    #[secondary_key(unique, optional)]
    name: Option<String>,
}

With a Custom Method

#[derive(Serialize, Deserialize)]
#[native_model(id=1, version=1)]
#[native_db(secondary_key(custom_name -> Option<String>, optional))]
struct Data {
    #[primary_key]
    id: u64,
    name: String,
    flag: bool,
}

impl Data {
    fn custom_name(&self) -> Option<String> {
        if self.flag { Some(self.name.clone().to_uppercase()) } else { None }
    }
}