pscale sql 完全指南：非交互式 SQL 查询、角色权限、副本路由与破坏性 SQL 防护

pscale sql 完全指南非交互式 SQL 查询、角色权限、副本路由与破坏性 SQL 防护【免费下载链接】cliThe CLI for PlanetScale Database项目地址: https://gitcode.com/gh_mirrors/cli31/clipscale sql是 PlanetScale Database 官方命令行工具pscale中用于执行非交互式 SQL 查询的核心命令。它无需打开交互式 shell一条命令即可对数据库分支执行单条 SQL并自带角色权限控制reader/writer/readwriter/admin、副本路由--replica与破坏性 SQL 防护DELETE/DROP/TRUNCATE 需 --force 显式批准三大安全机制是脚本和 AI Agent 安全操作 PlanetScale 数据库的首选方式。pscale sql 是什么与 pscale shell 的核心区别pscale sql执行单条 SQL 语句后自动退出使用临时凭证ephemeral credentials适合 CI/CD 脚本、自动化运维和 AI Agent 调用而pscale shell打开的是交互式会话适合人工调试。对比项pscale sqlpscale shell交互方式单条查询执行完即退出交互式客户端mysql/psql默认角色reader只读admin适用场景脚本、Agent、自动化人工排查、调试破坏性 SQL默认拦截需--force无此拦截命令骨架来自 internal/cmd/sql/sql.go核心执行逻辑位于 internal/sqlquery/sqlquery.go。快速上手60 秒完成一次非交互式查询基本语法只需两个位置参数数据库名、分支名加必填的--query与--org# 只读查询默认 reader 角色 pscale sql mydb main --org myorg --query SELECT 1 # 机器可读的 JSON 输出 pscale sql mydb main --org myorg --format json --query SELECT * FROM users LIMIT 3 # 从副本读 pscale sql mydb main --org myorg --replica --query SELECT COUNT(*) FROM orders 注意flag 要放在位置参数之后--org是必填项。MySQL 与 PostgreSQL 的默认行为不同见 internal/sqlquery/sqlquery.goMySQLVitess默认连接主 keyspace等同primary多 keyspace 库可用--keyspace keyspace指定PostgreSQL默认连接postgres库可用--dbname name切换。角色权限4 个访问级别默认最安全的 reader--role决定临时凭证的权限级别可选值为reader、writer、readwriter、admin。与pscale shell默认 admin 不同pscale sql默认是reader——这是刻意为脚本安全做的防御式设计见 internal/cmdutil/cmdutil.go 中的ResolveAccessRole。角色能力PostgreSQL 内部映射reader默认只读pg_read_all_datawriter可写pg_write_all_datareadwriter读写pg_read_all_datapg_write_all_dataadmin全部权限postgres角色角色到内置权限的映射实现在 internal/cmdutil/cmdutil.go 的PostgresInheritedRoles# 脚本需要写入数据时显式提升角色 pscale sql mydb main --org myorg --role writer --query INSERT INTO logs (msg) VALUES (ok)⚠️ 最小权限原则能reader就用reader只有写入任务才升级writer/readwriter。副本路由用 --replica 把读流量分流到副本加上--replica后所有读操作会路由到分支的主副本primary replicas和所有只读区域read-only regions把主节点留给写入避免报表类查询拖慢线上业务flag 定义见 internal/cmd/sql/sql.go。# 副本读报表、统计类查询 pscale sql mydb main --org myorg --replica --query SELECT region, COUNT(*) FROM orders GROUP BY region两个关键细节--replica隐含只读设置副本路由时凭证角色会被自动解析为reader见 internal/cmdutil/cmdutil.go从机制上杜绝经副本通道写入的可能PostgreSQL 的实现连接用户名会自动追加|replica后缀以命中副本入口见 internal/sqlquery/sqlquery.go。进阶用 --keyspace 锁定具体分片与副本MySQL 库中--keyspace支持keyspace、keyspace/-80锁定分片、keyspace/-80replica分片 副本 tablet三种写法可把连接钉在单个分片上# 先列出所有分片 pscale sql mydb main --org myorg --query SHOW VITESS_SHARDS # 将查询固定到 -80 分片的副本上执行 pscale sql mydb main --org myorg --keyspace mykeyspace/-80replica --query SELECT * FROM t破坏性 SQL 防护DELETE / DROP / TRUNCATE 默认被拦截pscale sql内置了破坏性 SQL 防护guardrail以DELETE、DROP、TRUNCATE开头的语句不加--force一律拒绝执行。# 不带 --force会被拦截 pscale sql mydb main --org myorg --query DELETE FROM logs WHERE id 100 # 报错destructive SQL requires explicit user approval (ask the user, then re-run with --force)检测逻辑相当细致internal/sqlquery/destructive.go先剥离干扰注释--、#、/* */、字符串字面量被剔除后才做判断避免注释里的 DROP 误报多语句逐条检查以分号拆句任一语句命中即拦截识别 CTE 包装WITH x AS (...) DELETE ...这类以WITH开头的删改语句同样会被识别覆盖变体ALTER TABLE ... DROP COLUMN、MERGE ... THEN DELETE也在检测范围内。拦截后的处理分两种场景见 internal/cmd/sql/json.go输出模式行为人类模式直接打印错误信息JSON 模式输出status: action_required结构化报告含问题码DESTRUCTIVE_SQL与修复建议退出码为 1普通错误退出码为 2定义见 internal/cmdutil/errors.go退出码 结构化 JSON 的组合正是为AI Agent 设计的Agent 读到action_required必须先向用户请求批准确认后才加--force重试——这条Agent 必须先征求用户同意的规则被明确写进了命令帮助文本internal/cmd/sql/sql.go。# 用户明确批准后带 --force 重新执行 pscale sql mydb main --org myorg --force --query DELETE FROM logs WHERE id 100JSON 输出与临时凭证为自动化而生的设计--format json返回统一的Result结构status、database、branch、kindmysql/postgresql、role、replica、row_count、rows_affected、columns、rows、next_steps字段定义见 internal/sqlquery/sqlquery.go方便程序解析。安全设计同样值得一提每次执行都会动态签发一个 5 分钟 TTL 的临时分支密码PostgreSQL 为临时角色查询结束后自动删除不留任何长期凭证——实现见 internal/passwordutil/password.go 与 internal/sqlquery/sqlquery.go。速查表常用命令速览场景命令只读查询pscale sql db branch --org org --query SELECT 1副本读追加--replica写入追加--role writer锁定分片副本追加--keyspace ks/-80replica指定 PG 库追加--dbname mydb破坏性语句用户批准后追加--force 总结pscale sql用「默认只读 副本路由 破坏性拦截」三层防线让非交互式 SQL 查询既快又安全。把它接进你的 CI 流水线或 AI Agent就能放心地自动化操作 PlanetScale 数据库了。【免费下载链接】cliThe CLI for PlanetScale Database项目地址: https://gitcode.com/gh_mirrors/cli31/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考