@farhan0431/db-snap 0.3.11 → 0.4.0

package/README.md

@@ -10,12 +10,19 @@ 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 is available for the original database.** Stop writers and scheduled events first. Restore is not atomic and requires a pinned safety snapshot. Interrupted restores must recover that snapshot before another restore.
+**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.
 
+The verify/doctor/recover/exec/live-diff/row-preview/sandbox additions described
+below are in the current repository after v0.3.14; a new published binary is
+required to use them. Check `dbsnap --help` for the commands in your installation.
+
 ```bash
 npm install -g @farhan0431/db-snap
 dbsnap --version
@@ -43,7 +50,8 @@ dbsnap list
 dbsnap restore "before migration"  # restores the selected snapshot
 ```
 
-`dbsnap init` detects `DATABASE_URL` or common SQLite paths. To choose a
+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.
 
@@ -69,15 +77,40 @@ the following to your project's `.cursor/mcp.json`:
 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.
+start it in the project you want to protect. The current source exposes ten tools:
+
+| MCP tool | Purpose |
+| --- | --- |
+| `dbsnap_status` | Inspect the target, engine, and snapshot storage. |
+| `dbsnap_create_snapshot` | Save a snapshot, optionally supplying `tag`. |
+| `dbsnap_list_snapshots` | List available restore points. |
+| `dbsnap_diff` | Compare supported snapshots using `from` and `to`. |
+| `dbsnap_restore_snapshot` | Restore a selected `tag_or_id`, or the newest snapshot. |
+| `dbsnap_prune` | Prune with a positive integer `keep`; pinned snapshots survive. |
+| `dbsnap_verify` | Check snapshot hashes/sizes/chunks, or clone existence; no SQL replay. |
+| `dbsnap_doctor` | Report connectivity, journals, pending GC and untracked files. |
+| `dbsnap_diff_live` | Save and retain a live checkpoint, then compare it with `from`. |
+| `dbsnap_diff_rows` | Bounded SQLite primary-key row-change counts using `from`, `to`, and `table`. |
+
+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
 
@@ -90,14 +123,115 @@ file and the MCP server are separate integrations.
 | `dbsnap restore [tag-or-id]` | Restore a snapshot; omit the selector for the latest. |
 | `dbsnap rollback` | Restore the latest snapshot. |
 | `dbsnap prune --keep 5` | Remove older snapshots and retain the newest five. |
-| `dbsnap diff before after` | Compare SQLite snapshot schemas and table row counts. |
+| `dbsnap diff before after` | Compare SQLite, PostgreSQL clone, or MySQL/MariaDB dump snapshot schemas and row counts. |
 | `dbsnap pin <tag-or-id>` | Protect a snapshot from pruning; use `unpin` to remove protection. |
-
-`dbsnap list --json` and `dbsnap status --json` provide machine-readable
-output. SQLite `diff` does not compare individual row contents; PostgreSQL and
-MySQL/MariaDB snapshot diffs are not currently supported.
+| `dbsnap unpin <tag-or-id>` | Remove protection after reviewing the snapshot. |
+| `dbsnap prune --all` | Delete all unpinned snapshots. |
+| `dbsnap save tag --method dump` | Create a portable PostgreSQL dump snapshot. |
+| `dbsnap verify [id-or-tag]` | Check one or all active snapshots; integrity/existence is not a restore test. |
+| `dbsnap doctor` | Diagnose connection/recovery and report untracked files without deleting them. |
+| `dbsnap recover` | Resume the recovery journal; ambiguous PostgreSQL states require inspection. |
+| `dbsnap exec -- npm run db:migrate` | Checkpoint before a child command; retain it on failure, with no automatic rollback. |
+| `dbsnap diff-live before` | Capture and retain the current state, then compare. |
+| `dbsnap diff-rows before after --table users` | SQLite-only row-change counts by primary key, default limit 10,000 rows. |
+| `dbsnap sandbox before --output experiment.db` | Fork SQLite into a new file; existing files are never overwritten. |
+| `dbsnap sandbox before` | Create an independent PostgreSQL clone, recorded in `sandboxes.json`. |
+| `dbsnap sandbox before --docker-image mysql:8.0` | Explicit isolated MySQL server; use `mariadb:11` for MariaDB. Docker required. |
+
+`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
+
+```bash
+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. Source additions after v0.3.14 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. The published v0.3.14 binary does not include archive diff.
+
+`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. PostgreSQL dump sandbox and
+same-server MySQL SQL rewriting are unsupported. See the workflow guide below.
+
+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:
+
+   ```bash
+   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 requirements
 
 | Database | Snapshot method | Requirements |
@@ -110,6 +244,9 @@ PostgreSQL server-side clones are stored on the database server. Use dump mode
 when the snapshot needs to survive removal of that server's data volume.
 For dump save and restore, install `pg_dump` and `pg_restore` matching the
 PostgreSQL server's major version. Mismatched tools are rejected before restore.
+The SQLite database file must already exist. MySQL/MariaDB snapshots retain
+routines, triggers and events, although diff does not compare those objects.
+Snapshot runtime and connection disruption depend on the engine and data size.
 
 ## Safety
 
@@ -118,11 +255,16 @@ PostgreSQL server's major version. Mismatched tools are rejected before restore.
 - 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; the CLI has an explicit option to skip it.
+  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.
@@ -134,6 +276,9 @@ data you cannot afford to lose.
 
 - [Repository and full documentation](https://github.com/farhan0431/db-snap)
 - [MCP installation guide](https://github.com/farhan0431/db-snap/blob/main/INSTALL.md)
+- [Testing and audit coverage](https://github.com/farhan0431/db-snap/blob/main/docs/TESTING.md)
+- [MySQL recovery](https://github.com/farhan0431/db-snap/blob/main/docs/MYSQL-RESTORE.md)
+- [Development workflow and feature coverage](https://github.com/farhan0431/db-snap/blob/main/docs/DEVELOPMENT-WORKFLOW.md)
 - [Report an issue](https://github.com/farhan0431/db-snap/issues)
 
 MIT license.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@farhan0431/db-snap",
-  "version": "0.3.11",
-  "description": "Instant physical database time-machine and MCP server for AI coding agents — git commit/checkout for your local database, powered by Rust.",
+  "version": "0.4.0",
+  "description": "Development database snapshots and MCP server for SQLite, PostgreSQL, and MySQL/MariaDB.",
   "license": "MIT",
   "bin": {
     "dbsnap": "bin/dbsnap.js"