Apache Cloudberry 常用 CLI 命令与工具详解

详解 Apache Cloudberry 2.1.0 常用命令行工具，覆盖 psql、gpstart/gpstop/gpstate、gpconfig、gpinitsystem、gprecoverseg 的真实用法与回显。

Apache CloudberryApache Cloudberry2026/10/14

Apache Cloudberry 常用 CLI 命令与工具详解

目标：把 Apache Cloudberry 2.1.0 日常运维最常用的命令行工具讲清楚——psql/createdb 怎么连库建库、gpstart/gpstop 怎么启停、gpstate 怎么看状态、gpconfig 怎么管参数、gpinitsystem/gprecoverseg/gpinitstandby 怎么初始化与恢复。每条命令都配有实测 --help 回显与操作结果。本文回显取自 Apache Cloudberry 2.1.0-incubating（PostgreSQL 14.4 内核）单机集群实测。

一、环境信息

项目实测值 / 说明
数据库版本Apache Cloudberry 2.1.0-incubating，内核 PostgreSQL 14.4
客户端版本psql (Apache Cloudberry) 14.4、createdb (Apache Cloudberry) 14.4
集群规模1 Coordinator（5432）+ 2 Primary（6000/6001）+ 2 Mirror（7000/7001）
工具目录/usr/local/cloudberry-db/bin（共 81 个可执行文件）
环境文件/usr/local/cloudberry-db/cloudberry-env.sh
环境变量GPHOME=/usr/local/cloudberry-db、COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1
运行用户gpadmin

说明：Cloudberry 的工具分两类——一类是 PostgreSQL 原生客户端（psql、createdb、pg_dump 等，语义与 PG 一致），一类是 gp 前缀的 MPP 管理工具（gpstart、gpstop、gpstate、gpconfig、gpinitsystem 等），后者负责整个集群而非单实例。

二、工具概览

实测 /usr/local/cloudberry-db/bin 下的管理类工具如下（节选）：

createdb  gpactivatestandby  gpaddmirrors  gpcheckcat  gpcheckperf  gpconfig  \
gpdeletesystem  gpdemo  gpexpand  gpfdist  gpinitstandby  gpinitsystem  gpload  \
gplogfilter  gpmemreport  gpmovemirrors  gppkg  gprecoverseg  gpshrink  \
gpssh  gpssh-exkeys  gpstart  gpstate  gpstop  gpsync  psql  pg_dump  pg_dumpall

下表按用途归类最常用的工具。

工具用途作用对象
psql交互式 SQL 客户端单连接
createdb创建数据库Coordinator
gpstart启动整个集群全集群
gpstop停止/重启/重载集群全集群
gpstate查看集群与 Segment 状态全集群
gpconfig统一查看/修改集群参数全集群
gpinitsystem初始化集群全集群
gpinitstandby初始化备 CoordinatorCoordinator + 备节点
gprecoverseg恢复失效的 Primary/Mirror指定 Segment
gpcheckperf硬件/网络性能校验各节点
gpssh批量在各节点执行命令各节点
gpfdist外部表并行加载服务加载节点

解读：gpinitsystem/gpstart/gpstop/gpstate/gpconfig 是「初始化 + 启停 + 查状态 + 管参数」的运维四件套；gprecoverseg/gpinitstandby 用于高可用；gpcheckperf/gpssh 用于部署前校验。

三、前置条件

使用任何 gp* 工具前，都必须以 gpadmin 登录并 source 环境文件。

sudo -iu gpadmin
source /usr/local/cloudberry-db/cloudberry-env.sh
export COORDINATOR_DATA_DIRECTORY=/data/coordinator/gpseg-1
echo "$GPHOME"
which gpstart gpstate gpconfig

实测回显：

/usr/local/cloudberry-db
/usr/local/cloudberry-db/bin/gpstart
/usr/local/cloudberry-db/bin/gpstate
/usr/local/cloudberry-db/bin/gpconfig

解读：source cloudberry-env.sh 把 bin/ 加入 PATH 并设置 GPHOME；COORDINATOR_DATA_DIRECTORY 让工具自动定位 Coordinator 实例，省去 -d 参数。

四、各工具详解

本节逐个工具给出真实 --help 回显与典型用法。

4.1 psql：交互式 SQL 客户端

psql 是连接 Coordinator 执行 SQL 的标准客户端。查看版本与帮助：

psql --version
psql -d postgres -c "SELECT current_user, version();"

实测回显：

psql (Apache Cloudberry) 14.4
 current_user |                                                                                             version
--------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 gpadmin      | PostgreSQL 14.4 (Apache Cloudberry 2.1.0-incubating build bdf90c5518f) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04.2) 11.4.0, 64-bit compiled on Apr 27 2026 11:21:44
(1 row)

解读：连接 Coordinator 后执行任何 SQL；-c 直接执行一条语句并返回，-d 指定数据库。远程连接用 psql -h <CoordinatorIP> -p 5432 -U gpadmin -d postgres。

💡 技术拓展：Cloudberry 的 SQL 客户端选择——

客户端形态特点适用场景
psql（本文）命令行轻量、脚本化、随包自带运维/自动化/排障
DBeaver图形化跨库、可视化建模数据分析、日常查询
JDBC/ODBC 驱动编程接口应用集成（PG 协议兼容）应用开发

Cloudberry 兼容 PostgreSQL 协议，凡支持 PG 的客户端/驱动都可用；本文用官方自带 psql。

4.2 createdb：创建数据库

createdb --version
createdb cbdbtest
psql -d postgres -c "\l cbdbtest"

实测回显：

createdb (Apache Cloudberry) 14.4
                                                  List of databases
   Name    |  Owner  | Encoding |   Collate   |    Ctype    | Access privileges
-----------+---------+----------+-------------+-------------+-------------------
 cbdbtest  | gpadmin | UTF8     | en_US.UTF-8 | en_US.UTF-8 | 
(1 row)

解读：createdb <dbname> 在 Coordinator 上创建数据库；\l <dbname> 查看其编码与属主。数据库本身不跨 Segment 分布，但其中的表会按分布键分布到各 Segment。

4.3 gpstart：启动集群

gpstart 一次拉起 Coordinator 与所有 Segment。查看帮助：

gpstart --help

实测回显（输出节选（实测首尾））：

COMMAND NAME: gpstart

Starts a Apache Cloudberry system.

SYNOPSIS
gpstart [-d <coordinator_data_directory>] [-B <parallel_processes>]
        [-R] [-m | -c] [-y] [-a] [-t <timeout_seconds>]
        [-l logfile_directory] [--skip-heap-checksum-validation]
        [-v | -q]
gpstart -? | -h | --help
gpstart --version

逐项解读：-a 不询问直接启动；-B <n> 并行启动进程数；-t <秒> 超时；-m/-c 仅启动 Mirror/仅启动 Coordinator；-R 重试启动失败实例。典型用法：

gpstart -a

实测回显（输出节选（实测首尾））：

20261013:18:41:51:010822 gpstart:cdw:gpadmin-[INFO]:-   Successful segment starts                                            = 4
20261013:18:41:51:010822 gpstart:cdw:gpadmin-[INFO]:-   Failed segment starts                                                = 0
20261013:18:41:51:010822 gpstart:cdw:gpadmin-[INFO]:-Successfully started 4 of 4 segment instances
20261013:18:41:51:010822 gpstart:cdw:gpadmin-[INFO]:-Database successfully started

解读：Successfully started 4 of 4 segment instances 表示 2 Primary + 2 Mirror 全部启动。

4.4 gpstop：停止/重启/重载集群

gpstop --help

实测回显（输出节选（实测首尾））：

COMMAND NAME: gpstop

Stops or restarts a Apache Cloudberry system.

SYNOPSIS
gpstop [-d <coordinator_data_directory>] [-B <parallel_processes>]
       [-M smart | fast | immediate] [-t <timeout_seconds>]
       [-r] [-y] [-a] [-l <logfile_directory>] [-v | -q]
gpstop -u [-d <coordinator_data_directory>] [-l <logfile_directory>]

逐项解读：-M smart|fast|immediate 停机模式；-r 停止后立即重启；-u 仅重载配置不停止；-a 不询问；--host <段主机> 只停某台主机的实例。典型用法：

gpstop -a            # 停止整个集群
gpstop -u            # 重载 postgresql.conf 配置
gpstop -a -r         # 停止并立即重启

实测回显（gpstop -a 关键行）：

20261013:18:41:50:010044 gpstop:cdw:gpadmin-[INFO]:-   Segments stopped successfully      = 4
20261013:18:41:50:010044 gpstop:cdw:gpadmin-[INFO]:-   Segments with errors during stop   = 0
20261013:18:41:50:010044 gpstop:cdw:gpadmin-[INFO]:-Successfully shutdown 4 of 4 segment instances
20261013:18:41:50:010044 gpstop:cdw:gpadmin-[INFO]:-Database successfully shutdown with no errors reported

解读：Successfully shutdown 4 of 4 segment instances 表示全部实例已停。

4.5 gpstate：查看集群状态

gpstate --help

实测回显（输出节选（实测首尾））：

COMMAND NAME: gpstate

Shows the status of a running Apache Cloudberry system.

SYNOPSIS
gpstate [-d <coordinator_data_directory>] [-B <parallel_processes>]
        [-s | -b | -Q | -e] [-m | -c] [-p] [-i] [-f]
        [-v | -q] [-l <log_directory>]

逐项解读：-b 简要状态；-s 详细状态；-e 查看有问题的 Segment；-Q 队列状态；-f 显示 standby 状态；-i/-p 分别显示该段 IP/端口映射。常用组合：

gpstate -b

实测回显（输出节选（实测首尾））：

20261013:18:42:43:011247 gpstate:cdw:gpadmin-[INFO]:-Cloudberry instance status summary
20261013:18:42:43:011247 gpstate:cdw:gpadmin-[INFO]:-   Coordinator instance                                      = Active
20261013:18:42:43:011247 gpstate:cdw:gpadmin-[INFO]:-   Coordinator standby                                       = No coordinator standby configured
20261013:18:42:43:011247 gpstate:cdw:gpadmin-[INFO]:-   Total segment instance count from metadata                = 4

gpstate -e

实测回显：

20261013:18:52:24:011726 gpstate:cdw:gpadmin-[INFO]:-Segment Mirroring Status Report
20261013:18:52:24:011726 gpstate:cdw:gpadmin-[INFO]:-All segments are running normally

解读：-b 给出「Coordinator Active + Segment 计数」概览；-e 用于排查 Mirror 问题，输出 All segments are running normally 表示无异常。

4.6 gpconfig：统一管理集群参数

gpconfig --help

实测回显（输出节选（实测首尾））：

COMMAND NAME: gpconfig

Sets server configuration parameters on all segments within
a Apache Cloudberry system.

SYNOPSIS
gpconfig -c <param_name> -v <value>
       [-m <coordinator_value> | --masteronly | --coordinatoronly]
       | -r <param_name> [--masteronly | --coordinatoronly]
       | -l

逐项解读：-c <参数> -v <值> 修改；-m <值> 单独指定 Coordinator 值；-r <参数> 恢复默认；-l 列出所有参数及取值；-s <参数> 查看值。典型用法：

gpconfig -s max_connections
gpconfig -c gp_vmem_protect_limit -v 4096

实测回显（gpconfig -s max_connections）：

Values on all segments are consistent
GUC              : max_connections
Coordinator value: 250
Segment     value: 750

解读：-s 同时打印 Coordinator 与 Segment 取值；修改后需 gpstop -u 重载或 gpstop -a && gpstart -a 重启生效。

4.7 gpinitsystem：初始化集群

gpinitsystem --help

实测回显（输出节选（实测首尾））：

COMMAND NAME: gpinitsystem

Initializes a Apache Cloudberry system by using configuration
parameters specified in a configuration file (gp_init_config).

SYNOPSIS
gpinitsystem -c <gpinitsystem_config>
            [-h <hostfile_gpinitsystem>]
            [-B <parallel_processes>]
            [-p <postgresql_conf_param_file>]

逐项解读：-c 指定初始化配置文件；-h 指定主机文件（若配置里未写 MACHINE_LIST_FILE）；-B 并行进程数；-p 追加的参数文件。首次初始化：

gpinitsystem -c /home/gpadmin/gpconfigs/gpinitsystem_config -a

实测回显（输出节选（实测首尾））：

20261013:18:41:05:004994 gpinitsystem:cdw:gpadmin-[INFO]:-Successfully started 2 of 2 segment instances
20261013:18:41:12:004994 gpinitsystem:cdw:gpadmin-[WARN]:-Failed to start Cloudberry instance; please review gpinitsystem log to determine failure.
20261013:18:41:12:004994 gpinitsystem:cdw:gpadmin-[INFO]:-Apache Cloudberry instance successfully created

解读：-a 免交互确认；出现 Apache Cloudberry instance successfully created 即初始化成功；末尾 WARN 为 Mirror 注册告警，用 gpstop -a && gpstart -a 修复（详见《Apache Cloudberry 配置参数详解》同类排障思路，或本文 4.4/4.3）。

4.8 gpinitstandby：初始化备 Coordinator

gpinitstandby --help

实测回显（输出节选（实测首尾））：

COMMAND NAME: gpinitstandby

Adds and/or initializes a standby coordinator host for a Apache Cloudberry system.

SYNOPSIS
gpinitstandby { -s <standby_hostname> [-P <port>] | -r | -n }

逐项解读：-s <主机名> 指定备 Coordinator 主机并初始化；-P <端口> 指定端口；-r 移除已配置的 standby；-n 不启动。典型用法（需已配置到备节点的免密 SSH）：

gpinitstandby -s scdw

解读：单机集群实测未配置 standby，gpstate -b 显示 No coordinator standby configured；生产环境建议配置备 Coordinator 以避免单点。

4.9 gprecoverseg：恢复失效的 Segment

gprecoverseg --help

实测回显（输出节选（实测首尾））：

COMMAND NAME: gprecoverseg

Recovers a primary or mirror segment instance that has
been marked as down (if mirroring is enabled).

Synopsis
gprecoverseg [-p <new_recover_host>[,...]]
             |-i <recover_config_file>

逐项解读：-p <主机> 指定新主机；-i <文件> 指定恢复配置文件；-a 免交互；-F 全量恢复；-s 分步模式。典型用法（某 Segment 被标记 down 后）：

gprecoverseg -a          # 增量恢复所有 down 的 Segment

解读：恢复完成后可用 gpstate -e 确认 All segments are running normally。

4.10 数据分布与执行计划查看

除上述管理工具，日常最常做的两件事是「看数据落在哪个 Segment」和「看并行执行计划」。

psql -d cbdbtest <<'SQL'
CREATE TABLE t_user (user_id int, user_name text, login_count int) DISTRIBUTED BY (user_id);
INSERT INTO t_user VALUES (1, 'alice', 10), (2, 'bob', 5), (3, 'carol', 7);
SELECT gp_segment_id, count(*) AS cnt FROM t_user GROUP BY gp_segment_id ORDER BY gp_segment_id;
EXPLAIN SELECT count(*) FROM t_user;
SQL

实测回显：

CREATE TABLE
INSERT 0 3
 gp_segment_id | cnt
---------------+-----
             0 |   2
             1 |   1
(2 rows)

                                     QUERY PLAN
------------------------------------------------------------------------------------
 Aggregate  (cost=0.00..431.00 rows=1 width=8)
   ->  Gather Motion 2:1  (slice1; segments: 2)  (cost=0.00..431.00 rows=1 width=1)
         ->  Seq Scan on t_user  (cost=0.00..431.00 rows=1 width=1)
 Optimizer: GPORCA
(4 rows)

解读：SELECT gp_segment_id, count(*) 显示数据按 hash 分布到 content=0（2 行）与 content=1（1 行）；EXPLAIN 中的 Gather Motion 2:1 (segments: 2) 表示 Coordinator 从 2 个 Segment 汇聚结果，证明并行执行生效，Optimizer: GPORCA 表示使用 GPORCA 优化器。

五、注意事项

  • 以 gpadmin 操作：所有 gp* 工具应以 gpadmin 执行，并用绝对路径或先 source 环境文件，避免 PATH 缺失导致 command not found。
  • 免密 SSH 是前提：gpstart/gpstop/gpstate/gpinitsystem 通过 SSH 在各主机下发命令，必须先配好 gpadmin 免密 SSH（gpssh-exkeys）。
  • 重启 vs 重载：gpstop -u 只重载可动态生效的参数；涉及 shared_buffers/max_connections 等需重启的参数必须 gpstop -a && gpstart -a。
  • 高危操作：gpdeletesystem（删除集群）、gprecoverseg -F（全量恢复）会重写数据目录，生产执行前务必备份。

六、常见问题

Q1：执行 gpstart 报 Coordinator instance process running，如何正确重启？

现象：集群已在运行时执行 gpstart -a 报错退出。定位：gpstart 只负责启动，检测到 Coordinator 进程存在即拒绝。解法：先停后启：

gpstop -a && gpstart -a

实测回显（gpstart 关键行）：

20261013:18:41:51:010822 gpstart:cdw:gpadmin-[INFO]:-Successfully started 4 of 4 segment instances

Q2：gpstate -b 显示 No coordinator standby configured，是否异常？

现象：gpstate -b 输出 Coordinator standby = No coordinator standby configured。定位：单机/未配置备节点时属正常，非故障。解法：生产环境配置备 Coordinator 提升可用性：

gpinitstandby -s scdw

Q3：gprecoverseg 恢复后仍显示 Segment down，怎么确认？

现象：执行 gprecoverseg -a 后不确定是否生效。定位：用 gpstate -e 复核 Mirror 状态。解法：

gpstate -e

实测回显：

20261013:18:52:24:011726 gpstate:cdw:gpadmin-[INFO]:-All segments are running normally

解读：输出 All segments are running normally 即恢复成功；否则查 gpstate -s 与 FTS 日志。

七、参考链接