⚡

PostgreSQL命令行查询工具Skill psql

这是一个PostgreSQL数据库命令行查询工具，通过psql客户端执行SQL查询和元命令。支持环境变量配置、文件执行、多种输出格式（元组、JSON），适用于数据库探索、数据分析、迁移执行和日常管理。关键词：PostgreSQL，SQL查询，数据库管理，CLI工具，psql，数据操作，迁移脚本。

后端开发 0 次安装 0 次浏览 更新于 3/2/2026

名称: psql 描述: 通过CLI运行PostgreSQL查询和元命令 版本: 1.0.0 许可证: MIT 兼容性: opencode

概述

用于对PostgreSQL数据库执行SQL查询和psql元命令的CLI工具。每个查询都通过psql CLI直接执行——无需持久连接。

前提条件

  • 已安装bun运行时
  • 已安装psql客户端
  • PostgreSQL连接环境变量已在<git-root>/.env中设置或已导出

环境变量

在您的.env文件中设置这些变量或导出它们：

变量 必填 默认值 描述
PGHOST 是 - 数据库主机
PGPORT 否 5432 数据库端口
PGDATABASE 是 - 数据库名称
PGUSER 是 - 数据库用户
PGPASSWORD 是 - 数据库密码
PGSSLMODE 否 - SSL模式（禁用、需要等）

示例.env：

PGHOST=localhost
PGPORT=5432
PGDATABASE=myapp
PGUSER=myapp
PGPASSWORD=secret
PGSSLMODE=disable

命令

查询

运行SQL查询、元命令或SQL文件。

bun .opencode/skill/psql/query.js <查询> [选项]
bun .opencode/skill/psql/query.js --file <路径> [选项]

参数：

  • query - 要执行的SQL查询或元命令

选项：

  • --file <路径> - 执行SQL文件而不是内联查询
  • --tuples - 仅元组输出（无标题和行数）
  • --timeout <毫秒> - 查询超时时间（毫秒）（默认：30000）
  • --json - 将输出包装为JSON格式
  • --help - 显示帮助

示例：

# SQL查询
bun .opencode/skill/psql/query.js "SELECT * FROM users LIMIT 5;"
bun .opencode/skill/psql/query.js "SELECT COUNT(*) FROM orders WHERE status = 'pending';"

# 元命令
bun .opencode/skill/psql/query.js "\dt"
bun .opencode/skill/psql/query.js "\d users"
bun .opencode/skill/psql/query.js "\di"
bun .opencode/skill/psql/query.js "\l"

# 执行SQL文件
bun .opencode/skill/psql/query.js --file migrations/001_create_users.sql
bun .opencode/skill/psql/query.js --file scripts/seed_data.sql

# 仅元组（用于脚本/解析）
bun .opencode/skill/psql/query.js "SELECT id FROM users;" --tuples

# 为慢查询设置更长超时时间
bun .opencode/skill/psql/query.js "SELECT * FROM large_table;" --timeout 60000

常见工作流

探索数据库架构

# 列出所有表
bun .opencode/skill/psql/query.js "\dt"

# 描述特定表
bun .opencode/skill/psql/query.js "\d users"

# 显示索引
bun .opencode/skill/psql/query.js "\di"

# 显示表的外键
bun .opencode/skill/psql/query.js "\d+ orders"

运行分析查询

# 统计记录数
bun .opencode/skill/psql/query.js "SELECT COUNT(*) FROM orders;"

# 分组聚合
bun .opencode/skill/psql/query.js "SELECT status, COUNT(*) FROM orders GROUP BY status;"

# 近期活动
bun .opencode/skill/psql/query.js "SELECT * FROM orders WHERE created_at > NOW() - INTERVAL '1 day' ORDER BY created_at DESC LIMIT 10;"

数据库管理

# 检查表大小
bun .opencode/skill/psql/query.js "SELECT relname, pg_size_pretty(pg_total_relation_size(relid)) FROM pg_catalog.pg_statio_user_tables ORDER BY pg_total_relation_size(relid) DESC LIMIT 10;"

# 检查活动连接
bun .opencode/skill/psql/query.js "SELECT count(*) FROM pg_stat_activity WHERE state = 'active';"

# 列出数据库
bun .opencode/skill/psql/query.js "\l"

运行迁移

# 执行迁移文件
bun .opencode/skill/psql/query.js --file migrations/001_create_users.sql

# 执行种子数据
bun .opencode/skill/psql/query.js --file scripts/seed.sql

输出行为

  • 查询输出直接显示在用户终端中
  • 请勿重新总结或重新格式化查询输出——用户已经可以看到它
  • 使用--tuples获得无标题的干净输出（适用于管道传输到其他工具）
  • 使用--json获得结构化输出，便于程序化解析

注意事项

  • 每个查询都是作为单独的psql调用执行的（无持久连接）
  • 元命令（以\开头）与SQL查询的工作方式相同
  • 长时间运行的查询可能需要将--timeout从默认的30秒增加
  • --tuples标志在需要解析输出或管道传输到其他命令时非常有用