pscale-sql

用途

pscale sql 用于对 PlanetScale 数据库分支执行单条 SQL 查询，使用临时凭证连接。它主要面向代理（agents）和脚本，适合非交互式的自动化场景；如果需要进行交互式探索，官方建议改用 pscale shell。

主要能力

执行单条 SQL 查询，支持机器可读输出，默认使用 reader 只读角色。
支持从副本读取：--replica。
MySQL/Vitess 场景下可指定 keyspace：--keyspace。
PostgreSQL 或 Neki 场景下可指定数据库名：--dbname，默认数据库为 postgres。
人类可读输出默认以表格展示，支持 --vertical 或查询末尾的 MySQL 风格 \G 以纵向方式呈现宽行结果；CLI 会在发送 SQL 前去除末尾的 \G 或 \g，\G 会启用纵向输出。JSON 仍是自动化场景的首选格式。
JSON 模式下的失败会返回结构化错误信封，应解析其中的机器可读 code/message 字段，而不是抓取带颜色的人类输出。

使用方式

常用命令示例：

# 只读查询，机器可读输出（默认角色为 reader）
pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"

# 从副本读取
pscale sql <database> <branch> --org <org> --format json --replica --query "SELECT count(*) FROM users"

# MySQL/Vitess：需要时指定 keyspace
pscale sql <database> <branch> --org <org> --format json --keyspace <keyspace> --query "SELECT 1"

PostgreSQL 或 Neki 场景指定数据库名（默认 postgres）：

pscale sql   --org  --format json --dbname app --query "SELECT 1"

人类可读输出示例：

pscale sql   --org  --query "SHOW VITESS_TABLETS"
pscale sql   --org  --vertical --query "SHOW REPLICA STATUS"
pscale sql   --org  --query "SHOW REPLICA STATUS\G"

标志应放在位置参数之后：

pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"

角色与安全

默认角色为 reader。
仅当用户明确要求可写操作时，才使用 --role writer、--role readwriter 或 --role admin。
包含 DELETE、DROP 或 TRUNCATE 的破坏性 SQL 会被拦截，除非传入 --force。该防护还会检测改写数据的 CTE，以及包裹破坏性语句的 EXPLAIN ANALYZE/EXPLAIN ANALYSE。MySQL 可执行注释（如 /*! DROP TABLE ... /）和按版本控制的 /!80000 DELETE ... */ 属于实际执行的 SQL，同样会被纳入安全检查，不应视为无效注释。
代理在使用 --force 前必须获得用户明确批准，并先展示确切的查询语句和目标数据库/分支/组织。

可写操作与破坏性操作示例：

# 有意的非破坏性写入，使用可写角色
pscale sql <database> <branch> --org <org> --role admin --query "UPDATE users SET disabled = true WHERE id = 123"

# 破坏性操作：仅在用户明确批准后执行
pscale sql <database> <branch> --org <org> --role admin --force --query "DELETE FROM sessions WHERE expires_at < now()"

代理工作流

确认 <org>、<database>、<branch>、引擎上下文（Vitess/MySQL 还是 Postgres/Neki），以及查询是否为只读。
只读查询优先使用 --format json，并保持默认 reader 角色。
写操作前，与用户确认目标与确切的 SQL。
未经对确切破坏性查询的明确批准，绝不添加 --force。
JSON 模式失败时解析结构化错误中的 code/message 字段。
返回简明摘要，并视情况附带行数/结果。

适用场景

代理或脚本执行只读 SQL。
收集数据、执行自动化查询。
需要机器可读 JSON 输出的自动化流程。
在获得明确批准的前提下执行受控的写操作。

连接与限制

对于 PostgreSQL 和 Neki 目标，CLI 创建的临时连接默认使用 sslmode=verify-full；除非用户有具体且经批准的诊断理由需要在命令之外更改连接行为，否则应保留该验证。
Neki 使用 Postgres 风格的临时角色；新建的临时角色可能不会立即就绪，CLI 在连接前最多等待一分钟。
pscale sql 面向单条非交互式查询；交互式探索应使用 pscale shell。

参考

pscale sql --help 的当前输出见 references/commands.md。