dbsnap

Database checkpoints for local development and AI coding agents.

Save a snapshot before a migration or bulk edit, then restore the schema and data if you need to roll back. Use dbsnap from your terminal or connect its built-in MCP server to an AI assistant.

Supports SQLite, PostgreSQL, and MySQL/MariaDB. The npm package bundles prebuilt binaries for Windows x64, macOS Intel and Apple Silicon, and Linux x64 (glibc and musl) and ARM64 (glibc).

MySQL/MariaDB restore works on the original database. Stop application connections, writers, and scheduled events first. Restore is non-atomic and requires a pinned safety snapshot. Interrupted restores must recover that snapshot before another restore; see the recovery steps below.

Install

Requires Node.js 16 or later.

Portable archives, server row previews, Git output, and PostgreSQL dump sandboxes require dbsnap v0.4.1 or later.

v0.4.2 binds init to the current directory, finds native clients in common Homebrew locations, and lets diff-rows --show-values select Git-style output when no format is given.

npm install -g @farhan0431/db-snap
dbsnap --version

Or run without a global install:

npx -y @farhan0431/db-snap --help

Migration rehearsals and CI

Use dbsnap to capture a restore point, run migrations against a disposable development or staging database, and review schema and row changes before rollout. The CLI runs in scripts, and the built-in MCP server gives coding agents access to checkpoint and inspection tools.

Point your migration runner at the sandbox explicitly. Keep production rollout and production backups in your existing deployment and recovery systems. Use sanitized data in shared environments.

Quick start

Run these commands in the root of the project containing your development database:

dbsnap init
dbsnap status
dbsnap save "before migration"

# Run your migration or make changes here.

dbsnap list
dbsnap restore "before migration"  # restores the selected snapshot

Target resolution is --db, then process DATABASE_URL, then project .env, then common SQLite paths. To choose a database explicitly, use dbsnap init --db ./prisma/dev.db. Check the target with dbsnap status before restoring: a restore changes the live database.

Snapshots and metadata live in .dbsnap/ in your project. The directory is added to .gitignore during initialization.

Use with an AI assistant

Register dbsnap as an MCP server in a compatible client. For example, add the following to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "dbsnap": {
      "command": "dbsnap",
      "args": ["mcp"]
    }
  }
}

Restart your client and ask it to run dbsnap_status to confirm the database before making changes. The server also exposes tools to create, list, restore, and prune snapshots. It resolves the project from its working directory, so start it in the project you want to protect. The current source exposes eleven tools:

Results include text plus structured ok, message, optional typed data and broad error codes. Snapshot creation returns the exact ID in data. Annotations describe behavior but do not replace session permissions or elicitation.

Restore and prune are disabled by default in MCP. To enable them for a server session, start it with dbsnap mcp --allow-destructive. Each operation requires approval through an MCP client supporting elicitation; otherwise use the CLI.

To configure an explicitly enabled session, change the server arguments to ["mcp", "--allow-destructive"]. Enabling the session does not approve individual operations. Your MCP client must still present and return the confirmation for each restore or prune.

dbsnap init also writes .agents/skills/dbsnap/SKILL.md in the project. Whether that skill is loaded automatically depends on the AI client; the skill file and the MCP server are separate integrations. Initialization preserves an existing skill file instead of overwriting local customizations. Updating the installed binary does not refresh that existing file; review it against the repository's current skill when upgrading.

Commands

dbsnap list --json and dbsnap status --json provide machine-readable output. Pinned snapshots survive prune, including --all.

Use the recorded ID when undoing a specific change. Duplicate tags may be ambiguous. rollback and restore without a selector choose the newest snapshot, which can be an automatic safety snapshot from a previous restore.

Snapshot diff

v0.4.4 rehearsal supplies a sandbox connection to a trusted migrator and reports schema/count changes. It retains sandbox resources and before/after snapshots for inspection, and discards child output. Verify the migrator uses its environment connection. Commands have the user's privileges and can select other connections. MCP requires session enablement and per-call approval. MySQL/MariaDB rehearsal and automatic sandbox removal are pending. See the rehearsal guide for timeout limits, exit codes and cleanup.

dbsnap save before
# Make your development changes.
dbsnap save after
dbsnap diff before after

Diff compares snapshots, not the current live database. SQLite compares schema objects and row counts. PostgreSQL clone diff compares table/view definitions and row counts. MySQL/MariaDB diff reads verified standard dumps offline, including multiline INSERT data, and compares table definitions and row counts. It does not replay SQL into the target.

Equal row counts do not mean equal data. Individual row contents are not compared. PostgreSQL diff excludes indexes, constraints, routines and triggers; MySQL/MariaDB diff excludes views, routines, triggers and events. Unsupported INSERT formats produce an error. Version 0.4.0 and later can compare two PostgreSQL dump archives offline through pg_restore: archive-wide schema changes and table counts from column-list COPY data, excluding ownership, privileges, row contents and sequence values. Mixed clone/archive diff is unsupported.

diff-rows additionally supports SQLite added/removed/updated counts without printing values. It requires explicit non-NULL primary keys and matching column layouts, refusing previews above --limit (maximum 100,000). Server-engine row diff is not implemented. diff-live uses storage and may briefly fence PostgreSQL connections because it creates a regular retained snapshot.

Checkpoints, diagnosis and sandbox experiments

verify and doctor print JSON. Verification failure exits nonzero. Doctor reports a failed probe in its report and does not automatically repair anything. recover reads the existing MySQL journal's ID or applies unambiguous PostgreSQL journal recovery. It does not repair a stopped database server or choose an arbitrary restore point. SQLite has no server recovery journal.

exec directly spawns a program without a shell, saving a checkpoint first. Snapshot failure prevents execution. Child failure retains the checkpoint and returns its ID, exit code and recovery command; the parent exits nonzero. Output is returned up to 64 KiB per stream. --db selects the checkpoint database, not the database your external program will use; set its environment deliberately. Arbitrary command execution is CLI-only, not an MCP tool.

SQLite and PostgreSQL clone sandboxes let experiments target independent data. Connect your migration/application explicitly to the returned file/database. Cleanup is manual after closing sandbox connections. MySQL/MariaDB sandboxes require explicit --docker-image mysql:8.0 or mariadb:11: a separate Docker server imports the verified dump with its original schema name, network disabled, no published ports/host mounts/source credentials. Use docker exec for SQL experiments and remove the returned container explicitly afterwards. Failed imports remove only the newly created container. v0.4.1 also supports sandbox replay from trusted PostgreSQL custom dumps. See the workflow guide below.

Portable archives and Git-style row previews

These commands require v0.4.1 or later.

dbsnap export before --output before.dbsnap
dbsnap import before.dbsnap --tag transferred
dbsnap diff-rows before after --table users --format git --show-values

• Archive transfer. Import verifies checksums and registers a new snapshot in the destination catalog. Restore is separate. The archive contains database contents, so keep it private and accept only trusted archives. PostgreSQL clone export requires matching pg_dump. MySQL/MariaDB requires the original database name at the destination.
• Row preview. Use a table with an explicit primary key. JSON and MCP return counts. Git output shows schema changes when layouts differ and can show stored row values when layouts match and --show-values is supplied. Treat that output as sensitive. The default limit is 10,000 rows per snapshot with a maximum of 100,000 and a 16 MiB encoded value budget per snapshot.
• Server replay. PostgreSQL row preview reads clones directly and requires --replay-dumps for trusted dumps. dbsnap sandbox before also accepts a trusted PostgreSQL custom dump. It needs matching pg_restore, database creation permission, and compatible extensions. The sandbox shares the PostgreSQL server. MySQL/MariaDB row preview requires an explicit --docker-image mysql:8.0 or --docker-image mariadb:11 and Docker. MCP replay requires session authorization and per-call approval. Abrupt termination can leave temporary resources that need cleanup.

Prune persists retired records in metadata.json.pending_gc and retries their recorded artifact cleanup on a later prune. Shared survivor data and arbitrary untracked files are preserved. Doctor reports pending GC and untracked staging. Do not downgrade to an older binary unaware of pending_gc while it is nonempty.

Recovering an interrupted MySQL/MariaDB restore

A fresh restore creates, syncs and catalogs a pinned safety snapshot before cleanup. It preserves the database itself and replaces objects inside it. --no-safety-snapshot is rejected for fresh MySQL/MariaDB restores.

If restore fails after the recovery journal is written:

1. Keep application writers/connections and scheduled events stopped.

2. Fix the reported disk-space, connection or privilege problem. Local free space checks do not measure the database server's storage.

3. Read the recovery ID in the error or .dbsnap/mysql-restore.json, then run:

   dbsnap restore RECOVERY_ID
   

The journal stores the recovery ID as a JSON string. Other restore IDs and unpinning are refused while recovery is pending. Recovery uses the existing pinned snapshot; it does not snapshot the partially restored target. If the journal is malformed or the recovery copy is missing/corrupt, preserve the files and investigate. Do not delete the journal to bypass recovery.

After success, safety snapshots remain pinned until you review and explicitly unpin them. Restore remains non-atomic and requires trusted dumps; preflight checks do not prevent another application from reconnecting during replay.

Database support

For PostgreSQL, keep clones on the server and use dumps to transfer snapshots between machines. For MySQL/MariaDB, start with offline diff. Use diff-rows --docker-image mysql:8.0 or --docker-image mariadb:11 when you need row changes. The destination project must use the original database name when importing MySQL/MariaDB archives. During in-place restore, stop writers and scheduled events and preserve the recovery journal on failure.

Safety

• MCP permits SQLite and loopback database hosts only. The CLI also permits private-network targets by default. A local target is not necessarily safe.
• Project binding checks that the current target matches the recorded database.
• Restore checks SQLite chunks and dump artifacts before applying them and, by default, creates a safety snapshot first. If that snapshot cannot be created, restore stops. Only SQLite/PostgreSQL allow explicit opt-out; fresh MySQL/MariaDB restores require a pinned safety snapshot.
• A PostgreSQL server-side clone has a metadata fingerprint, not a content checksum. dbsnap checks that the clone exists before restore.
• PostgreSQL restore is not atomic; an interruption can require manual recovery. Clone and staged dump restores journal their cutover.
• MySQL restore is in-place and non-atomic. Stop writers/events first. Visible target connections and enabled events cause refusal before cleanup; this is not a fence against future connections. Keep the pinned snapshot and recovery journal if replay fails, including when server storage is full.
• PostgreSQL network connections require verified TLS. Set DBSNAP_PG_CA_CERT to a trusted CA PEM file if needed; use DBSNAP_PG_TLS=verify-full to require TLS on loopback connections as well.

dbsnap is intended for development workflows. Keep independent backups for data you cannot afford to lose.

Links

• Repository and full documentation
• MCP installation guide
• Testing and audit coverage
• MySQL recovery
• Development workflow and feature coverage
• Report an issue

MIT license.