dactyl

dactyl-db is a lightweight application-layer datastore for read/write-heavy apps that need the same small Rust surface over a local store and Vercel Neon. It binds values, normalizes returned rows, and exposes explicit physical atomicity so the application does not need separate driver code for each backend.

Dactyl is deliberately not database-administration tooling. Callers own schema design, migration ids and ordering, grouping policy, retries, analytics, and business intelligence. Dactyl owns only physical execution, local durability, atomic batch boundaries, access mode, and result/error normalization.

What is shared

SQLite and Neon use the same application contract:

• read(sql, params) returns owned Rows.
• write(sql, params) returns the affected-row count for compatibility; write_result also returns explicit generated keys.
• atomic(&[Operation]) executes an opaque all-or-nothing batch and preserves result order. Empty batches are no-ops, and a failed batch persists nothing. It does not implement retry, nesting, or idempotency policy.
• OpenOptions { access_mode: ReadOnly, .. } opens a non-mutating handle.
• Values are bound as Null, Bool, Integer, Real, Text, or Blob.
• The Neon adapter forwards SQL to /query and atomic batches to /batch.
• StorageContext is a versioned opaque { version, payload } envelope. It is ignored by local storage and forwarded unchanged by Neon; Dactyl does not interpret tenancy or authorization fields.
• Adapter failures use typed categories including busy/locked/timeout, constraint/conflict/version-conflict/transaction-aborted, read-only, capability, value, storage, transport, authentication/authorization, quota, rate-limit, and protocol failures. Remote stable error codes are available through DactylError::adapter_code() without parsing provider messages.

The local implementation is a thin private C-ABI connection behind the same public contract. The optional sqlite feature dynamically loads the host's shared SQLite library at runtime; Dactyl does not compile or bundle SQLite, and does not duplicate SQLite's file format, parser, pager, journal, or query planner. The route name and DATASTORE=sqlite setting therefore mean what they say: the requested path is an ordinary SQLite database.

Local SQLite route

DATASTORE=sqlite DATASTORE_ROUTE=/path/to/app.db opens the file directly. Existing SQLite files remain readable and writable without conversion. A read/write route creates a missing file and its parent directory; a read-only route requires an existing file. SQLite supplies locking, journaling, crash recovery, and its supported SQL surface. Dactyl applies the configured busy timeout and maps SQLite busy, locked, constraint, read-only, corrupt, and storage outcomes into its typed error categories.

The SQLite connector report records the boundary and the compatibility proof. The same report is published from docs/ as GitHub Pages.

Connection::inspect_schema() returns a backend-neutral catalog containing tables, columns, nullability/defaults, primary and unique keys, indexes, foreign keys, delete actions, and row counts. Callers do not need to issue SQLite-specific catalog queries. Blobs are normalized to JSON arrays of bytes and are read back with Row::get_blob; NULL, text, integer, REAL, and blob values remain distinct through the public row contract.

Schema versioning, migration ordering, backups, import from legacy stores, retry/backoff, idempotency keys, and domain-level version/CAS policy remain with Decapod or Propodus. The Neon adapter maps the stable Propodus v1 error codes it receives, but it does not invent the resource-route translation or claim live cloud parity when that service contract is unavailable.

Local and mock conformance matrix

tests/storage_fixtures.rs is the backend-neutral fixture suite. The same cases run against the local store and, when the neon feature is enabled, an in-process executing mock that speaks the Neon /query and /batch envelope.

A skipped live backend is recorded as unavailable, never passed. Local CAS is a zero-row observation on a caller-owned version predicate. Dactyl does not invent a version-conflict policy for the local store.

Quick start

[dependencies]
dactyl-db = { version = "0.8.0", features = ["sqlite", "neon"] }

Select the backend with environment variables:

DATASTORE=sqlite DATASTORE_ROUTE=/path/to/app.db
# or
DATASTORE=neon DATASTORE_ROUTE=https://propodus.example DATASTORE_TOKEN=...

Use the same calls for either backend:

use dactyl_db::{read, write, Parameter};

fn load_app_rows() -> Result<(), dactyl_db::DactylError> {
    write(
        "insert into app_events (name) values ($1)",
        &[Parameter::Text("opened".into())],
    )?;

    let rows = read("select name from app_events order by id", &[])?;
    for row in rows.iter() {
        println!("{}", row.get_str("name")?);
    }
    Ok(())
}

For an explicit route, use Connection::open:

use dactyl_db::{Connection, DatastoreRoute, Parameter};

let db = Connection::open(DatastoreRoute::sqlite("/tmp/app.db"))?;
db.write(
    "update accounts set last_seen = $1 where id = $2",
    &[Parameter::Integer(1_725_000_000), Parameter::Integer(7)],
)?;

Remote callers provide the Decapod-owned context separately from the physical route. The context payload is application-owned and must be a JSON object; its fields are opaque to Dactyl:

use dactyl_db::{Connection, DatastoreRoute, StorageContext};
use serde_json::json;

let context = StorageContext::new(
    1,
    json!({"opaque_target": "target", "opaque_session": "session"}),
)?;
let db = Connection::open_with_context(
    DatastoreRoute::neon("https://propodus.example", None),
    Some(context),
)?;

Neon requests without a valid context fail closed with a typed authentication_required or invalid_context error before Dactyl sends SQL.

Use an explicit physical batch and generated-key result when those semantics matter:

use dactyl_db::{Connection, DatastoreRoute, Operation, Parameter};

let db = Connection::open(DatastoreRoute::sqlite("/tmp/app.db"))?;
let result = db.atomic(&[
    Operation::schema("create table if not exists events (id integer primary key, name text)", Vec::new()),
    Operation::write("insert into events (name) values ($1)", vec![Parameter::Text("opened".into())]),
])?;

Environment

DATASTORE is the only ambient selector. Dactyl requires a non-empty DATASTORE_ROUTE for whichever selector is chosen and fails before adapter construction when either value is missing, empty, or unsupported. There is no implicit SQLite fallback, so a deployment cannot silently write to a local file when its Neon configuration is malformed. DATASTORE_TOKEN is read only for neon; an unset or blank token is treated as absent and does not change the context requirement. Explicit Connection::open routes bypass ambient selection without changing the free-function signatures.

The database schema and backend endpoint contract are application-owned. Dactyl executes caller-supplied schema statements but does not assign migration ids, order migrations, create hidden tables, or administer recovery policy.

License

MIT.