Documentation

Start a local instance, connect an application, and recover your data.

Your first shiny

A warren is a logical database. Each warren contains dens, and each den holds JSON documents called shinies. An ID belongs to one den, so two dens can each have a car:001.

From the source checkout, install the CLI and initialize your default instance. Choose an administrator password at the prompt. Leave the server running and open a second terminal for the shell.

Terminal 1 · install and serve

cargo install --locked --path crates/ratdb-cli
ratdb init
ratdb serve

Terminal 2 · run ratdb, sign in, then enter

use garage
use cars
put car:001 {"make":"Ford","year":2021}
update car:001 {"year":2022}
get car:001
find make=Ford
page 20
exit

Embed in Rust

Use ratdb-document when one application owns the file. Add it as a path dependency from the source checkout, along with serde_json. The handle owns an exclusive lock until it is dropped.

This example creates a fresh file. On subsequent runs use Documents::open("garage.ratdb") to reopen it.

Embedded API reference Portable storage adapters

Rust · local file

use ratdb_document::Documents;
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut db = Documents::create("garage.ratdb")?;
    let mut cars = db.warren("garage")?.den("cars")?;
    cars.put("car:001", json!({"make": "Ford"}))?;
    if let Some(car) = cars.get("car:001")? {
        println!("{}", car["make"]);
    }
    Ok(())
}

Connect to a server

Use a persistent connection when several applications share an instance. The server owns the file and serializes database operations. A client authenticates once and selects its own warren and den.

The server listens on loopback by default at 127.0.0.1:7337. Use an authenticated SSH tunnel for remote connections. The bundled Rust and Python clients connect through the local endpoint.

The development checkout adds a Node.js client and conditional transactions. On a v3 instance you can also create field indexes and enforce uniqueness. The frozen alpha download includes the Rust and Python clients.

Node.js client guide Conditional transactions Consistent reads across pages Secondary indexes and unique fields Rust client guide Python client guide Wire protocol

Python · read the shiny from the shell guide

from getpass import getpass
from ratdb import Client

with Client("admin", getpass()) as db:
    db.select_warren("garage")
    db.select_den("cars")
    print(db.get("car:001"))

Copy clients/python/ratdb.py from the checkout beside your script.

Limits and recovery

Storage v1 reserves two banks of 16 MiB each by default. One bank holds the active snapshot. Each commit writes a new snapshot to the other bank and acknowledges it after the final sync. Cost grows with live data.

A default file accepts encoded values up to 256 KiB. Pages return up to 100 documents under a 512 KiB serialized-document budget. Continue with the returned cursor to read further. Each page sees the current committed state.

Recovery audit Engineering report

Restore to a fresh path

Stop the server and locate its data file. For an explicit file named garage.ratdb, use the commands below. Both destinations must be unused. The backup contains data only, so set credentials before serving the restored file.

Terminal · server stopped

ratdb backup garage.ratdb garage.backup
ratdb restore garage.backup recovered.ratdb
ratdb check recovered.ratdb
ratdb setup recovered.ratdb admin
ratdb serve recovered.ratdb

The development server can take a generation-consistent backup while clients stay connected. Operators can rehearse an upgrade using the archived alpha.

Online backup guide Upgrade and rollback rehearsal

If a write loses its reply, reconnect and read the record before retrying. If open reports corruption or ambiguous headers, preserve the original file and investigate a copy. Recovery depends on the storage adapter honoring successful syncs.