Skill: vastbase-vsql(实际连库执行)
scripts/vsql.py 是 vsql 的 psycopg2 实现:连接 Vastbase 执行 SQL,结果默认渲染为
markdown 表格(面向 AI/自动化阅读)。命令行参数对照官方 vsql
(VastbaseG100 V3.0.9 参考指南 > 工具参考 > vsql)。
前提
psycopg2 是硬性前提:要用 vsql,必须先安装 psycopg2-binary,没有替代方案。
检测到未安装(脚本以退出码 1 提示 未安装 psycopg2)时,唯一正确动作是安装后重试:
pip3 install psycopg2-binary # 工作区有 .venv 时: .venv/bin/pip install psycopg2-binary
安装失败(无权限/离线)就停下,告知用户"不装 psycopg2-binary 无法使用本 skill",
待用户装好后再继续。严禁自行实现 PostgreSQL 线协议、编写替代驱动/客户端、
或改用任何其他连接方式绕过——缺依赖只能靠安装解决。
(有 .venv 时优先用 .venv/bin/python3 运行脚本。)
用法
# 基本查询(markdown 表格输出)
python3 scripts/vsql.py -h <IP> -p 5432 -U vastbase -d postgres -W '<密码>' -c "SELECT version();"
# conninfo 连接串 + 脚本文件,整体一个事务,遇错即停
python3 scripts/vsql.py "host=<IP> port=5432 dbname=postgres user=vastbase password=<密码>" \
-f init.sql -1 -v ON_ERROR_STOP=1
# 元命令直接可用(\dt 支持 模式.名称 通配)
python3 scripts/vsql.py -h <IP> -p 5432 -U vastbase -W <密码> -c "\dt v_b*"
# 管道喂 SQL / 列库 / 从标准输入读密码(-2)
echo 'SELECT 1;' | python3 scripts/vsql.py -h <IP> -p 5432 -d postgres
python3 scripts/vsql.py -l -h <IP> -p 5432
printf '<密码>\n' | python3 scripts/vsql.py -2 -U vastbase -d postgres -c "SELECT 1;"
关键语义
- 密码优先级:
-W '<密码>'>-2(标准输入读一行)>VB_PASSWORD>
PGPASSWORD(libpq 原生)> 服务器要求时终端交互。 - 连接参数优先级:命令行 >
VB_HOST/VB_PORT/VB_DB/VB_USERNAME/VB_PASSWORD
环境变量 > libpq 默认值(PG_*/本地套接字)。 - 元命令:查询类(
\l \dt \di \dv \ds \d \dn \du \dg \df \dx)翻译为等价目录表
SQL 执行;\df/\du支持模式.名称/通配 过滤(\df sch.*);服务器
NOTICE/INFO 提示(如VACUUM VERBOSE明细)会打印;\copy支持括号子查询
作源与TO STDOUT/FROM STDIN直连终端/管道;本地类(\c \i \o \q \copy \timing \x \t \a \H \echo \warn \qecho \! \cd \conninfo \p \r \set \unset \?)执行客户端动作;\?查看清单。 - 单条
-c内元命令与 SQL 不可混用(vsql 同款语义),拆成多条-c;
-f/管道/交互输入不受限,可自由混排。 - 事务与退出码:连接全程自动提交(psql/libpq 同款)——语句执行即生效,
出错语句自动回滚自身、后续继续;多语句-c串作为一个事务(任一语句
出错则其余语句不再执行、整串回滚,对齐官方 vsql 的隐式事务块;单语句-c
裸执行,VACUUM/CREATE DATABASE 等因此单独可用);-1整次运行一个事务
(全有或全无);-v ON_ERROR_STOP=1遇错即停(-f/管道缺省逐语句生效、
遇错继续,需原子性务必加-1)。退出码 0 成功 / 1 连接失败或 SQL 错误 /
3 ON_ERROR_STOP 命中或 -1 整体回滚。 - 手写事务块(psql 同款,原生成组):
BEGIN/START TRANSACTION开块、
COMMIT/END/ROLLBACK收块(ROLLBACK TO SAVEPOINT、COMMIT/ROLLBACK PREPARED不收块);-f/管道/交互中开块后挂起逐语句自动提交直至收块;单条
-c内同样生效,BEGIN 前的语句与块同事务——未收块则整条-c一起回滚,
事务跨多条-c保持;块内出错保持 aborted,后续语句报
"current transaction is aborted" 直到块尾;输入结束未收块自动回滚;交互
提示符以*标记事务态。仅-1下不跟踪(psql 对-1混用显式 BEGIN
同样不保证行为)。 - 输出格式(优先级):
-HHTML >-A非对齐 > 默认 markdown;-t只出行、
-x扩展、-F/-R分隔符(支持\n \t \r \0转义,-z/-0空字节)、
-o FILE结果写文件、-L FILE同步记录日志、-q安静、-e/-a/-E各级回显。 - 远程连接注意:Vastbase 初始用户(如 vastbase)默认禁止远程登录
(FATAL: Forbid remote connection with initial user),远程请用业务用户。
能力边界(设计取舍,非缺陷)
- 交互类元命令未实现:
\e \ef \s \watch \g \gset \gexec \lo_* \sf \sv \password \pset;
未实现命令行参数:-P/-s/-S/-n/-r/-m/-C/-D/-k。 - 无
:varSQL 变量代换(\set/-v只认 ON_ERROR_STOP,其余静默接受)。 - 未指定库名时默认
postgres;默认输出 markdown(官方 vsql 为对齐表格)。 - 多语句
-c内手写BEGIN会与该串的事务包裹叠加,产生一次
"there is already a transaction in progress" 警告(psql 为隐式块静默收编),
仅表现差异,语义一致;单语句-c与-f/管道/交互中无此现象。 - 完整差异说明见
scripts/vsql.py头部文档;--help查看全部参数。
