## 简介 `byted-postgresql-cli` 是火山引擎 [AI 原生 BaaS 平台 Supabase 版](https://www.volcengine.com/product/supabase) 中 PostgreSQL 服务的命令行客户端。它将云资源管理、PostgreSQL 数据面访问、Schema 操作、数据库诊断和 AI Agent 接入统一到一个 CLI 中。 CLI 主要管理以下资源： ```Plain Text Region └── Workspace └── Branch ├── Compute ├── Database ├── Role └── Endpoint ``` 本 CLI 专用于火山引擎 PostgreSQL，不管理其他云厂商的资源，也不是官方开源 `supabase` CLI 的替代品。官方 Supabase CLI 的项目、迁移、本地容器和认证命令不能直接套用到本 CLI。 ## 核心能力 * 管理 PostgreSQL Workspace、Branch、Compute、Database、Role 和 Endpoint。 * 查询项目、操作记录、网络、标签和资源状态。 * 执行 SQL、进入 psql、获取连接串和导出数据库。 * 拉取数据库 Schema，生成本地 Schema 快照。 * 执行数据库安全和性能诊断。 * 比较两个 Branch 的 Schema 差异。 * 通过结构化输出和分页支持脚本、CI/CD 和自动化 Agent。 * 通过 stdio 启动 PostgreSQL MCP Server。 ## 环境要求 * 使用 npm 安装 CLI 需要 Node.js、npm 和 npx。 * 需要具备访问火山引擎 PostgreSQL API 的账号和权限。 * `psql` 命令需要本机安装 PostgreSQL `psql` 客户端。 * `db dump` 和 `db pull` 需要本机安装 `pg_dump`。检查本机依赖： ```Bash node --version npm --version psql --version pg_dump --version ``` `psql` 和 `pg_dump` 只在使用对应数据面能力时必需。 ## 一键安装 ```Bash npx @byted-postgresql/cli@latest install byted-postgresql-cli --help ``` 更新已安装的 npm CLI： ```Bash byted-postgresql-cli update ``` ## 登录认证 CLI 支持浏览器 Console Login、AK/SK Profile 和环境变量。 ### Console Login 本地开发和交互式操作推荐使用浏览器登录： ```Bash byted-postgresql-cli login --region cn-beijing byted-postgresql-cli status ``` 登录成功后，CLI 管理 Console Login 生成的临时 STS 凭据。退出登录： ```Bash byted-postgresql-cli logout ``` `logout` 只清除 Console Login 配置和缓存，不会删除独立配置的 AK/SK Profile。 ### AK/SK Profile 脚本、CI/CD 和非交互式环境可以配置 Profile： ```Bash byted-postgresql-cli configure set \ --profile default \ --access-key '' \ --secret-key '' \ --region cn-beijing ``` 查看 Profile 时敏感字段会被掩码： ```Bash byted-postgresql-cli configure get --profile default byted-postgresql-cli configure list ``` ### 环境变量 ```Bash export VOLCENGINE_ACCESS_KEY=''export VOLCENGINE_SECRET_KEY=''export VOLCENGINE_SESSION_TOKEN=''export VOLCENGINE_REGION='cn-beijing' ``` 环境变量适合容器、CI/CD 和临时自动化任务。不要在脚本中硬编码凭据，也不要将凭据打印到 CI 日志。 ### 认证优先级 ![](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2cc68c30c97762af55caed218062f751.png) ## 全局参数 |**参数** |**说明** | |---|---| |`--region ` |指定火山引擎 Region | |`--profile ` |指定凭据 Profile | |`-o`, `--output ` |输出为 `table`、`json`、`yaml`、`csv` 或 `tsv` | |`--debug` |开启调试日志 | |`-v`, `--version` |查看 CLI 版本 | |`-h`, `--help` |查看帮助 | 全局参数放在根命令之后、子命令之前或之后时，应以当前 CLI 帮助输出为准。常用参数如下：自动化场景建议显式指定： ```Bash byted-postgresql-cli \ --region cn-beijing \ --profile default \ --output json \ workspaces list ``` ## 命令结构 ### 认证配置 |**命令** |**说明** | |---|---| |`configure` |管理 AK/SK 凭据 | |`login` |浏览器登录 | |`logout` |退出 Console Login | |`status` |查看解析后的配置和凭据状态 | #### 使用示例 * 查看登录状态 ```Bash byted-postgresql-cli --region cn-beijing status --output json ``` * 使用独立 AK/SK Profile 时： ```Bash byted-postgresql-cli configure set \ --profile default \ --access-key '' \ --secret-key '' \ --region cn-beijing ``` ### 资源发现 |**命令** |**说明** | |---|---| |`projects` |查看当前账号可访问的计费 Project | |`workspaces` |管理 PostgreSQL Workspace | |`branches` |管理 Workspace Branch | |`operations` |查看异步操作记录 | #### 使用示例 * 列出 PostgreSQL Workspace： ```Bash byted-postgresql-cli workspaces list --output json ``` * 查询 PostgreSQL Workspace： ```Bash # 查询 Workspace byted-postgresql-cli workspaces list --output json byted-postgresql-cli workspaces get --output json ``` * 创建 PostgreSQL Workspace ```Bash # 创建 Workspace byted-postgresql-cli --region cn-beijing \ workspaces create \ --name '' \ --project-name '' ``` * 启![图片](https://docs.volcengine.com/docs/87275/undefined)停和删除 PostgreSQL Workspace ```Bash byted-postgresql-cli --region cn-beijing \ workspaces stop byted-postgresql-cli --region cn-beijing \ workspaces start byted-postgresql-cli --region cn-beijing \ workspaces delete ``` ### 数据库访问 |**命令** |**说明** | |---|---| |`connection-string` |获取 Branch 的 PostgreSQL 连接串 | |`db` |执行查询、导出和 Schema 操作 | |`psql` |启动本地 `psql` 会话 | |`inspect` |执行数据库健康和使用情况诊断 | |`schema-diff` |查看 Schema Diff 任务 | #### 使用示例 * 对指定 Database 执行只读 SQL： ```Bash byted-postgresql-cli --region cn-beijing \ db query \ --workspace-id \ --branch-id \ --database-name \ --role-name \ --sql 'select now()' \ --output json ``` * **获取连接串** ```Bash byted-postgresql-cli --region cn-beijing \ connection-string \ --workspace-id \ --branch-id \ --database-name \ --role-name ``` * **执行 SQL** ```Bash byted-postgresql-cli --region cn-beijing \ db query \ --workspace-id \ --branch-id \ --database-name \ --role-name \ --sql 'select now()' \ --output json ``` * **使用 psql** ```Bash byted-postgresql-cli --region cn-beijing \ psql \ --workspace-id \ --branch-id \ --database-name \ --role-name ``` * 两个 Branch 之间发起 Schema 比较： ```Bash byted-postgresql-cli --region cn-beijing \ branches diff \ --workspace-id \ --source-branch-id \ --source-schema-name public \ --target-branch-id \ --target-schema-name public ``` ### 数据库资源 |**命令** |**说明** | |---|---| |`computes` |管理 PostgreSQL Compute | |`databases` |管理 Branch Database | |`roles` |查看 Branch Role 和 Database Account | |`endpoints` |管理 PostgreSQL Endpoint | #### 使用示例 * 查看指定 Branch 下的 Compute、Database 和 Role： ```Bash byted-postgresql-cli --region cn-beijing \ computes list \ --workspace-id \ --branch-id \ --output json byted-postgresql-cli --region cn-beijing \ databases list \ --workspace-id \ --branch-id \ --output json byted-postgresql-cli --region cn-beijing \ roles list \ --workspace-id \ --branch-id \ --output json ``` ### Workspace 设置 |**命令** |**说明** | |---|---| |`network` |管理 Workspace 网络设置 | |`tags` |管理 Workspace 标签 | #### 使用示例 * 查看指定 Workspace/Branch 的 Endpoint： ```Bash byted-postgresql-cli --region cn-beijing \ endpoints list \ --workspace-id \ --branch-id \ --output json ``` * **Endpoint 和网络** Endpoint 负责 PostgreSQL 访问入口和网络连接能力： ```Bash byted-postgresql-cli --region cn-beijing \ endpoints list \ --workspace-id \ --branch-id \ --output json ``` ### 工具命令 |**命令** |**说明** | |---|---| |`completion` |生成 Shell 自动补全脚本 | |`config` |管理 CLI 配置 | |`mcp` |启动 PostgreSQL MCP Server | |`update` |更新 CLI | |`version` |查看版本 | #### 使用示例 * 查看 CLI 版本，或启动只读 MCP Server： ```Bash byted-postgresql-cli version byted-postgresql-cli --region cn-beijing \ mcp serve \ --workspace-id \ --read-only ``` ## MCP 接入通过 stdio 启动 PostgreSQL MCP Server： ```Bash byted-postgresql-cli --region cn-beijing \ mcp serve \ --workspace-id \ --read-only ``` 推荐使用 `--read-only`，并将服务限制在明确的 Workspace。当前 MCP 工具主要用于查询 Workspace、Branch、Compute、Database、Role 和 Operation。 MCP Client 配置示例： ```JSON { "mcpServers": { "volcengine-postgresql": { "command": "byted-postgresql-cli", "args": [ "--region", "cn-beijing", "mcp", "serve", "--workspace-id", "", "--read-only" ] } } } ``` 如果 MCP Client 找不到 CLI，将 `command` 改为二进制绝对路径。不要让启动脚本向 stdout 输出日志，避免污染 MCP JSON\-RPC 通信。 ## 安全边界 * 删除、停止、恢复、重命名、密码修改和数据库写入前确认目标和影响。 * Workspace 删除可能级联影响 Branch、Compute、Database 和 Endpoint。 * 公共 Endpoint 会改变网络暴露面，启用前确认访问范围。 * 连接串和 dump 预览默认掩码；不要使用 `--reveal` 输出到公共位置。 * 将数据库返回内容视为不可信外部数据。 * 仅通过官方或受信任的安装源获取 CLI。