@lark-apaas/miaoda-cli 0.1.3 → 0.1.4-alpha.abaa17f

package/dist/cli/commands/db/index.js

@@ -1,31 +1,47 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDbCommands = registerDbCommands;
+const error_1 = require("../../../utils/error");
 const index_1 = require("../../../cli/handlers/db/index");
 const shared_1 = require("../../../cli/commands/shared");
+const _env_1 = require("../../../cli/handlers/db/_env");
+function parsePositiveInt(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new error_1.AppError('ARGS_INVALID', `--limit must be a positive integer (got '${raw}')`);
+    }
+    return n;
+}
 function registerDbCommands(program) {
     const dbCmd = program
-        .command("db")
-        .description("应用数据库（PostgreSQL）的命令行操作集合。")
-        .usage("<command> [flags]")
+        .command('db')
+        .description('应用数据库（PostgreSQL）的命令行操作集合。')
+        .usage('<command> [flags]')
         // --env 注册在 db 父级，spec 把它列入 db --help 的 Global Flags；
         // leaf 命令仍各自接收 --env 值（commander 解析时父级 option 自动适用于子命令）
-        .option("--env <name>", "指定目标环境（dev / online，仅专家模式应用支持）");
+        .option('--env <name>', '指定目标环境（dev / online，仅专家模式应用支持）');
+    // 任意 leaf action 执行前先做 --env vocab 校验：用户拼错（'onlin'/'prod' 等）立即报
+    // UNKNOWN_ENV_VALUE 避免后端无意义被打到。preAction hook 拿父级 dbCmd 的 --env 值
+    // —— commander 把父级 option 自动 propagate 给子命令的 optsWithGlobals。
+    dbCmd.hook('preAction', () => {
+        const env = dbCmd.opts().env;
+        (0, _env_1.validateEnv)(typeof env === 'string' ? env : undefined);
+    });
     dbCmd.action(() => {
         dbCmd.outputHelp();
     });
     dbCmd
-        .command("sql")
-        .summary("执行任意 SQL（SELECT / DML / DDL，支持多条分号分隔）")
-        .description("执行 SQL 语句，支持 SELECT、DML、DDL 等所有标准 PostgreSQL 操作。\n" +
-        "支持通过 stdin 读取（miaoda db sql < file.sql），多条语句以分号分隔。\n" +
-        "事务控制使用 PG 原生的 BEGIN / COMMIT / ROLLBACK 语法。")
-        .usage("<query> [flags]")
-        .argument("[query]", "要执行的 SQL 语句；省略时从标准输入读取")
+        .command('sql')
+        .summary('执行任意 SQL（SELECT / DML / DDL，支持多条分号分隔）')
+        .description('执行 SQL 语句，支持 SELECT、DML、DDL 等所有标准 PostgreSQL 操作。\n' +
+        '支持通过 stdin 读取（miaoda db sql < file.sql），多条语句以分号分隔。\n' +
+        '事务控制使用 PG 原生的 BEGIN / COMMIT / ROLLBACK 语法。')
+        .usage('<query> [flags]')
+        .argument('[query]', '要执行的 SQL 语句；省略时从标准输入读取')
         .action(async function (query) {
         await (0, index_1.handleDbSql)(query, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
-        .addHelpText("after", `
+        .addHelpText('after', `
 Notes:
   - SELECT 结果超过 1000 行直接报错（RESULT_SET_TOO_LARGE），不做隐式截断。
     需要分页时请在 SQL 中用 LIMIT / OFFSET。
@@ -60,23 +76,23 @@ Examples:
 `);
     // schema 二级资源分组
     const schemaCmd = dbCmd
-        .command("schema")
-        .summary("查看数据库表结构")
-        .description("查看应用数据库的表结构信息。")
-        .usage("<command> [flags]");
+        .command('schema')
+        .summary('查看数据库表结构')
+        .description('查看应用数据库的表结构信息。')
+        .usage('<command> [flags]');
     schemaCmd.action(() => {
         schemaCmd.outputHelp();
     });
     schemaCmd
-        .command("list")
-        .summary("列出所有表的概览（表名、行数、大小等）")
-        .description("列出当前应用所有表的概览信息：表名、描述、行数、大小、列数、最近更新时间。\n" +
-        "查看单表完整结构请用 `schema get`；查看 DDL 变更历史请用 `changelog`（P1）。")
-        .usage("[flags]")
+        .command('list')
+        .summary('列出所有表的概览（表名、行数、大小等）')
+        .description('列出当前应用所有表的概览信息：表名、描述、行数、大小、列数、最近更新时间。\n' +
+        '查看单表完整结构请用 `schema get`；查看 DDL 变更历史请用 `changelog`。')
+        .usage('[flags]')
         .action(async function () {
         await (0, index_1.handleDbSchemaList)({ ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
-        .addHelpText("after", `
+        .addHelpText('after', `
 Examples:
   $ miaoda db schema list
   name      description   rows   size      columns   updated_at
@@ -96,17 +112,17 @@ Examples:
   }
 `);
     schemaCmd
-        .command("get")
-        .summary("查看单表完整结构（列定义、索引、约束）")
-        .description("查看指定表的完整结构：列定义（含类型、可空、默认值、注释）、索引、行数、大小。\n" +
-        "默认 pretty 输出 CREATE TABLE 的 SQL 文本；--json 输出结构化字段。")
-        .usage("<table> [flags]")
-        .argument("<table>", "表名（无需带 schema 前缀）")
-        .option("--ddl", "强制输出 CREATE TABLE 建表语句（pretty 默认就是 DDL，--json 时配合此 flag 返 SQL 文本）")
+        .command('get')
+        .summary('查看单表完整结构（列定义、索引、约束）')
+        .description('查看指定表的完整结构：列定义（含类型、可空、默认值、注释）、索引、行数、大小。\n' +
+        '默认 pretty 输出 CREATE TABLE 的 SQL 文本；--json 输出结构化字段。')
+        .usage('<table> [flags]')
+        .argument('<table>', '表名（无需带 schema 前缀）')
+        .option('--ddl', '强制输出 CREATE TABLE 建表语句（pretty 默认就是 DDL，--json 时配合此 flag 返 SQL 文本）')
         .action(async function (table) {
         await (0, index_1.handleDbSchemaGet)(table, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
-        .addHelpText("after", `
+        .addHelpText('after', `
 Examples:
   $ miaoda db schema get users
   CREATE TABLE users (
@@ -127,27 +143,27 @@ Examples:
 `);
     // data 二级资源分组
     const dataCmd = dbCmd
-        .command("data")
-        .summary("表数据导入导出")
-        .description("表数据的批量导入导出，适合数据备份、跨环境迁移、外部分析。")
-        .usage("<command> [flags]");
+        .command('data')
+        .summary('表数据导入导出')
+        .description('表数据的批量导入导出，适合数据备份、跨环境迁移、外部分析。')
+        .usage('<command> [flags]');
     dataCmd.action(() => {
         dataCmd.outputHelp();
     });
     dataCmd
-        .command("import")
-        .summary("从本地 CSV / JSON 文件导入数据到表")
-        .description("从本地 CSV / JSON 文件导入数据到表。整个导入是原子的——遇到任何错误（主键冲突、\n" +
-        "类型不匹配、列名不匹配等）会回滚已插入的所有行。\n" +
-        "不支持 SQL 文件，SQL 备份请用 `miaoda db sql < <文件>.sql` 回放。")
-        .usage("<file> [flags]")
-        .argument("<file>", "本地文件路径（CSV 或 JSON 格式）")
-        .option("--table <name>", "目标表名；未指定时按文件名（不含扩展名）推断（如 users.csv → users）")
-        .option("--format <fmt>", "文件格式 csv / json；未指定时按文件扩展名推断")
+        .command('import')
+        .summary('从本地 CSV / JSON 文件导入数据到表')
+        .description('从本地 CSV / JSON 文件导入数据到表。整个导入是原子的——遇到任何错误（主键冲突、\n' +
+        '类型不匹配、列名不匹配等）会回滚已插入的所有行。\n' +
+        '不支持 SQL 文件，SQL 备份请用 `miaoda db sql < <文件>.sql` 回放。')
+        .usage('<file> [flags]')
+        .argument('<file>', '本地文件路径（CSV 或 JSON 格式）')
+        .option('--table <name>', '目标表名；未指定时按文件名（不含扩展名）推断（如 users.csv → users）')
+        .option('--format <fmt>', '文件格式 csv / json；未指定时按文件扩展名推断')
         .action(async function (file) {
         await (0, index_1.handleDbDataImport)(file, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
-        .addHelpText("after", `
+        .addHelpText('after', `
 Notes:
   - 目标表必须已存在；CSV 表头 / JSON 顶层 key 必须与表字段名完全一致。
   - 导入为原子操作：遇到错误回滚所有已插入行，不会出现部分导入的中间状态。
@@ -172,19 +188,19 @@ Examples:
           \`miaoda db sql "DELETE FROM users WHERE id IN (...)"\`.
 `);
     dataCmd
-        .command("export")
-        .summary("导出表数据到本地 CSV / JSON / SQL 文件")
-        .description("把指定表的所有数据导出到本地文件，支持 CSV / JSON / SQL 三种格式。")
-        .usage("<table> [flags]")
-        .argument("<table>", "表名（无需带 schema 前缀）")
-        .option("--format <fmt>", "导出格式 csv / json / sql，默认 csv（sql 输出 INSERT 语句，可用 db sql < file.sql 回放）")
-        .option("-f, --file <path>", "输出文件路径，默认 <表名>.<格式>")
-        .option("--limit <n>", "最多导出行数（不超过 5000）")
-        .option("--force", "输出文件已存在时覆盖（默认报错）")
+        .command('export')
+        .summary('导出表数据到本地 CSV / JSON / SQL 文件')
+        .description('把指定表的所有数据导出到本地文件，支持 CSV / JSON / SQL 三种格式。')
+        .usage('<table> [flags]')
+        .argument('<table>', '表名（无需带 schema 前缀）')
+        .option('--format <fmt>', '导出格式 csv / json / sql，默认 csv（sql 输出 INSERT 语句，可用 db sql < file.sql 回放）')
+        .option('-f, --file <path>', '输出文件路径，默认 <表名>.<格式>')
+        .option('--limit <n>', '最多导出行数（不超过 5000）')
+        .option('--force', '输出文件已存在时覆盖（默认报错）')
         .action(async function (table) {
         await (0, index_1.handleDbDataExport)(table, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
-        .addHelpText("after", `
+        .addHelpText('after', `
 Notes:
   - SQL 格式生成 INSERT 语句，可用 \`miaoda db sql < <文件>.sql\` 在其他环境回放。
   - 文件已存在时默认报错（FILE_ALREADY_EXISTS），用 --force 覆盖或 -f 改路径。
@@ -206,5 +222,537 @@ Examples:
   $ miaoda db data export users
   Error: Output file 'users.csv' already exists
     hint: Use -f to specify a different path, or --force to overwrite.
+`);
+    // ── changelog ──
+    dbCmd
+        .command('changelog')
+        .summary('查看 DDL 变更历史')
+        .description('查看 DDL 变更记录（建表、改表、删表等）。默认按时间倒序显示，可按表名或时间范围过滤。')
+        .usage('[flags]')
+        .option('--table <name>', '按表名过滤')
+        .option('--since <time>', '起始时间')
+        .option('--until <time>', '截止时间')
+        .option('--change-id <id>', '按 change_id 精确查询单条变更记录（指定后只返该 ID 一条，JSON 仍保持数组）')
+        .option('--limit <n>', '返回条数上限（默认 20）', parsePositiveInt, 20)
+        .option('--cursor <token>', '从上一页返回的游标位置继续获取')
+        .option('--all', '获取全部结果，自动翻页')
+        .action(async function () {
+        await (0, index_1.handleDbChangelog)(this.optsWithGlobals());
+    })
+        .addHelpText('after', `
+Notes:
+  - DDL 变更由系统自动记录，不可关闭，无需单独开启。
+  - 默认输出展示摘要（summary），完整 SQL 原文（statement）通过 --json 获取。
+
+Examples:
+  # 列出近期变更（statement 截断展示，完整 SQL 用 --json 获取）
+  $ miaoda db changelog
+  change_id          changed_at             operator   target_table   change_type             summary
+  1862462453263587   2026-04-16 13:24:59    zqy        users          ALTER_AUDIT_RETENTION   修改记录日志周期
+  1861814222210116   2026-04-08 20:12:37    zqy        users          CREATE_TABLE            创建并修改数据表
+
+  # 按条件过滤
+  $ miaoda db changelog --table users --since 2026-04-01
+  $ miaoda db changelog --limit 5
+
+  # --json 输出包含完整 statement
+  $ miaoda db changelog --limit 1 --json
+  {
+    "data": [{
+      "change_id": "1861814222210116",
+      "changed_at": "2026-04-08T20:12:37Z",
+      "operator": "zqy",
+      "target_table": "users",
+      "change_type": "CREATE_TABLE",
+      "summary": "创建并修改数据表",
+      "statement": "CREATE TABLE ... ;"
+    }],
+    "next_cursor": null,
+    "has_more": false
+  }
+`);
+    // ── audit ──
+    const auditCmd = dbCmd
+        .command('audit')
+        .summary('表级数据审计开关与查询')
+        .description('配置表的数据审计 (enable/disable/retention)，查询审计状态与日志。')
+        .usage('<command> [flags]');
+    auditCmd.action(() => {
+        auditCmd.outputHelp();
+    });
+    auditCmd
+        .command('status')
+        .summary('查看审计开关状态')
+        .description('查看表的审计开关状态。不指定表则显示全部。')
+        .usage('[table] [flags]')
+        .argument('[table]', '表名；省略时返所有已配置审计的表')
+        .action(async function (table) {
+        await (0, index_1.handleDbAuditStatus)(table, this.optsWithGlobals());
+    })
+        .addHelpText('after', `
+Examples:
+  # 全部表
+  $ miaoda db audit status
+  table     enabled   enabled_at            retention
+  users     yes       2026-04-01 08:00:00   30d
+  orders    no        —                     —
+  products  yes       2026-03-15 10:30:00   forever
+
+  # 单表
+  $ miaoda db audit status users
+       Table:  users
+     Enabled:  yes
+  Enabled at:  2026-04-01 08:00:00
+   Retention:  30d
+
+  # --json（全部表）
+  $ miaoda db audit status --json
+  {
+    "data": [
+      {"table": "users", "enabled": true, "enabled_at": "2026-04-01T08:00:00Z", "retention": "30d"},
+      {"table": "orders", "enabled": false, "enabled_at": null, "retention": null},
+      {"table": "products", "enabled": true, "enabled_at": "2026-03-15T10:30:00Z", "retention": "forever"}
+    ]
+  }
+
+  # --json（单表）
+  $ miaoda db audit status users --json
+  {
+    "data": {
+      "table": "users",
+      "enabled": true,
+      "enabled_at": "2026-04-01T08:00:00Z",
+      "retention": "30d"
+    }
+  }
+`);
+    auditCmd
+        .command('enable')
+        .summary('启用表审计')
+        .description('开启指定表的审计，记录每次 INSERT / UPDATE / DELETE 操作。')
+        .usage('<table> [flags]')
+        .argument('<table>', '目标表名')
+        .option('--retention <period>', '审计日志保留时长，可选 7d / 30d / 180d / 360d / forever', '7d')
+        .action(async function (table) {
+        await (0, index_1.handleDbAuditEnable)(table, this.optsWithGlobals());
+    })
+        .addHelpText('after', `
+Notes:
+  - 开启审计会占用额外存储空间，计入应用的存储配额。
+  - 用 \`miaoda db quota\` 查看用量；用 \`miaoda db audit disable\` 或调整 --retention 控制开销。
+
+Examples:
+  # 默认保留 7 天
+  $ miaoda db audit enable orders
+  ✓ Audit enabled for table 'orders' (retention: 7d)
+
+  # 指定保留时长 / 永久保留
+  $ miaoda db audit enable orders --retention 180d
+  $ miaoda db audit enable orders --retention forever
+
+  # non-TTY
+  $ miaoda db audit enable orders | cat
+  OK Audit enabled for table 'orders' (retention: 7d)
+
+  # --json
+  $ miaoda db audit enable orders --retention 180d --json
+  {
+    "data": {
+      "table": "orders",
+      "enabled": true,
+      "retention": "180d"
+    }
+  }
+
+  # 报错：已经开启
+  $ miaoda db audit enable orders
+  Error: Audit is already enabled for table 'orders'
+    hint: Use \`miaoda db audit status orders\` to check current retention,
+          or run this command with a different --retention to update.
+
+  # 报错：retention 值非法
+  $ miaoda db audit enable orders --retention 60d
+  Error: Invalid retention '60d'
+    hint: Allowed values: 7d, 30d, 180d, 360d, forever.
+`);
+    auditCmd
+        .command('disable')
+        .summary('关闭表审计')
+        .description('关闭指定表的审计。')
+        .usage('<table> [flags]')
+        .argument('<table>', '目标表名')
+        .action(async function (table) {
+        await (0, index_1.handleDbAuditDisable)(table, this.optsWithGlobals());
+    })
+        .addHelpText('after', `
+Examples:
+  $ miaoda db audit disable orders
+  ✓ Audit disabled for table 'orders'
+
+  # non-TTY
+  $ miaoda db audit disable orders | cat
+  OK Audit disabled for table 'orders'
+
+  # --json
+  $ miaoda db audit disable orders --json
+  {
+    "data": {
+      "table": "orders",
+      "enabled": false
+    }
+  }
+
+  # 报错：未开启
+  $ miaoda db audit disable orders
+  Error: Audit is not enabled for table 'orders'
+    hint: Use \`miaoda db audit status\` to see which tables have audit enabled.
+`);
+    auditCmd
+        .command('list')
+        .summary('查询审计日志')
+        .description('查询一个或多个表的审计日志记录。多表查询时输出会带 target_table 列标识每条记录所属的表。')
+        .usage('<table...> [flags]')
+        .argument('<tables...>', '一个或多个表名')
+        .option('--since <time>', '起始时间')
+        .option('--until <time>', '截止时间')
+        .option('--limit <n>', '返回条数上限（默认 20）', parsePositiveInt, 20)
+        .option('--cursor <token>', '从上一页返回的游标位置继续获取')
+        .option('--all', '获取全部结果，自动翻页')
+        .action(async function (tables) {
+        await (0, index_1.handleDbAuditList)(tables, this.optsWithGlobals());
+    })
+        .addHelpText('after', `
+Notes:
+  - 默认输出展示变更摘要（summary），完整变更快照（details 含 before / after）通过 --json 获取。
+  - 多表查询时不可用的表（未开启审计或不存在）会被跳过而非整体失败，全部不可用才返回错误。
+  - 退出码：只要有任何一张表有结果即为 0（跳过不算失败）；全部不可用才为 1。
+
+Examples:
+  # 单表
+  $ miaoda db audit list users --limit 5
+
+  # 多表（输出带 target_table 列区分来源）
+  $ miaoda db audit list users orders --limit 5
+
+  # 按时间范围
+  $ miaoda db audit list users --since 2026-04-14 --limit 10
+
+  # --json（含完整 details / before / after）
+  $ miaoda db audit list users --limit 1 --json
+  {
+    "data": [{
+      "event_id": "01525416B44F87001509F20CD000000002",
+      "event_time": "2026-04-15T10:30:00Z",
+      "target_table": "users",
+      "type": "UPDATE",
+      "operator": "alice",
+      "details": {
+        "before": {"id": "ef4db805-...", "age": 28},
+        "after":  {"id": "ef4db805-...", "age": 29}
+      }
+    }],
+    "next_cursor": null,
+    "has_more": false
+  }
+
+  # 报错：单表未开启
+  $ miaoda db audit list orders
+  Error: Audit is not enabled for table 'orders'
+    hint: Run \`miaoda db audit enable orders\` to start recording changes.
+
+  # 多表全部不可用才整体报错
+  $ miaoda db audit list orders invoices
+  Error: No audit data available for any of the specified tables
+    hint: Check audit status with \`miaoda db audit status\`.
+`);
+    // ── migration ──
+    const migrationCmd = dbCmd
+        .command('migration')
+        .summary('多环境管理（dev / online，仅专家模式应用）')
+        .description('init 拆分双环境，diff 预览待发布变更，apply 把 dev 同步到 online。')
+        .usage('<command> [flags]');
+    migrationCmd.action(() => {
+        migrationCmd.outputHelp();
+    });
+    migrationCmd
+        .command('init')
+        .summary('初始化多环境模式（dev / online）')
+        .description('初始化多环境模式（dev / online）。初始化后，dev 环境的数据库结构变更需要经 `migration apply` ' +
+        '应用到 online；online 将无法直接更改数据库结构（仍可进行数据 DML 操作）。')
+        .usage('[flags]')
+        .option('--sync-data', '启用时将现有数据同步一份到 dev 环境')
+        .option('-y, --yes', '跳过确认提示直接执行')
+        .action(async function () {
+        await (0, index_1.handleDbMigrationInit)(this.optsWithGlobals());
+    })
+        .addHelpText('after', `
+Notes:
+  - 多环境模式一旦启用无法恢复为单库模式，请确认后再启用。
+
+Examples:
+  # TTY 下会要求确认
+  $ miaoda db migration init
+  ? This action is irreversible. Initialize multi-env (dev / online)? (y/N) y
+  ✓ Multi-env initialized (dev / online)
+
+  # --yes 跳过确认（Agent / CI 场景）
+  $ miaoda db migration init --sync-data --yes
+  ✓ Multi-env initialized, data synced to dev
+
+  # non-TTY
+  $ miaoda db migration init --yes | cat
+  OK Multi-env initialized (dev / online)
+
+  # --json
+  $ miaoda db migration init --yes --json
+  {
+    "data": {
+      "status": "initialized",
+      "environments": ["dev", "online"],
+      "data_synced": false
+    }
+  }
+
+  # 报错：已经初始化过
+  $ miaoda db migration init
+  Error: Multi-env is already initialized
+    hint: Run \`miaoda db migration diff\` to view pending changes.
+`);
+    migrationCmd
+        .command('diff')
+        .summary('预览 dev → online 待发布变更')
+        .description('预览 dev → online 的待发布变更。只读预览，不会实际发布。')
+        .usage('[flags]')
+        .action(async function () {
+        await (0, index_1.handleDbMigrationDiff)(this.optsWithGlobals());
+    })
+        .addHelpText('after', `
+Examples:
+  $ miaoda db migration diff
+  dev → online (2 changes):
+
+    ALTER TABLE users ADD COLUMN avatar_url text;
+    CREATE INDEX idx_users_avatar ON users(avatar_url);
+
+  # --json
+  $ miaoda db migration diff --json
+  {
+    "data": {
+      "from": "dev",
+      "to": "online",
+      "changes": [
+        {"type": "ALTER_TABLE",  "table": "users", "statement": "ALTER TABLE users ADD COLUMN avatar_url text;"},
+        {"type": "CREATE_INDEX", "table": "users", "statement": "CREATE INDEX idx_users_avatar ON users(avatar_url);"}
+      ]
+    }
+  }
+
+  # 报错：无待发布变更
+  $ miaoda db migration diff
+  Error: No pending changes between dev and online
+    hint: Make schema changes in dev first (e.g. \`miaoda db sql "ALTER TABLE ..." --env dev\`).
+
+  # 报错：多环境未初始化
+  $ miaoda db migration diff
+  Error: Multi-env is not initialized
+    hint: Run \`miaoda db migration init\` to set up multi-env first.
+`);
+    migrationCmd
+        .command('apply')
+        .summary('将 dev 的变更发布到 online（单事务原子）')
+        .description('将 dev 的变更发布到 online。')
+        .usage('[flags]')
+        .option('-y, --yes', '跳过确认提示直接执行')
+        .action(async function () {
+        await (0, index_1.handleDbMigrationApply)(this.optsWithGlobals());
+    })
+        .addHelpText('after', `
+Notes:
+  - 该操作会直接改动线上数据库，建议先用 \`migration diff\` 确认变更。
+  - 变更以单事务执行：多条 DDL 任何一条失败整批回滚，online 保持原状态。
+  - 退出码：0 表示全部成功；1 表示已回滚。
+
+Examples:
+  # TTY 下会要求确认
+  $ miaoda db migration apply
+  ? Apply 2 changes to online? (y/N) y
+  ✓ Applied dev → online (2 changes)
+
+  # --yes 跳过确认
+  $ miaoda db migration apply --yes
+  ✓ Applied dev → online (2 changes)
+
+  # non-TTY
+  $ miaoda db migration apply --yes | cat
+  OK Applied dev -> online (2 changes)
+
+  # --json
+  $ miaoda db migration apply --yes --json
+  {
+    "data": {
+      "status": "applied",
+      "from": "dev",
+      "to": "online",
+      "changes_applied": 2
+    }
+  }
+
+  # 报错：无待发布变更
+  $ miaoda db migration apply
+  Error: No pending changes to apply
+    hint: Make schema changes in dev first, then run \`miaoda db migration diff\` to preview.
+
+  # 报错：多环境未启用
+  $ miaoda db migration apply
+  Error: Multi-env is not initialized
+    hint: Run \`miaoda db migration init\` to set up multi-env first.
+`);
+    // ── recovery（PITR）──
+    const recoveryCmd = dbCmd
+        .command('recovery')
+        .summary('基于时间点恢复（PITR）')
+        .description('把数据库整体恢复到指定时间点，diff 预览影响范围，apply 不可逆覆盖。')
+        .usage('<command> [flags]');
+    recoveryCmd.action(() => {
+        recoveryCmd.outputHelp();
+    });
+    recoveryCmd
+        .command('diff')
+        .summary('预览恢复到指定时间点的影响范围')
+        .description('预览恢复到指定时间点的影响范围（受影响的表、数据变更量、预计耗时）。只读预览，不改动数据。')
+        .usage('<timestamp> [flags]')
+        .argument('<timestamp>', '目标时间')
+        .action(async function (target) {
+        await (0, index_1.handleDbRecoveryDiff)(target, this.optsWithGlobals());
+    })
+        .addHelpText('after', `
+Notes:
+  - 超出可恢复窗口的时间点会报错，错误信息中会标注当前可恢复窗口。
+
+Examples:
+  # TTY pretty
+  $ miaoda db recovery diff 2026-04-15T10:00:00Z
+  Recovery preview (→ 2026-04-15T10:00:00Z):
+
+    tables affected: 2
+    users:   +3 rows, -1 row, ~5 rows modified
+    orders:  table will be restored (was dropped at 10:25:00)
+
+    estimated time: ~30s
+
+  # non-TTY（管道，TAB 分列）
+  $ miaoda db recovery diff 2026-04-15T10:00:00Z | cat
+  Recovery preview (-> 2026-04-15T10:00:00Z):
+  tables_affected	2
+  users	+3 rows, -1 row, ~5 rows modified
+  orders	table will be restored (was dropped at 10:25:00)
+  estimated_time	30
+
+  # --json
+  $ miaoda db recovery diff 2026-04-15T10:00:00Z --json
+  {
+    "data": {
+      "target": "2026-04-15T10:00:00Z",
+      "tables_affected": 2,
+      "changes": [
+        {"table": "users",  "inserted": 3, "deleted": 1, "modified": 5},
+        {"table": "orders", "action": "restore_table", "dropped_at": "2026-04-15T10:25:00Z"}
+      ],
+      "estimated_seconds": 30
+    }
+  }
+
+  # 无变更（目标时间点与当前状态一致）
+  $ miaoda db recovery diff 2026-04-15T14:00:00Z
+  Recovery preview (→ 2026-04-15T14:00:00Z):
+
+    No changes — database is already at this state.
+
+  # 超出可恢复窗口
+  $ miaoda db recovery diff 2026-04-05T10:00:00Z
+  Error: Timestamp is outside the recoverable window
+    hint: Current recoverable window: 2026-04-09T12:00:00Z ~ 2026-04-16T12:00:00Z
+          (limited by last migration apply at 2026-04-09T12:00:00Z)
+
+`);
+    recoveryCmd
+        .command('apply')
+        .summary('将数据库恢复到指定时间点的状态')
+        .description('将数据库恢复到指定时间点的状态。')
+        .usage('<timestamp> [flags]')
+        .argument('<timestamp>', '目标时间')
+        .option('-y, --yes', '跳过确认提示直接执行')
+        .action(async function (target) {
+        await (0, index_1.handleDbRecoveryApply)(target, this.optsWithGlobals());
+    })
+        .addHelpText('after', `
+Notes:
+  - 该操作会覆盖当前数据且不可撤销，建议先用 \`recovery diff\` 预览影响。
+  - 恢复过程是原子的：中途失败时数据库回到操作前的状态，不会出现部分恢复。
+  - 退出码：0 表示完成；1 表示已回滚。
+
+Examples:
+  # TTY 下会要求确认
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z
+  ? Restore database to 2026-04-15T10:00:00Z? This will overwrite current data. (y/N) y
+  ✓ Database restored to 2026-04-15T10:00:00Z (2 tables affected, 30s elapsed)
+
+  # --yes 跳过确认
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z --yes
+  ✓ Database restored to 2026-04-15T10:00:00Z (2 tables affected, 30s elapsed)
+
+  # non-TTY
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z --yes | cat
+  OK Database restored to 2026-04-15T10:00:00Z (2 tables affected, 30s elapsed)
+
+  # --json
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z --yes --json
+  {
+    "data": {
+      "status": "restored",
+      "target": "2026-04-15T10:00:00Z",
+      "tables_affected": 2,
+      "elapsed_seconds": 30
+    }
+  }
+
+  # 超出可恢复窗口
+  $ miaoda db recovery apply 2026-04-05T10:00:00Z
+  Error: Timestamp is outside the recoverable window
+    hint: Current recoverable window: 2026-04-09T12:00:00Z ~ 2026-04-16T12:00:00Z
+          Run \`miaoda db recovery diff <ts>\` within this window to preview impact.
+
+  # 并发冲突（已有恢复任务在执行）
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z
+  Error: Another recovery is already in progress
+    hint: Wait for the current recovery to finish. Started at 2026-04-16T12:30:00Z.
+`);
+    // ── quota ──
+    dbCmd
+        .command('quota')
+        .summary('查看数据库的存储用量与限额')
+        .description('查看数据库的存储用量、配额和表数量。')
+        .usage('[flags]')
+        .action(async function () {
+        await (0, index_1.handleDbQuota)(this.optsWithGlobals());
+    })
+        .addHelpText('after', `
+Examples:
+  $ miaoda db quota
+      Storage:  14.9 MB / 1 GB (1.5%)
+       Tables:  3
+        Views:  10
+
+  # --json
+  $ miaoda db quota --json
+  {
+    "data": {
+      "storage_used_bytes": 15623782,
+      "storage_quota_bytes": 1073741824,
+      "usage_percent": 1.5,
+      "tables": 3,
+      "views": 10
+    }
+  }
 `);
 }