# @farhan0431/db-snap 中文文档

规范地址：https://npmcn.com/package/%40farhan0431/db-snap/

版本：0\.4\.4
npm 元数据更新时间：2026-11-06T06:00:37.563Z
中文译文更新时间：2026-11-14T10:30:17.829Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40farhan0431/db-snap
原文对照：https://npmcn.com/package/%40farhan0431/db-snap/?lang=original
项目主页：https://github.com/farhan0431/db-snap#readme
源码仓库：https://github.com/farhan0431/db-snap

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：52.3 MB，9 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=16
- 运行依赖：0 个
- 首次发布：2026-11-03T03:32:59.520Z
- 最新版本发布：2026-11-06T06:00:37.384Z
- 近 30 天下载量：2156（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

为SQLite,PostgreSQL,和MySQL/MariaDB开发数据库快照和MCP服务器.

## 安装

```sh
npm install @farhan0431/db-snap
```

也可以使用：`pnpm add @farhan0431/db-snap`、`yarn add @farhan0431/db-snap`、`bun add @farhan0431/db-snap`

## README

# dbsnap (英语)

**用于地方发展和AI编码代理的数据库检查站.**

在迁移或批量编辑前保存快照,然后恢复计划 数据,如果需要滚回。 从终端使用 dbsnap 或连接其 内置的 MCP 服务器为 AI 助手.

支助 **SQL 点**, (中文(简体) ), **邮递SQL**,以及 **MySQL/马里亚DB**Npm 软件包 捆绑为 Windows x64、 macOS Intel 和 Apple Silicon 预建的二进制 Linux x64 (glibc and musl)和ARM64 (glibc).

**MySQL/MariaDB恢复了原始数据库上的作品.** 停止应用程序 联系,作家, 和预定的活动先。 恢复是非原子和 需要贴上安全图 中断的恢复必须恢复 在另一个恢复之前的快照; 参见下面的恢复步骤 .

## 安装

需要节点.js 16或后.

可移植档案、服务器行预览、 Git 输出和 PostgreSQL 堆放 沙盒需要dbsnap v.0.4.1或更后.

v. 4.2 绑定 `init` ,查找本地客户端 土生土长地点,然后 `diff-rows --show-values` 选择 Git 样式输出 当未给出格式时.

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

或者在没有全局安装的情况下运行 :

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

## 移民排练和CI

使用 dbsnap 来捕捉恢复点, 运行对可支配的迁移 开发或建立数据库,并在 展开 CLI 以脚本运行, 内置的 MCP 服务器给出编码 特工人员进入检查站和检查工具.

明确指向沙盒上的移民跑道 保持生产 在你的现有部署和复原中推出和生产备份 系统。 在共享环境中使用消毒数据.

## 快开始

在包含您的开发的工程根中运行这些命令 数据库 :

```bash
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
```

目标分辨率是 `--db`,然后处理 `DATABASE_URL`,然后是项目 `.env`, (中文(简体) ), 然后是常见的 SQLite 路径。 选择一个 明确数据库,使用 `dbsnap init --db ./prisma/dev.db`。检查目标 与 `dbsnap status` 在恢复前:恢复更改了活数据库.

快照和元数据 `.dbsnap/` 在你的项目。 目录是 添加到 `.gitignore` 初始化期间.

## 与 AI 助手使用

在兼容客户端中将 dbsnap 注册为 MCP 服务器 。 例如,添加 以下是您的项目 `.cursor/mcp.json`数字 :

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

重新启动客户端并请求其运行 `dbsnap_status` 确认数据库 在做出改变之前。 服务器还曝光创建,列表,恢复, 和普鲁纳快照。 它从工作目录中解决项目,所以 在您想要保护的项目中启动它 。 目前来源披露了11个工具:

| MCP 工具 | 目的 |
| --- | --- |
| `dbsnap_status` | 检查目标、引擎和快照存储器. |
| `dbsnap_create_snapshot` | 保存快照, 可选择提供 `tag`。 。 。 . |
| `dbsnap_list_snapshots` | 列出可用的还原点 . |
| `dbsnap_diff` | 比较所支持的快照 `from` 财务报告和审定财务报表 `to`。 。 。 . |
| `dbsnap_restore_snapshot` | 恢复选定的 `tag_or_id`,或最新快照. |
| `dbsnap_prune` | 粗体正整数 `keep`;被钉住的快照活下来了. |
| `dbsnap_verify` | 请检查快照散列/ 大小/ 重排, 或克隆存在; 没有 SQL 重放 . |
| `dbsnap_doctor` | 报告连通性,日记,待发GC和未跟踪文件. |
| `dbsnap_diff_live` | 保存并保留一个活检点,然后与 `from`。 。 。 . |
| `dbsnap_diff_rows` | 使用 `from`, (中文(简体) ), `to`,以及 `table`。 。 。 . |

成果包括文本加结构 `ok`, (中文(简体) ), `message`,可选键入 `data` 财务报告和审定财务报表 广义错误代码 。 快照创建返回数据中准确的ID. 说明 描述行为,但不替换会话权限或引出.

恢复和prune在MCP中默认被禁用. 用于服务器 会话,从 `dbsnap mcp --allow-destructive`。每项行动都需要 通过MCP客户端支持引出批准;否则使用CLI.

要配置明确启用的会话, 请将服务器参数更改为 `["mcp", "--allow-destructive"]`. 授权会议不批准个人 操作。 您的 MCP 客户端必须在场并返回确认 每一个恢复或发作.

`dbsnap init` 还写 `.agents/skills/dbsnap/SKILL.md` 在项目. 该技能是否自动被加载取决于 AI 客户端; 技能 文件与MCP服务器是独立的集成. 初始化保存已有的技能文件, 而不是覆盖本地文件 定制. 更新已安装的二进制不刷新已存在的 file; 升级时对照寄存器当前技能审查.

## 图标

| 命令 | 目的 |
| --- | --- |
| `dbsnap init` | 将项目绑入数据库 . |
| `dbsnap status` | 检查数据库和快照存储 . |
| `dbsnap save [tag]` | 创建快照; 标记是可选的 . |
| `dbsnap rehearse before --fail-on-drop-table -- npx prisma migrate deploy` | 在一个保留的 SQLite/PostgreSQL 沙盒上重排一个信任的迁移 . |
| `dbsnap save before -m "Before migration" --git-branch` | 用本地便条保存, 并记录可用的 Git 分支 . |
| `dbsnap tag before baseline` | 重命名快照标签 . |
| `dbsnap rm baseline` | 删除一个没有绑定的快照 . |
| `dbsnap list` | 列出快照ID和标签. |
| `dbsnap restore [tag-or-id]` | 还原快照; 省略最新选择器 . |
| `dbsnap rollback` | 恢复最新的快照 . |
| `dbsnap prune --keep 5` | 移除更古老的快照并保留最新的5个. |
| `dbsnap diff before after` | 比较 SQLite, PostgreSQL 克隆, 或 MySQL/ MariaDB 垃圾快照图和行数 . |
| `dbsnap pin <tag-or-id>` | 保护快照不被刷新; 使用 `unpin` 移除保护. |
| `dbsnap unpin <tag-or-id>` | 查看快照后删除保护 . |
| `dbsnap prune --all` | 删除所有未绑定的快照 . |
| `dbsnap save tag --method dump` | 创建可移植 PostgreSQL 垃圾快照 . |
| `dbsnap verify [id-or-tag]` | 检查一个或所有活动快照; 完整性/ 存在性不是一个恢复测试 . |
| `dbsnap doctor` | 诊断连接/ 恢复并报告未跟踪的文件而不删除它们 . |
| `dbsnap recover` | 恢复回收日记;模棱两可的PostgreSQL状态需要检查. |
| `dbsnap exec -- npm run db:migrate` | 儿童命令前的检查站;失败时保留,不自动回滚. |
| `dbsnap diff-live before` | 抓取并保留当前状态,然后进行比较. |
| `dbsnap diff-live before --ephemeral` | 比较而不保留恢复点 . |
| `dbsnap diff-rows before after --table users` | 按主键计算 默认限制为一万行 v0.4.1 添加服务器预览和 Git 风格输出. |
| `dbsnap sandbox before --output experiment.db` | Fork SQLite 输入新文件; 现有文件永远不会被覆盖 . |
| `dbsnap sandbox before` | 创建一个独立的 PostgreSQL 克隆,记录在 `sandboxes.json`。 。 。 . |
| `dbsnap sandbox before --docker-image mysql:8.0` | 明确隔离的 MySQL 服务器; 使用 `mariadb:11` 马里亚DB。 需要多克帮忙. |
| `dbsnap sandbox-list` | 列出所记录的沙盒,其源快照,以及资源状态. |
| `dbsnap sandbox-remove CONTAINER_ID` | 在验证项目所有权后删除新建的 Docker 沙盒 . |
| `dbsnap diff-report before after --fail-on-drop-table` | JSON是用来自动化的 3号出口意味着一个表格被移除. |

`dbsnap list --json` 财务报告和审定财务报表 `dbsnap status --json` 提供机器可读输出. 剪接的快照还能活下来 `prune`,包括: `--all`。 。 。 .

撤销特定更改时使用已记录的ID。 复制标记可能是 模棱两可. `rollback` 财务报告和审定财务报表 `restore` 没有选择者选择最新的 shapt,可以是前作恢复的自动安全快照.

## 快照 diff

v0.4.4 彩排提供一个沙盒连接到一个值得信赖的印花机和 报告计划/计算变化。 它保留了沙盒资源以及之前/之后 需要检查的快照,并丢弃了孩子的输出. 校验相机 使用它的环境连接。 命令具有用户权限和 能够选择其他连接。 MCP 需要会话授权和逐个调用 核准。 MySQL/MariaDB的排练和自动取出沙盒的工作正在进行中. 见 [排练指南](https://github.com/farhan0431/db-snap/blob/main/docs/REHEARSE.md) 用于超时限制,退出代码和清理.

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

Diff 比较 **快照**,而不是当前实时数据库。 SQLite 比较 计划对象和行数。 PostgreSQL 克隆 diff 比较表格/视图 定义和行数。 MySQL/ MariaDB diff 读取已验证的标准垃圾堆 离线,包括多线 `INSERT` 数据,并比较表格定义 和行数。 它不会重放 SQL 到目标.

等行计数并不意味着等行数据. 单个行内容不是 比较。 PostgreSQL diff 排除索引、限制、例行和触发; MySQL/MariaDB diff 排除了观点,常规,触发和事件. 不支持 INSERT格式产生出错. 0.4.0版本及以后可比较两个版本 PostgreSQL 卸载离线文件 `pg_restore`: 全归档计划 从列清单的COPY数据中进行的更改和表数,不包括所有权, 权限、行内容和序列值。 混合克隆/存档 diff 是 不支持 .

`diff-rows` 额外支持 SQLite 添加/删除/更新的计数 打印值。 它需要明确的非 NULL 主密钥和匹配列 布局, 拒绝上面的预览 `--limit` (最多十万个). 服务器引擎行 diff 未执行. `diff-live` 使用存储并可能短暂使用栅栏 PostgreSQL 连接,因为它创建了常规保留快照.

## 检查站、诊断和沙盒实验

`verify` 财务报告和审定财务报表 `doctor` 打印 JSON。 核查失败退出非零。 医生 报告其报告失败的探测器,并不自动修复任何东西. `recover` 读取现有的 MySQL 日记的ID或应用清晰的 PostgreSQL 日记恢复。 它不修复已停止的数据库服务器或选择一个 任意恢复点。 SQLite 没有服务器恢复日志 .

`exec` 直接产出一个没有外壳的程序,首先会保存一个检查站. 快照失败阻止了执行. 儿童不及格者保留检查站和 返回其ID、退出代码和恢复命令;父退出非零。 产出 返回到每流64个基B. `--db` 选择检查点数据库,而不是 您的外部程序将使用数据库; 有意设置其环境. 任意命令执行是CLI唯一的,而不是MCP工具.

SQLite和PostgreSQL克隆沙盒让实验瞄准独立数据. 将您的迁移/应用程序明确连接到返回的文件/数据库. 清理是关闭沙盒连接后的手工操作 。 MySQL/马里亚DB 沙盒 需要明确 `--docker-image mysql:8.0` 或者说 `mariadb:11`: 一个单独的多克 服务器以原计划名称导入已核实的垃圾堆, 网络已禁用, 没有公布的端口/主机挂载/来源证书 。 使用 `docker exec` 用于 SQL 试验,然后明确取出返回的容器。 失败 导入只删除新建的容器。 页:1 支持从信任的 PostgreSQL 自定义垃圾堆中重放沙盒 。 见工作流程 下面的指南.

### 可移植归档和 Git 风格行预览

这些命令需要v. 4.1或以后.

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

-   **存档传输.** 导入验证校验和登记新的快照 在目的地目录。 恢复是分开的。 存档包含 数据库内容,所以保持其私有性,只接受可信赖的档案. PostgreSQL 克隆导出需要匹配 `pg_dump`. MySQL/马里亚DB 需要 目的地的原始数据库名称.
-   **行预览.** 使用带有明确主键的表格。 JSON 和 MCP 软件 返回计数。 Git 输出在布局不同时显示方案变化 当布局匹配并显示已存储行值 `--show-values` 提供. 将输出视为敏感。 默认限制为每快照一万行 每个快照最多可有10万个且有16个米B编码值预算.
-   **服务器重放 .** PostgreSQL 行预览直接读取克隆并需要 `--replay-dumps` 被信任的垃圾场. `dbsnap sandbox before` 还接受 信任的 PostgreSQL 自定义垃圾堆 。 它需要匹配 `pg_restore`数据库 创建权限, 以及兼容的扩展 。 沙盒分享 PostgreSQL 服务器. MySQL/ MariaDB 行预览需要明确 `--docker-image mysql:8.0` 或者说 `--docker-image mariadb:11` 还有多克. MCP重放需要会话授权和逐个调用批准. 发光 终止可以留下需要清理的临时资源.

普鲁纳一直保持着退休记录 `metadata.json.pending_gc` 并重复他们的 记录了文物清理情况 共享幸存者数据和任意性 未跟踪文件被保存 。 医生报告 GC和未跟踪运行. 不要降级到一个不知道的老二进制 `pending_gc` 而不为所欲为.

## 恢复中断的 MySQL/ MariaDB 恢复

新的还原创建、同步和目录 清净相. 它保存了数据库本身并替换了里面的物体. `--no-safety-snapshot` 对于新鲜的 MySQL/MariaDB 恢复,则被拒绝.

如果恢复日志被写入后恢复失败 :

1.  保留应用程序作者/连接和计划事件停止.
    
2.  解决已报告的磁盘空间、连接或特权问题。 当地免费 空间检查不测量数据库服务器的存储.
    
3.  在错误中读取回收编号或 `.dbsnap/mysql-restore.json`,然后运行 :
    
    ```bash
    dbsnap restore RECOVERY_ID
    ```
    

日记将恢复ID存储为JSON字符串. 其他恢复身份证明和 在等待追回时拒绝解皮。 恢复使用现有的 被绑定的快照; 它不会快照部分恢复的目标 . 如果日记有缺陷或恢复副本缺失/损坏,请保存 档案和调查。 不删除要绕过回收的日记 .

成功后,安全快照会一直被固定 直到你审查并明确 解开他们。 恢复为非原子状态,需要可信赖的垃圾堆;飞行前 检查并不妨碍另一个应用程序在重放时重新连接.

## 数据库支持

| 数据库 | 抓图并恢复 | V. 4.1 预览和沙盒 | 所需资源 |
| --- | --- | --- | --- |
| SQL 点 | 在线备份, 带有已复制块 。 恢复到现有的数据库文件 . | 主键行预览和沙盒作为新文件. | 已存在的 SQLite 文件 . |
| 邮递SQL | 用于本地迭代的服务器侧克隆或用于传输的自定义堆放. 垃圾堆在切换前会恢复重放. | 直接读取克隆行 。 在明确请求时重放信任的自定义垃圾堆 。 创建来自任一种类的沙盒. | 用于服务器侧操作的数据库创建权限 。 匹配 - 主要 `pg_dump` 财务报告和审定财务报表 `pg_restore` 为了垃圾场. |
| MySQL/马里亚DB | 逻辑堆放有常规,触发,事件. 现场恢复使用被钉住的安全拷贝和日记. | 离线表计划/ Count diff. 使用多克进行行预览和沙盒. | 兼容本地客户端 `PATH`,用于一致性的交易表,以及用于在沙盒中重放的多克. |

对于 PostgreSQL , 请在服务器上保留克隆并使用垃圾堆传输快照 在机器之间 对于 MySQL/MariaDB , 请从离线开始 `diff`启用 `diff-rows --docker-image mysql:8.0` 或者说 `--docker-image mariadb:11` 当你 需要修改行 。 目标项目必须使用原始数据库 名称,用于导入 MySQL/MariaDB 档案。 在现场恢复期间,停止 编剧和预定的事件,并保存了故障的复苏期刊.

## 安全问题

-   MCP只允许SQLite和回放数据库主机. 国家劳工局也允许 默认的私人网络目标。 当地的目标不一定安全.
-   项目绑定检查, 当前的目标匹配记录的数据库 .
-   在应用前恢复检查 SQLite 块和倾倒文物,默认情况下, 先创建安全快照. 如果无法创建该快照, 请恢复 停下来。 只有SQLite/PostgreSQL允许明确选择退出;新鲜的MySQL/MariaDB 恢复需要贴上安全快照.
-   PostgreSQL 服务器侧克隆有元数据指纹,而不是内容 校验和. dbsnap 检查复制在恢复前是否存在.
-   PostgreSQL 恢复不是原子;中断需要手动 复原。 克隆人和舞台垃圾可以恢复日记的剪接.
-   MySQL还原是位相和非原子相. 先停止写作/活动. 可见 目标连接和启用事件在清理前导致拒绝; 这是 而不是与未来联系的围栏。 保持被绑的快照和复苏 如果重放失败, 包括服务器存储已满.
-   PostgreSQL网络连接需要经过验证的TLS. 设定 `DBSNAP_PG_CA_CERT` 需要时可信任的 CAPEM 文件; 使用 `DBSNAP_PG_TLS=verify-full` 要求 还有回路连接的TLS.

dbsnap用于开发工作流程. 保持独立备份 数据.

## 链接

-   [仓库和完整文件](https://github.com/farhan0431/db-snap)
-   [MCP 安装指南](https://github.com/farhan0431/db-snap/blob/main/INSTALL.md)
-   [测试和审计范围](https://github.com/farhan0431/db-snap/blob/main/docs/TESTING.md)
-   [MySQL 恢复](https://github.com/farhan0431/db-snap/blob/main/docs/MYSQL-RESTORE.md)
-   [发展工作流程和专题报道](https://github.com/farhan0431/db-snap/blob/main/docs/DEVELOPMENT-WORKFLOW.md)
-   [报告问题](https://github.com/farhan0431/db-snap/issues)

麻省理工学院执照.

## 常见问题

### @farhan0431/db-snap 是什么？

为SQLite,PostgreSQL,和MySQL/MariaDB开发数据库快照和MCP服务器\.

### 如何安装 @farhan0431/db-snap？

在项目目录运行 npm install @farhan0431/db-snap，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 dbsnap，可以用 npx dbsnap 直接运行。

### @farhan0431/db-snap 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/farhan0431\_\_db-snap 是否存在。

### @farhan0431/db-snap 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @farhan0431/db-snap 可以商用吗？

@farhan0431/db-snap 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @farhan0431/db-snap 的下载量有多少？

根据 npm 官方下载统计，@farhan0431/db-snap 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,156 次，日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @farhan0431/db-snap 还在维护吗？

最新版本 0\.4\.4 发布于 2026/11/06（8 天前）；至今共发布 12 个版本，其中过去 12 个月发布了 12 个；首次发布于 2026/11/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。