dbnest

Cozy local databases in seconds.

dbnest is a cross-platform CLI for provisioning local databases and initializing schema from a simple JSON (file or folder layout).

Current features

• SQLite embedded provisioning (no external dependencies)
• PostgreSQL server Docker instance (Docker required)
• Instance registry (list / remove with --force)
• Instance lifecycle status checks
• PostgreSQL lifecycle commands: start, stop, restart
• PostgreSQL persistent Docker volumes, removed only with rm --force --volumes
• Schema workflow:
  • plan generates SQL from schema
  • apply executes the schema against the database
  • up --schema provisions and bootstraps in one command
• Schema input formats:
  • Single JSON file (schema.json)
  • Directory layout (schema/<table>/columns.json, optional indexes.json)

0.1.2 hardening:

• Safer schema validation and deterministic plans
• Secret redaction in output by default
• Safer removal with rm --force
• PostgreSQL persistent Docker volumes
• start / restart
• Structured JSON errors when --json is used
• Additional registry, schema, output, and ignored Docker integration tests

Planned after SQLite/PostgreSQL hardening:

• MySQL via Docker
• Migration-aware planning through the existing plan command

---

Install

From crates.io (recommended)

cargo install dbnest

From source

cargo install --path crates/dbnest-cli

---

Quickstart

1. Create a database

SQLite:

dbnest up sqlite --path ./dev.sqlite

PostgreSQL:

dbnest up postgres --user dev --password dev --db appdb

List instances. This is metadata-fast and does not perform live health checks.

dbnest ls

Check instance status

dbnest status {instance_id}
dbnest status --all      # status for all dbnest instances

Stop a PostgreSQL instance:

dbnest stop {instance_id}
dbnest start {instance_id}
dbnest restart {instance_id}

Remove an instance:

dbnest rm {instance_id} --force
dbnest rm {instance_id} --force --volumes   # also remove PostgreSQL data volumes

2. Define schema Create a schema file or directory layout

schema.json:

{
  "tables": [
    {
      "name": "users",
      "columns": [
        { "name": "id", "type": "uuid", "primary_key": true },
        { "name": "email", "type": "string", "unique": true, "nullable": false },
        { "name": "created_at", "type": "timestamp", "default": "now" }
      ],
      "indexes": [
        { "name": "idx_users_email", "columns": ["email"], "unique": true }
      ]
    }
  ]
}

Or a directory layout:

schema/
  users/
    columns.json
    indexes.json

with columns.json and indexes.json containing the respective table schema.

[
  { "name": "id", "type": "uuid", "primary_key": true },
  {
    "name": "email",
    "type": "string",
    "unique": true,
    "nullable": false
  },
  { "name": "created_at", "type": "timestamp", "default": "now" }
]

3. Generate SQL from schema (plan)

SQLite:

dbnest plan sqlite --schema ./schema.json               # from single json schema
dbnest plan sqlite --schema ./schema/                   # from directory based schema

Postgres:

dbnest plan postgres --schema ./examples/schema.json    # from single json schema
dbnest plan postgres --schema ./schema/                 # from directory based schema

4. Apply schema to database (apply)

dbnest apply --id <INSTANCE_ID> --schema ./schema.json
# or
dbnest apply --id <INSTANCE_ID> --schema ./schema/

Provision and apply schema in one command:

dbnest up sqlite --path ./dev.sqlite --schema ./schema.json
dbnest up sqlite --path ./dev.sqlite --schema ./schema.json --keep-on-failure

Commands that print connection data redact secrets by default. Use --show-secrets only when you need the full connection URL.

---

Documentation

• docs/schema.md describes the JSON schema format.
• docs/lifecycle.md describes instance lifecycle behavior.
• docs/security.md describes secret redaction and local metadata handling.
• docs/development.md and docs/testing.md describe development workflows.

---

License

MIT