Keyspaces

A keyspace is an independent set of keys inside one database. Each keyspace has its own options, in-memory tables, levels and compactions. A key in one keyspace never collides with the same key in another.

Every database has the default keyspace, KeyspaceId::DEFAULT, named "default". A database holds up to 4096 keyspaces; a name is up to 255 bytes.

Why several

• Different data wants different options: a cache with FIFO compaction beside records with leveled compaction, or a stronger compression codec for cold data.
• Dropping a keyspace removes all its keys at once, far cheaper than deleting them one by one.
• A batch may span keyspaces and stays atomic across them, even across a crash.

Naming keyspaces at open

The database records which keyspaces it holds, not their options. Every open must name every keyspace it holds, with its options.

use tessarikv::{CompactionStyle, Db, DbOptions, KeyspaceOptions};

async fn open_with_sessions() -> tessarikv::Result<Db> {
    let sessions = KeyspaceOptions::builder()
        .compaction(CompactionStyle::fifo())
        .build()?;
    let options = DbOptions::builder()
        .keyspace("sessions", sessions)
        .create_missing_keyspaces(true) // add it the first time
        .build()?;
    let db = Db::open("data/app", options).await?;
    let _sessions_id = db.keyspace("sessions"); // Some(id)
    Ok(db)
}

A keyspace the options name and the database does not hold is added when create_missing_keyspaces is set, and refused otherwise. A keyspace the database holds and the options do not name is refused.

Db::keyspace(name) returns a keyspace's id; Db::keyspaces() lists every one.

Creating and dropping while running

use tessarikv::{Db, KeyspaceOptions};

async fn rotate(db: &Db) -> tessarikv::Result<()> {
    let metrics = db.create_keyspace("metrics-2026-10", KeyspaceOptions::default()).await?;
    // Reads and writes may name `metrics` from here on.
    if let Some(old) = db.keyspace("metrics-2026-09") {
        db.drop_keyspace(old).await?;
    }
    let _ = metrics;
    Ok(())
}

• create_keyspace returns an id no other keyspace of this database ever takes. On storage the keyspace is recorded before it returns. Later opens must name it.
• drop_keyspace removes the keyspace with every key in it. Reads and writes naming it are refused from then on. Its table files are removed once no reader holds them. Later opens must no longer name it. The default keyspace is never dropped.

Recorded options

Every open writes the options it runs with to a file named OPTIONS-<n> in the database directory, so you can see later what a database ran with.