Ridge Embedded API

Use the ridge Grove package when one seed process should own the database. The database handle is a move-only resource with deterministic cleanup.

Minimal application

use "ridge"

fn main() -> result<i64, ridge_error> {
    let mut db = ridge_open("./data/app", 4096 as usize)?
    db.create_table("items", 4096 as usize)?

    let payload = bytes.from("hello").or_abort()
    db.insert("items", 1, payload.view())?

    let found = db.get("items", 1)?
    match found {
        some(row) => print(f"row={row.id}")
        none => print("not found")
    }
    result.ok(0)
}

Run the current seed compiler checks before copying an example into an application:

./seed/seed check path/to/application
./seed/seed test path/to/application

Core operations

ridge_open / ridge_open_with_cache
db.create_table / db.insert / db.get / db.update / db.delete
db.count / db.scan / db.find_equal / db.create_unique_index
db.begin / db.try_begin / db.transaction_put / db.transaction_delete
db.commit / db.rollback
db.integrity / db.backup / ridge_validate_backup / ridge_restore
db.commit_stats / db.stats

The direct legacy row API stores an i64 primary key and binary-safe payload. The relational and SQL packages provide generation-2 typed multi-column rows. Choose one coherent data path for an application rather than mixing legacy and relational visibility assumptions.

Ownership and errors

• Treat the database and transaction handles as owned resources.
• Propagate ridge_error with ? or handle it explicitly.
• Keep borrowed row and buffer views inside their valid lexical scope.
• Never duplicate or edit Ridge storage files while the database is open.
• Use Ridge backup and restore APIs for consistent copies.

Use the seed-lang skill together with ridgedb when an AI agent writes or reviews .sd code.

Observability

db.commit_stats() returns per-commit WAL, page, cache, split/merge, reuse, I/O, sync, allocation, and staging counters. db.stats() returns cumulative cache and engine-owned buffer statistics since open. Interpret these as local diagnostics, not fleet telemetry.