@farhan0431/db-snap 0.3.11 → 0.3.14

package/README.md

@@ -10,7 +10,10 @@ 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
 
@@ -43,7 +46,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 +73,32 @@ 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 six tools are:
+
+| 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. |
 
 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 +111,66 @@ 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 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 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 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. PostgreSQL dump archives are not supported.
+
+## 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 +183,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 +194,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 +215,8 @@ 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)
 - [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.3.14",
+  "description": "Development database snapshots and MCP server for SQLite, PostgreSQL, and MySQL/MariaDB.",
   "license": "MIT",
   "bin": {
     "dbsnap": "bin/dbsnap.js"