@coze/cli 0.1.8 → 0.2.0-alpha.9f6611

package/skills/using-coze-cli/coze-code/references/coze-code-db.md

@@ -0,0 +1,537 @@
+# code db commands
+
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 了解认证、全局参数和安全规则。
+
+数据库管理命令索引。涵盖 Coze 空间中 Supabase 数据库的创建、查询、类型生成、Schema 导出、回滚和删除操作。
+
+## 命令导航
+
+| 文档 | 命令 | 说明 |
+|------|------|------|
+| 本文档 | `coze code db create` | 创建新数据库 |
+| 本文档 | `coze code db list` | 列出空间中的数据库 |
+| 本文档 | `coze code db get --db-id <id>` | 查看数据库详情（含连接信息） |
+| 本文档 | `coze code db query --db-id <id> --sql "..."` | 执行 SQL 查询 |
+| 本文档 | `coze code db gen-types --db-id <id>` | 生成 TypeScript 类型 |
+| 本文档 | `coze code db dump --db-id <id>` | 导出数据库 Schema 或数据 |
+| 本文档 | `coze code db rollback --db-id <id> --timestamp <ts> --confirm` | 回滚数据库到指定时间点 |
+| 本文档 | `coze code db status --db-id <id>` | 查看数据库状态和回滚信息 |
+| 本文档 | `coze code db delete --db-id <id> --confirm` | 删除数据库（不可逆） |
+
+### 共享参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--space-id <spaceId>` | 否 | 空间 ID（可选，默认从上下文读取） |
+
+> 所有 `db` 子命令都支持 `--space-id`，若未传入则从 `coze space use` 设置的上下文中读取。缺少空间 ID 时会报 `MISSING_SPACE_ID` 错误。
+
+---
+
+## db create
+
+在当前空间中创建新的 Supabase 数据库。数据库名称和凭据自动生成。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--space-id <spaceId>` | 否 | 空间 ID（默认从上下文读取） |
+
+### 推荐命令模板
+
+```bash
+# 创建数据库
+coze code db create --format json
+```
+
+### 返回值
+
+`--format json` 时返回：
+
+| 字段 | 说明 |
+|------|------|
+| `database_id` | 创建的数据库 ID |
+| `database_url` | 数据库连接 URL |
+| `status` | 数据库状态（`active` / `creating`） |
+| `database_env` | 环境（`dev` / `prod`） |
+| `created_at` | 创建时间 |
+
+### 坑点
+
+- 创建后数据库可能处于 `creating` 状态，需等待变为 `active` 后才能执行 SQL 和生成类型。
+- 空间有数据库配额限制，超出时报 `DB_QUOTA_EXCEEDED`，需先删除不用的数据库。
+
+---
+
+## db list
+
+列出当前空间中的所有数据库。支持游标分页。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--space-id <spaceId>` | 否 | 空间 ID（默认从上下文读取） |
+| `--limit <limit>` | 否 | 每页数量（1-100，默认 20） |
+| `--cursor <cursorId>` | 否 | 分页游标 |
+| `--all` | 否 | 获取所有数据库（自动翻页） |
+| `--max-pages <maxPages>` | 否 | 文本模式下最大翻页数（默认 10） |
+
+### 推荐命令模板
+
+```bash
+# 列出数据库
+coze code db list --format json
+
+# 获取所有数据库（自动翻页）
+coze code db list --all --format json
+
+# 分页查询
+coze code db list --limit 5 --cursor <cursorId> --format json
+```
+
+### 返回值
+
+返回数据库数组，每项包含：
+
+| 字段 | 说明 |
+|------|------|
+| `database_id` | 数据库 ID |
+| `name` | 数据库名称 |
+| `status` | 状态（`active` / `creating`） |
+| `database_env` | 环境（`dev` / `prod`） |
+| `created_at` | 创建时间 |
+
+> JSON 模式下还会返回 `next_cursor_id` 用于翻页。
+
+---
+
+## db get
+
+获取数据库详情，包括连接 URL 和凭据信息。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--db-id <dbId>` | 是 | 数据库 ID |
+| `--space-id <spaceId>` | 否 | 空间 ID（默认从上下文读取） |
+
+### 推荐命令模板
+
+```bash
+# 查看数据库详情
+coze code db get --db-id <databaseId> --format json
+```
+
+### 返回值
+
+`--format json` 时返回：
+
+| 字段 | 说明 |
+|------|------|
+| `database_id` | 数据库 ID |
+| `name` | 数据库名称 |
+| `database_url` | PostgreSQL 连接 URL |
+| `supabase_url` | Supabase 项目 URL |
+| `anon_key` | Supabase 匿名密钥（用于 PostgREST 访问） |
+| `status` | 状态 |
+| `database_env` | 环境 |
+| `created_at` | 创建时间 |
+
+> `database_url` 和 `anon_key` 是敏感信息，仅在 `db get` 中返回，用于应用连接和 CLI 内部操作。
+>
+> ⚠️ **安全例外**：根 `SKILL.md` 安全规则要求"禁止输出密钥到终端明文"，而 `db get` 是该规则的**受控例外**——它必然返回凭据。使用时请：
+> - 用 `--format json` 把输出**重定向到文件**（如 `> .env.local`），不要直接回显到日志或贴给最终用户；
+> - 仅在需要凭据的工作流（写 `.env`、初始化连接）中调用，其余场景改用 `db list` / `db status`（不含凭据）。
+
+---
+
+## db query
+
+在数据库上执行 SQL。支持内联 SQL、文件输入和 stdin 管道。危险操作需 `--confirm` 确认。
+
+### 核心坑点（最高优先级标注）
+
+**危险 SQL（DROP、TRUNCATE、`ALTER TABLE`、无 WHERE 的 DELETE/UPDATE）必须加 `--confirm`，否则在 JSON 模式下报错，在文本模式下弹出交互确认。**（注意：`ALTER TABLE` 虽为 `warning` 级，但同样被判为 dangerous，需要 `--confirm`。）
+
+```bash
+# 正确 ✅
+coze code db query --db-id <id> --sql "DROP TABLE old_data" --confirm
+
+# 错误 ❌（JSON 模式下会报 DB_SQL_DANGEROUS 错误）
+coze code db query --db-id <id> --sql "DROP TABLE old_data"
+```
+
+### SQL 输入优先级
+
+1. `--sql`（内联 SQL，最高优先级）
+2. `--file`（从文件读取）
+3. stdin 管道输入
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--db-id <dbId>` | 是 | 数据库 ID |
+| `--sql <sql>` | 否 | 内联 SQL（最高优先级） |
+| `--file <path>` | 否 | SQL 文件路径 |
+| `--confirm` | 否 | 确认执行危险 SQL |
+| `--space-id <spaceId>` | 否 | 空间 ID（默认从上下文读取） |
+
+> `--sql`、`--file`、stdin 三者必须提供至少一个，否则报错。
+
+### 推荐命令模板
+
+```bash
+# 执行内联 SQL
+coze code db query --db-id <id> --sql "SELECT * FROM users LIMIT 10" --format json
+
+# 执行 SQL 文件
+coze code db query --db-id <id> --file ./query.sql --format json
+
+# 通过 stdin 管道输入
+echo "SELECT 1" | coze code db query --db-id <id> --format json
+
+# 执行危险 SQL（需确认）
+coze code db query --db-id <id> --sql "DROP TABLE old_data" --confirm --format json
+```
+
+### 返回值
+
+`--format json` 时返回：
+
+| 字段 | 说明 |
+|------|------|
+| `result` | 查询结果数组（SELECT） |
+| `rows_affected` | 影响行数 |
+| `command` | SQL 命令类型（`SELECT` / `DROP` / `INSERT` 等） |
+| `warnings` | 安全警告（危险操作时非空） |
+
+### 危险 SQL 检测规则
+
+| 级别 | 模式 | 说明 |
+|------|------|------|
+| `critical` | `DROP TABLE/INDEX/SCHEMA/...` | 永久删除数据库对象 |
+| `critical` | `TRUNCATE` | 清空表所有数据 |
+| `critical` | `DELETE FROM` 无 WHERE | 删除所有行 |
+| `critical` | `UPDATE ... SET` 无 WHERE | 更新所有行 |
+| `warning` | `ALTER TABLE` | 可能导致数据丢失 |
+
+> 检测会先剥离 SQL 注释（`--` 和 `/* */`）再匹配，避免误判。
+
+---
+
+## db gen-types
+
+从数据库 Schema 生成 TypeScript 类型定义。使用 PostgREST OpenAPI 接口获取 Schema 信息。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--db-id <dbId>` | 是 | 数据库 ID |
+| `--output <path>` | 否 | 输出文件路径（默认 `types/database.ts`） |
+| `--include-schema <name>` | 否 | Schema 名称（可多次指定，默认 `public`） |
+| `--space-id <spaceId>` | 否 | 空间 ID（默认从上下文读取） |
+
+### 推荐命令模板
+
+```bash
+# 生成 public schema 的类型
+coze code db gen-types --db-id <id> --format json
+
+# 指定多个 schema
+coze code db gen-types --db-id <id> --include-schema public --include-schema auth --format json
+
+# 自定义输出路径
+coze code db gen-types --db-id <id> --output src/types/db.ts --format json
+```
+
+### 返回值
+
+`--format json` 时返回：
+
+| 字段 | 说明 |
+|------|------|
+| `output_path` | 生成的文件路径 |
+| `schemas` | 已生成类型的 schema 列表 |
+
+### 前置条件
+
+- 数据库状态必须为 `active`
+- 数据库必须有 `supabase_url` 和 `anon_key`（PostgREST 依赖）
+
+### 坑点
+
+- 生成的文件头部包含 `Auto-generated by coze code db gen-types` 注释，不要手动编辑。
+- 数据库处于 `creating` 状态时无法生成类型，需等待 `active`。
+
+---
+
+## db dump
+
+导出数据库 Schema（DDL）或数据为 SQL 文件。使用 pg-meta API 查询 information_schema。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--db-id <dbId>` | 是 | 数据库 ID |
+| `--output <path>` | 否 | 输出文件路径（默认 `db/schema.sql`） |
+| `--schema-only` | 否 | 仅导出 Schema（默认行为） |
+| `--data-only` | 否 | 仅导出数据 |
+| `--include-schema <name>` | 否 | 要导出的 schema，可重复指定（默认 `public`） |
+| `--space-id <spaceId>` | 否 | 空间 ID（默认从上下文读取） |
+
+> `--schema-only` 和 `--data-only` 互斥。不指定时默认为 `--schema-only`。
+>
+> 默认只导出 `public` schema。需要系统 schema（如 `auth`、`storage`）时必须显式 `--include-schema auth --include-schema storage` 叠加，避免产出 Supabase 内部表导致无法 replay。
+>
+> ⚠️ 不要用 `--schema` 作 schema 筛选——`--schema` 是 CLI 框架保留的全局 flag（打印命令 JSON Schema），会被拦截。
+
+### 推荐命令模板
+
+```bash
+# 导出 public schema（默认）
+coze code db dump --db-id <id> --format json
+
+# 仅导出数据
+coze code db dump --db-id <id> --data-only --format json
+
+# 指定多个 schema
+coze code db dump --db-id <id> --include-schema public --include-schema auth --format json
+
+# 自定义输出路径
+coze code db dump --db-id <id> --output backups/schema.sql --format json
+```
+
+### 返回值
+
+`--format json` 时返回：
+
+| 字段 | 说明 |
+|------|------|
+| `output_path` | 输出文件路径 |
+| `mode` | 导出模式（`schema-only` / `data-only`） |
+| `schemas` | 实际导出的 schema 列表 |
+
+### 导出内容
+
+**Schema 模式**导出：
+- `CREATE TABLE IF NOT EXISTS` 语句（含列定义、NOT NULL、DEFAULT）
+- `CREATE INDEX` 语句
+
+**Data 模式**导出：
+- `INSERT INTO` 语句（逐行生成）
+
+### 前置条件
+
+- 数据库必须有 `supabase_url` 和 `database_url`（pg-meta 依赖）
+
+---
+
+## db rollback
+
+将数据库回滚到指定时间点（PITR，Point-in-Time Recovery）。`--confirm` 为必填参数。
+
+### 核心坑点（最高优先级标注）
+
+**`--confirm` 和 `--timestamp` 都是必填参数！**
+
+```bash
+# 正确 ✅
+coze code db rollback --db-id <id> --timestamp 1713254400000 --confirm
+
+# 错误 ❌（缺少 --confirm 会报错）
+coze code db rollback --db-id <id> --timestamp 1713254400000
+```
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--db-id <dbId>` | 是 | 数据库 ID |
+| `--timestamp <timestamp>` | 是 | 目标时间戳（毫秒级 Int64 字符串） |
+| `--confirm` | 是 | 确认回滚操作 |
+| `--space-id <spaceId>` | 否 | 空间 ID（默认从上下文读取） |
+
+### 推荐命令模板
+
+```bash
+# 回滚数据库到指定时间点
+coze code db rollback --db-id <id> --timestamp 1713254400000 --confirm --format json
+
+# 回滚后检查状态
+coze code db status --db-id <id> --format json
+```
+
+### 返回值
+
+`--format json` 时返回：
+
+| 字段 | 说明 |
+|------|------|
+| `restore_history_id` | 回滚记录 ID |
+
+### 回滚状态查询
+
+回滚是异步操作，发起后使用 `coze code db status --db-id <id>` 查看进度。
+
+### 常见错误
+
+| 错误 | 说明 | 修复 |
+|------|------|------|
+| `DB_RESTORE_WINDOW_EXCEEDED` | 回滚时间超出恢复窗口 | 使用 `db status` 查看 `earliest_restore_time` |
+| `DB_RESTORE_IN_PROGRESS` | 已有回滚正在进行 | 等待当前回滚完成 |
+
+---
+
+## db status
+
+查看数据库状态，包括 PITR 回滚信息和恢复进度。
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--db-id <dbId>` | 是 | 数据库 ID |
+| `--space-id <spaceId>` | 否 | 空间 ID（默认从上下文读取） |
+
+### 推荐命令模板
+
+```bash
+# 查看数据库状态
+coze code db status --db-id <databaseId> --format json
+```
+
+### 返回值
+
+`--format json` 时返回：
+
+| 字段 | 说明 |
+|------|------|
+| `can_restore` | 是否支持 PITR 回滚 |
+| `is_restoring` | 是否正在回滚中 |
+| `earliest_restore_time` | 最早可回滚时间 |
+| `latest_restore_status` | 最近回滚状态（`restoring` / `success` / `failed`） |
+| `latest_restore_error` | 最近回滚错误信息（失败时有值） |
+| `latest_restore_start_time` | 最近回滚开始时间 |
+| `latest_restore_end_time` | 最近回滚结束时间 |
+
+### 数据库状态枚举
+
+| 状态 | 含义 |
+|------|------|
+| `active` | 正常运行 |
+| `creating` | 创建中 |
+
+### 回滚状态枚举
+
+| 状态 | 含义 |
+|------|------|
+| `restoring` | 回滚进行中 |
+| `success` | 回滚成功 |
+| `failed` | 回滚失败 |
+
+---
+
+## db delete
+
+删除数据库。**不可逆操作**，`--confirm` 为必填参数。
+
+### 核心坑点（最高优先级标注）
+
+**`--confirm` 是必填参数！不加会报错。**
+
+```bash
+# 正确 ✅
+coze code db delete --db-id <id> --confirm
+
+# 错误 ❌（缺少 --confirm 会报 DB_SQL_DANGEROUS 错误）
+coze code db delete --db-id <id>
+```
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--db-id <dbId>` | 是 | 数据库 ID |
+| `--confirm` | 是 | 确认删除 |
+| `--space-id <spaceId>` | 否 | 空间 ID（默认从上下文读取） |
+
+### 推荐命令模板
+
+```bash
+# 删除数据库
+coze code db delete --db-id <databaseId> --confirm --format json
+```
+
+### 返回值
+
+`--format json` 时返回：
+
+| 字段 | 说明 |
+|------|------|
+| `deleted` | 删除状态（`true`） |
+| `database_id` | 已删除的数据库 ID |
+
+### 注意事项
+
+- **不可逆操作**，执行前确认用户意图。
+- 用户已经明确要求删除且目标明确时可直接执行。
+
+---
+
+## 常见错误速查
+
+| 错误码 | 名称 | 说明 | 修复 |
+|--------|------|------|------|
+| E1003 | `MISSING_SPACE_ID` | 缺少空间 ID | 使用 `--space-id` 或先执行 `coze space use <spaceId>` |
+| E1007 | `DB_SQL_DANGEROUS` | 危险操作未确认 | 添加 `--confirm` 参数 |
+| E3010 | `DB_NOT_FOUND` | 数据库不存在或无权限 | 检查 `--db-id`，执行 `coze code db list` 确认 |
+| E3012 | `DB_RESTORE_WINDOW_EXCEEDED` | 回滚时间超出恢复窗口 | 使用 `db status` 查看 `earliest_restore_time` |
+| E3013 | `DB_RESTORE_IN_PROGRESS` | 已有回滚正在进行 | 等待当前回滚完成 |
+| E4002 | `DB_QUOTA_EXCEEDED` | 空间数据库配额已满 | 删除不用的数据库 |
+| E5004 | `DB_SQL_EXECUTION_FAILED` | SQL 执行失败 | 检查 SQL 语法和表结构 |
+| E5005 | `DB_CONNECTION_FAILED` | 数据库连接失败 | 检查数据库状态和网络 |
+| E5006 | `DB_GEN_TYPES_FAILED` | 类型生成失败 | 确认数据库为 `active` 状态且 PostgREST 可用 |
+| E5007 | `DB_DUMP_FAILED` | Schema 导出失败 | 检查数据库状态和权限 |
+
+## 典型工作流
+
+### 创建并使用数据库
+
+```bash
+# 1. 创建数据库
+coze code db create --format json
+# 记录返回的 database_id
+
+# 2. 等待状态变为 active
+coze code db status --db-id <id> --format json
+
+# 3. 执行建表 SQL
+coze code db query --db-id <id> --sql "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT NOT NULL)" --format json
+
+# 4. 生成 TypeScript 类型
+coze code db gen-types --db-id <id> --format json
+
+# 5. 导出 Schema 备份
+coze code db dump --db-id <id> --output backups/schema.sql --format json
+```
+
+### 回滚数据库
+
+```bash
+# 1. 检查是否可回滚
+coze code db status --db-id <id> --format json
+# 确认 can_restore 为 true，记录 earliest_restore_time
+
+# 2. 执行回滚
+coze code db rollback --db-id <id> --timestamp 1713254400000 --confirm --format json
+
+# 3. 查看回滚进度
+coze code db status --db-id <id> --format json
+# 等待 latest_restore_status 变为 success
+```