pig postgres
pig pg 命令（别名 pig postgres）用于管理本地 PostgreSQL 服务器和数据库。它封装了 pg_ctl、psql、vacuumdb 等本地原语；集群级 Patroni 操作请使用 pig pt，编排式 PITR 请使用 pig pitr。
命令概览
服务控制（pg_ctl 封装）：
| 命令 | 别名 | 描述 | 备注 |
|---|---|---|---|
pg init | initdb, i | 初始化数据目录 | 封装 initdb |
pg start | boot, up | 启动 PostgreSQL | 封装 pg_ctl start |
pg stop | halt, down | 停止 PostgreSQL | 封装 pg_ctl stop |
pg restart | reboot | 重启 PostgreSQL | 封装 pg_ctl restart |
pg reload | hup | 重载配置 | 封装 pg_ctl reload |
pg status | st, stat | 查看服务状态 | 显示进程与相关服务状态 |
pg promote | pro | 提升备库为主库 | 封装 pg_ctl promote |
pg role | r | 检测实例角色 | 输出 primary/replica |
连接与查询：
| 命令 | 别名 | 描述 | 备注 |
|---|---|---|---|
pg psql | sql, connect | 连接到数据库 | 封装 psql |
pg ps | activity, act | 显示当前连接 | 查询 pg_stat_activity |
pg kill | k | 终止连接 | 默认 dry-run 模式 |
pg clone | 克隆单个数据库 | CREATE DATABASE ... TEMPLATE ... FILE_COPY |
数据库维护：
| 命令 | 别名 | 描述 | 备注 |
|---|---|---|---|
pg vacuum | vac, vc | 清理表 | 封装 vacuumdb |
pg analyze | ana, az | 分析表 | 封装 vacuumdb –analyze-only |
pg freeze | 冻结清理表 | 封装 vacuumdb –freeze | |
pg repack | rp | 在线重整表 | 需要 pg_repack 扩展 |
参数调优：
| 命令 | 别名 | 描述 | 备注 |
|---|---|---|---|
pg tune | tuning | 生成 PostgreSQL 调优参数 | 自动探测硬件，支持结构化输出 |
实例 Fork：
| 命令 | 别名 | 描述 | 备注 |
|---|---|---|---|
pg fork | fork init 的便捷写法 | 默认创建托管 fork，不自动启动 | |
pg fork init | create | 创建本地一次性物理副本 | 默认 /pg/data-<name> |
pg fork list | 列出托管 fork | 扫描 /pg/data-* | |
pg fork start | 启动已有 fork | 支持托管名或 --dst-data 非托管目录 | |
pg fork stop | 停止已有 fork | 支持 shutdown mode | |
pg fork rm | remove, delete | 删除 fork | 运行中的 fork 需 --stop |
日志工具：
| 命令 | 别名 | 描述 | 备注 |
|---|---|---|---|
pg log | l | 日志管理 | 父命令 |
pg log list | ls | 列出日志文件 | |
pg log tail | t, f | 实时查看日志 | tail -f |
pg log show | cat, c | 输出日志内容 | |
pg log less | vi, v | 用 less 查看 | |
pg log grep | g, search | 搜索日志 |
服务子命令（pg svc，也可写作 pg service 或 pg s）：
| 命令 | 别名 | 描述 |
|---|---|---|
pg svc start | boot, up | 启动 postgres 服务 |
pg svc stop | halt, dn, down | 停止 postgres 服务 |
pg svc restart | reboot, rt | 重启 postgres 服务 |
pg svc reload | rl, hup | 重载 postgres 服务 |
pg svc status | st, stat | 显示服务状态 |
快速入门
全局参数
以下参数适用于所有 pig pg 子命令：
| 参数 | 简写 | 默认值 | 说明 |
|---|---|---|---|
--version | -v | 自动检测 | PostgreSQL 主版本号（形如 18，17） |
--data | -D | /pg/data | 数据目录路径 |
--dbsu | -U | postgres | 数据库超级用户（或 $PIG_DBSU 环境变量） |
版本检测逻辑：
- 如果指定了
-v，使用指定 PG 大版本 - 否则从数据目录的
PG_VERSION文件读取版本 - 如果都无法获取，使用 PATH 中的默认 PostgreSQL 大版本
服务控制命令
pg init
初始化 PostgreSQL 数据目录，封装 initdb 命令。
- 校验和默认打开，除非使用
-K|--no-data-checksums显式关闭 - 优先使用平台无关的 C.UTF-8 内置 Locale （PG 17 及以上版本），如果不支持则优先使用系统的 C.UTF-8 / C Locale，都不满足时使用系统默认 Locale。
- 如果数据目录已存在，命令会拒绝执行，除非使用
-f|--force强制覆盖。如果数据目录上有 PostgreSQL 正在运行，即使使用-f|--force，命令也会拒绝执行，以防止数据丢失 - 您可以使用
--追加额外参数给initdb，例如--waldir=/wal指定 WAL 日志目录。但如果要覆盖 Locale / Encoding 等参数，建议直接使用initdb命令。
选项：
| 参数 | 简写 | 默认值 | 说明 |
|---|---|---|---|
--no-data-checksums | -K | false | 禁用数据校验和 |
--force | -f | false | 强制初始化，删除已有数据（危险！） |
--yes | -y | false | 与 --force 配合时跳过覆盖确认提示 |
pg start
使用 pg_ctl start 命令启动 PostgreSQL 服务器。
如果 PostgreSQL 由 Patroni 管理，建议使用 pig pt start 通过启动 patroni 的方式来启动。
如果 PostgreSQL 由 Systemd 管理，可以使用 pig pg svc start 来启动服务。
选项：
| 参数 | 简写 | 说明 |
|---|---|---|
--log | -l | 重定向 stdout/stderr 到日志文件 |
--timeout | -t | 等待超时（秒） |
--no-wait | 不等待启动完成 | |
--options | -O | 传递给 postgres 的选项 |
如果 PostgreSQL 已经运行，命令会提示，并打印现有 Postmaster 进程 PID，不会报错。
pg stop
使用 pg_ctl stop 命令停止 PostgreSQL 服务器。
请注意如果 PostgreSQL 由 Patroni 管理，直接使用 pg_ctl stop 停止数据库可能会导致 Patroni 认为数据库异常退出，自动重启或触发自动故障转移。
建议在 Patroni 管理的环境中使用 pig pt stop 或 pig pt svc stop 来停止 patroni ，从而停止 PostgreSQL。
选项：
| 参数 | 简写 | 默认值 | 说明 |
|---|---|---|---|
--mode | -m | fast | 关闭模式：smart/fast/immediate |
--timeout | -t | 60 | 等待超时（秒） |
--no-wait | false | 不等待关闭完成 | |
--plan | false | 只预览本地 pg_ctl stop 计划，不执行 |
关闭模式说明：
| 模式 | 说明 |
|---|---|
smart | 等待所有客户端断开后关闭 |
fast | 回滚活动事务，断开客户端，正常关闭 |
immediate | 立即终止所有进程，下次启动需要恢复 |
pg restart
使用 pg_ctl restart 重启 PostgreSQL 服务器。
选项： 与 pg stop 相同，另外支持 --options（-O）传递给 postgres。
pg reload
使用 pg_ctl reload 重载 PostgreSQL 配置。向服务器发送 SIGHUP 信号。
pg status
显示 PostgreSQL 服务器状态。此命令不仅显示 pg_ctl status 的结果，还会显示 postgres 相关进程和 Pigsty 相关服务的状态。
输出内容：
pg_ctl status输出（进程是否运行、PID 等）- PostgreSQL 进程列表（
ps -u postgres） - 相关服务状态：
postgres：PostgreSQL systemd 服务patroni：Patroni HA 管理服务pgbouncer：连接池服务pgbackrest：备份服务vip-manager：VIP 管理服务haproxy：负载均衡服务
pg promote
使用 pg_ctl promote 命令将备库提升为主库。
选项：
| 参数 | 简写 | 说明 |
|---|---|---|
--timeout | -t | 等待超时（秒） |
--no-wait | 不等待提升完成 | |
--plan | 仅预览提升计划 | |
--yes | -y | 跳过确认提示 |
pg role
检测 PostgreSQL 实例的角色（主库或备库）。
选项：
| 参数 | 简写 | 说明 |
|---|---|---|
--verbose | -V | 显示详细检测过程 |
输出说明：
primary：当前实例为主库replica：当前实例为备库unknown：无法确定实例角色
检测策略（按优先级）：
- 进程检测：检查
walreceiver、recovery等进程 - SQL 查询：执行
pg_is_in_recovery()查询（需要 PostgreSQL 运行） - 数据目录检查：检查
standby.signal、recovery.signal、recovery.conf文件
连接与查询命令
pg psql
通过 psql 连接到 PostgreSQL 数据库。
选项：
| 参数 | 简写 | 说明 |
|---|---|---|
--command | -c | 执行单条 SQL 命令 |
--file | -f | 执行 SQL 脚本文件 |
如果指定全局 -D/--data，pg psql 会以数据库超级用户读取该数据目录下的 postmaster.pid，并使用其中记录的端口和 Unix socket 目录连接该实例。
若无法读取或解析 postmaster 信息，命令会直接失败，而不是静默连接到默认实例。
pg ps
显示 PostgreSQL 当前连接。查询 pg_stat_activity 视图。
选项：
| 参数 | 简写 | 说明 |
|---|---|---|
--all | -a | 显示所有连接（包括系统进程） |
--user | -u | 按用户筛选 |
--database | -d | 按数据库筛选 |
pg kill
终止 PostgreSQL 连接。默认为 dry-run 模式，需要 -x 参数才会实际执行。
选项：
| 参数 | 简写 | 说明 |
|---|---|---|
--execute | -x | 实际执行（默认为 dry-run） |
--pid | 终止指定 PID | |
--user | -u | 按用户筛选 |
--database | -d | 按数据库筛选 |
--state | -s | 按状态筛选（idle/active/idle in transaction） |
--query | -q | 按查询模式筛选 |
--all | -a | 包括复制连接 |
--cancel | -c | 取消查询而非终止连接 |
--watch | 每 N 秒重复执行 | |
--plan | 预览执行计划，不终止连接 |
安全说明： --state 和 --query 参数会进行标识符验证，只接受简单的字母数字模式，以防止 SQL 注入。
pg clone
克隆数据库集群中的一个数据库，对于 PG 18 及以上版本优先使用 CoW 原地瞬间克隆
在当前 PostgreSQL 实例内克隆一个数据库。该命令封装 CREATE DATABASE ... TEMPLATE ... STRATEGY FILE_COPY，并会在克隆前终止源数据库上的现有会话，语义与 Pigsty 的 pgsql-db clone 工作流一致。
选项：
| 参数 | 简写 | 说明 |
|---|---|---|
--port | PostgreSQL 端口（默认 5432 或 $PG_PORT） | |
--conn-db | 执行 CREATE DATABASE 的连接库，克隆 postgres 时默认 template1 | |
--owner | 克隆后尝试修改新库 owner | |
--conn-limit | 新库连接数限制（-1 无限制，0 禁止连接） | |
--plan | 仅显示执行计划 | |
--yes | -y | 跳过确认提示 |
说明： PostgreSQL 18+ 且 file_copy_method=clone 可用时，数据库克隆可使用 CoW 语义；否则会退化为普通文件复制。该命令克隆的是单个数据库逻辑对象，不会创建新的 PostgreSQL 实例。
数据库维护命令
pg vacuum
清理数据库表。封装 vacuumdb 命令。
选项：
| 参数 | 简写 | 说明 |
|---|---|---|
--all | -a | 处理所有数据库 |
--schema | 指定 schema | |
--table | -t | 指定表名 |
--verbose | -V | 详细输出 |
--full | -F | VACUUM FULL（需要排他锁） |
安全说明： --schema 和 --table 参数会进行标识符验证，只接受有效的 PostgreSQL 标识符格式。
pg analyze
分析数据库表以更新统计信息。
选项：
| 参数 | 简写 | 说明 |
|---|---|---|
--all | -a | 处理所有数据库 |
--schema | 指定 schema | |
--table | -t | 指定表名 |
--verbose | -V | 详细输出 |
pg freeze
对数据库表执行冻结清理（vacuum freeze），防止事务 ID 回卷。
选项： 与 pg vacuum 相同（不含 --full）。
pg repack
在线重整数据库表。需要安装 pg_repack 扩展。
选项：
| 参数 | 简写 | 说明 |
|---|---|---|
--all | -a | 处理所有数据库 |
--schema | 指定 schema | |
--table | -t | 指定表名 |
--verbose | -V | 详细输出 |
--jobs | -j | 并行任务数（默认 1） |
--plan | 显示将被重整的表 |
参数调优命令
pg tune
根据当前 PostgreSQL 主版本、主机硬件资源和工作负载画像，生成一组推荐的 PostgreSQL 参数。默认自动探测 CPU、内存与数据盘容量，并以文本形式输出配置项。
选项：
| 参数 | 简写 | 默认值 | 说明 |
|---|---|---|---|
--profile | -p | oltp | 调优画像：oltp / olap / tiny / crit |
--cpu | -c | 0 | CPU 核数，0 表示自动探测 |
--mem | -m | 0 | 内存大小（MB），0 表示自动探测 |
--disk | -d | 0 | 数据盘容量（GB），0 表示自动探测 |
--max-conn | -C | 0 | 覆盖 max_connections，0 表示使用画像默认值 |
--shmem-ratio | -R | 0.25 | shared_buffers 占内存比例，取值范围 0.1 ~ 0.4 |
画像说明：
| 画像 | 适用场景 | 特点 |
|---|---|---|
oltp | 通用在线事务处理 | 平衡连接数、缓存与并行度 |
olap | 分析型负载 | 更激进地使用并行与工作内存 |
tiny | 小规格实例 | 控制内存占用与并行度 |
crit | 延迟敏感场景 | 限制并行 gather，偏向稳态响应 |
说明：
- 生成结果会随当前 PostgreSQL 主版本自动裁剪，例如
io_workers仅会在 PG 18+ 输出。 - 文本输出可直接重定向到配置片段，结构化输出适合自动化脚本消费。
- 该命令当前生成建议参数，不会直接修改数据库配置文件。
实例 Fork
pg fork
创建一个本地一次性 PostgreSQL 物理副本，适合临时分析、排障、恢复验证和开发测试。托管 fork 默认写入 /pg/data-<name>，不会注册到 Pigsty、systemd 或 Patroni；显式指定 --dst-data 时会创建非托管 fork，不会被 fork list 枚举。
创建选项：
| 参数 | 简写 | 默认值 | 说明 |
|---|---|---|---|
--dst-data | /pg/data-<name> | 非托管目标数据目录 | |
--dst-port | 自动探测 | 目标端口，从 15432 起寻找空闲端口 | |
--src-data | /pg/data 或 $PG_DATA | 源数据目录；也可用全局 pg -D/--data 设置 | |
--src-port | 5432 或 $PG_PORT | 源端口 | |
--start | -s | false | 创建后启动 fork |
--force | -f | false | 覆盖已有且已停止的目标目录，并跳过确认 |
--timeout | -t | 60 | 启动等待超时（秒） |
--yes | -y | false | 跳过确认提示 |
--plan | false | 只显示执行计划，不执行 |
管理子命令：
| 命令 | 常用参数 | 说明 |
|---|---|---|
pig pg fork list | --plan, -o json/yaml | 列出托管 fork |
pig pg fork start <name> or --dst-data <dir> | --dst-data, --dst-port, -t/--timeout, --plan | 启动已有 fork |
pig pg fork stop <name> or --dst-data <dir> | --dst-data, -m/--mode, -t/--timeout, --plan | 停止已有 fork |
pig pg fork rm <name> or --dst-data <dir> | --dst-data, --stop, -m/--mode, -t/--timeout, -f/--force, -y/--yes, --plan | 删除 fork；运行中的 fork 需 --stop |
行为说明：
- 源实例运行时，命令会使用 PostgreSQL 低级备份 API 创建一致的物理副本；源实例停止时，可执行冷复制。
- 命令会优先使用 CoW/reflink；如果只能普通复制，会在交互模式中提示空间风险并等待确认。
- 为避免误删源数据，目标目录不能是
/、/pg、源 PGDATA、自身父目录或子目录；软链接会先解析到真实路径再判断。 - 复制完成后会清理 fork 中的运行态与复制状态，并写入
fork.json。只有指定-s|--start时才会启动新实例。 - 托管 fork 必须通过名称管理；非托管 fork 需要通过
--dst-data指定目录来启动、停止或删除。
列出 fork：
pig pg fork list 扫描 /pg/data-* 并读取 fork.json。文本状态只区分 forked 与 orphan，不实时判断实例是否正在运行。
结构化输出：
日志命令
日志命令用于查看 PostgreSQL 日志文件。默认日志目录为 /pg/log/postgres，可通过 --log-dir 参数指定其他目录。默认 pg log 动作显示最新 CSV 日志快照；使用 pg log -f 或 pg log tail 实时跟踪。只有 pg log 与 pg log show 支持 -o json 将 CSV 日志行转换为 JSONL；日志快照不支持 yaml 与 json-pretty，follow/tail、less、grep 不支持结构化输出。
日志命令全局参数：
| 参数 | 说明 |
|---|---|
--log-dir | 日志目录路径（默认：/pg/log/postgres） |
--lines / -n | 显示行数（默认 50） |
--follow / -f | 跟踪最新日志（仅 pg log 父命令） |
权限处理： 如果当前用户没有权限读取日志目录，命令会自动使用 sudo 重试。
pg log
显示最新日志快照；配合 -f 时跟踪最新日志。
pg log list
列出日志目录中的日志文件。
pg log tail
实时查看日志文件（类似 tail -f）。默认查看最新的 CSV 日志文件。
选项：
| 参数 | 简写 | 默认值 | 说明 |
|---|---|---|---|
--lines | -n | 50 | 显示的行数 |
--follow | -f | false | 兼容性 no-op；tail 本身总是跟踪 |
pg log show
输出日志文件内容。
选项：
| 参数 | 简写 | 默认值 | 说明 |
|---|---|---|---|
--lines | -n | 50 | 显示的行数 |
pg log less
用 less 打开日志文件。默认定位到文件末尾（+G）。
pg log grep
搜索日志文件内容。
选项：
| 参数 | 简写 | 说明 |
|---|---|---|
--ignore-case | 忽略大小写 | |
--context | -C | 显示上下文行数 |
pg svc 子命令
pg svc（也可写作 pg service 或 pg s）提供通过 systemctl 管理 PostgreSQL 服务的功能：
别名对照：
| 命令 | 别名 |
|---|---|
pg svc start | boot, up |
pg svc stop | halt, dn, down |
pg svc restart | reboot, rt |
pg svc reload | rl, hup |
pg svc status | st, stat |
设计说明
与原生工具的关系：
pig pg 并非对 PostgreSQL 原生工具的简单封装，而是针对常用操作的上层抽象：
- 服务控制命令（init/start/stop/restart/reload/promote）调用
pg_ctl status命令除了pg_ctl status外，还显示进程和相关服务状态- 连接管理命令（psql/ps/kill）调用
psql - clone 命令调用 SQL 创建数据库副本
- 维护命令（vacuum/analyze）调用
vacuumdb - repack 命令调用
pg_repack - fork 命令使用 PostgreSQL 低级备份 API 与本地文件复制创建一次性物理副本
- 日志命令调用
tail、less、grep等系统工具 pg svc命令调用systemctl
如需使用原生工具的完整功能，可直接调用相应命令。
权限处理：
- 如果当前用户已是 DBSU：直接执行命令
- 如果当前用户是 root：使用
su - postgres -c "..."执行 - 其他用户：使用
sudo -inu postgres -- ...执行
安全性考虑：
--state、--query、--schema、--table等参数都经过标识符验证，防止 SQL 注入pg kill默认为 dry-run 模式，避免误操作pg clone会终止源数据库现有会话，建议在维护窗口使用pg fork会拒绝危险目标路径；普通复制 fallback 会提示空间风险- 日志命令在权限不足时自动使用 sudo
平台支持：
此命令专为 Linux 系统设计，部分功能依赖 systemctl。