Vastbase G100手册实践：连接、表操作与接口避坑指南-平芜编程栈

简介：《VASTDATA Vastbase G100 V2.2用户手册》是一份面向信创场景的国产数据库操作指南，适合数据库管理员、应用开发者和国产化替代项目的运维人员研读，用于快速掌握基于openGauss打造的Vastbase G100的架构逻辑、事务管理与日常操作。包内共1个PDF文档，体积8.76MB，目录从概述逐步深入，涵盖数据库逻辑结构、数据查询请求处理过程、管理事务、连接数据库、创建和管理数据库、表空间规划与列存数据压缩等核心内容，并详细给出了配置服务端远程连接、使用vsql连接以及通过应用程序接口访问数据库的具体方法。已有196人学习下载。对希望系统学习Vastbase G100或参与信创数据库落地的读者而言，这份手册能提供从概念到操作的完整参考，帮助理解国产数据库在信息安全与数据主权方面的设计思路，也可作为日常运维的速查手册；由于文档由OCR扫描生成，个别字词可能存在识别误差，阅读时需结合上下文理解。

1. 一份国产数据库手册：为什么要从“逻辑结构”而不是安装步骤读起

信创数据库选型或替换评估时，Vastbase G100 是一个绕不开的名字，它是基于 openGauss 内核路线打造的国产化数据库解决方案，能在兼容 PostgreSQL 生态开发习惯的同时，覆盖政务、金融等场景对安全合规的要求。手头这份 V2.2 用户手册最让我意外的一点是：它没有一上来就教你怎么装库，而是先讲数据库逻辑结构、查询请求处理过程、管理事务这些容易被略过的部分。这个编排反而适合两类人：一类是刚接手国产库运维的 DBA，需要一套可执行的命令基线；另一类是负责老业务迁移评估的应用开发者，想判断现有 SQL、JDBC、ODBC 代码能复用多少。手册把连接、库表、应用开发、安全认证分成独立章节，踩坑时按图索骥就好。

2. 连接与初始化：vsql、远程认证、接口选型与关闭的边界

这次我按手册顺序先跑通了“连接数据库”和“关闭数据库”两个章节，发现它适合作为运维基线的核心不在命令本身，而在于这四件事：服务端远程连接怎么开、vsql 怎么连、应用接口选哪条、关闭数据库用什么姿势。这四件事对应了日常排障的四个入口，下面把参数和边界尽量留全。

2.1 先读逻辑结构图：连库之前需要建立的三层视图

手册 2.1 给出的数据库逻辑结构图，其实是在讲一个三层对应关系：表空间对应物理目录，schema 对应命名空间，表、分区、索引挂在 schema 下面。我一般切到新环境后会先执行一遍系统查询把这张图还原出来，确认自己连进去的库有没有走预期路径。

SELECT t.spcname AS tablespace, n.nspname AS schema, c.relname AS table_name FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace JOIN pg_tablespace t ON t.oid = c.reltablespace WHERE c.relkind = 'r' AND n.nspname NOT LIKE 'pg_%' LIMIT 10;

这个查询的逻辑是：pg_class存了所有表、索引、序列等对象，relkind = 'r'只取普通表；pg_namespace负责把表挂到 schema 下；pg_tablespace则把 schema 里的表映射到物理表空间。加了NOT LIKE 'pg_%'是为了过滤系统 schema，否则结果里全是系统表，看不出业务分布。

需要说明的是，reltablespace为 0 时表示使用数据库默认表空间，JOIN 出来会显示 NULL，这是正常现象，不代表表没有归属。理解这个结构的好处是，后面配置参数时知道改的是哪一层：表空间设置影响物理路径，schema 权限影响应用账号可见性，表级参数影响具体业务查询。排障时先确定问题发生在哪一层，再去看对应配置，能省掉很多无用功。

2.2 配置服务端远程连接：监听地址、认证方式与重载顺序

手册 3.2.1 专门讲了配置服务端远程连接。这里我先说一个容易踩的默认值：安装后数据库默认可能只监听 127.0.0.1，外部机器连不上，不一定是防火墙问题。先打开数据目录下的postgresql.conf（常见路径是$PGDATA/postgresql.conf，具体以实际安装目录为准），确认两个参数：

# 修改 $PGDATA/postgresql.conf listen_addresses = '192.0.2.10,127.0.0.1' port = 5432 password_encryption_type = 1

listen_addresses决定服务端在哪些网卡上接受连接，测试环境可以直接写'*'，生产环境建议写具体 IP。password_encryption_type是 openGauss 系常见的口令加密参数，1 对应 md5，2 对应 sha256，Vastbase 手册里没有给默认值，建议以实测为准。改完监听后，还要同步修改客户端认证配置文件pg_hba.conf，否则连接会被认证策略拦下来：

# 追加到 $PGDATA/pg_hba.conf host all all 192.0.2.0/24 scram-sha-256

这一行的含义是：允许来自 192.0.2.0/24 网段的 TCP 连接访问所有数据库、所有用户，认证方式为 scram-sha-256。host表示 TCP 连接，all分别指数据库名和用户名，末尾的认证方式决定了服务端如何校验口令。这里不建议图省事写成trust，否则内网任意机器都能免密直连，信创环境的安全审计通常过不了。

配置文件改完后，需要让服务端重新加载。常见做法是执行vb_ctl reload，或者在 vsql 里执行SELECT pg_reload_conf();。两者等价，都只对后续新连接生效，不会打断已有会话。需要强调的是：改listen_addresses和port必须重启数据库进程才生效，而pg_hba.conf的变更 reload 即可。如果改了认证方式后旧连接仍然正常、新连接却报错，多半是没 reload 干净，先检查这个再查防火墙。

2.3 使用 vsql 连接：命令行参数与三种常用姿势

vsql 是 Vastbase 自带的命令行客户端，用法与 PostgreSQL 系的 psql 同源。手册 3.2.2 给了连接方法，我把测试时最常用的三种姿势整理出来：

# 交互式连接，进入后可以直接执行 SQL vsql -h 192.0.2.10 -p 5432 -U vastbase -d vastbase # 执行单条 SQL，-c 后跟命令，适合脚本调用 vsql -h 192.0.2.10 -p 5432 -U vastbase -d vastbase -c "SELECT version();" # 执行 SQL 脚本文件，-f 指定文件路径 vsql -h 192.0.2.10 -p 5432 -U vastbase -d vastbase -f /tmp/init.sql

-h指定数据库主机地址，-p指定端口，-U指定登录用户，-d指定要连接的数据库名，-c和-f分别对应单条命令和脚本文件。这里有一个我在生产环境吃过亏的细节：如果密码直接写在命令行里，比如-W 'YourPassword'，会出现在 shell 历史和系统进程列表中，安全扫描很容易报出来。更稳妥的做法是用环境变量PGPASSWORD传入，或者使用连接串：

export PGPASSWORD='YourPassword' vsql -h 192.0.2.10 -p 5432 -U vastbase -d vastbase -c "SELECT current_user;"

手册里没有专门提醒这一点，但信创环境的安全基线普遍要求密码不出现在命令行参数中，建议从第一天就养成这个习惯。

2.4 应用接口选型：JDBC、ODBC 与 libpq 的边界

手册 4.2 到 4.4 分别讲了 JDBC、ODBC 和基于 libpq 的开发，选哪条路取决于业务形态，而不是哪个更“高级”。我把三者适用场景列成一个对比，方便直接套用：

接口	适用场景	典型使用者	主要弱项
JDBC	Java 服务、连接池、ORM 框架	后端应用开发	驱动版本要跟 JDK 匹配
ODBC	C/C++ 程序、BI 报表工具	数据集成、报表平台	DSN 配置链路长，容易配错
libpq	嵌入式 C 程序、轻量客户端	底层工具开发	没有连接池，生命周期要自己管理

选型理由很直接：如果你的团队以 Java 为主，且业务已经用了 MyBatis 或 Spring Data 这类 ORM，那 JDBC 是唯一合理选择，连接池、读写分离都有成熟方案；如果业务涉及 BI 报表工具连库取数，或者用 C++ 写采集程序，ODBC 的兼容性更好；libpq 适合那些不想引入重型依赖、只需要简单查询的小工具。

2.5 关闭数据库：命令行与 SQL 两种方式别再搞混

手册 3.3 把关闭数据库分成了“使用 SQL 语句关闭”和“使用 vb_ctl 工具关闭”两节，这里要分清粒度。vb_ctl stop是停数据库实例，作用于整个集群，生产环境执行前必须确认没有正在跑的关键业务，否则所有连接会瞬间中断。常见用法：

vb_ctl stop -m fast

-m fast表示快速关闭：回滚未提交事务、断开客户端连接后停止进程。如果改成-m immediate，数据库不会等待事务完成，直接终止进程，下次启动时可能需要做崩溃恢复，非必要不要用。还有一种情况是只想断开某个异常会话，而不是停整个库，这时用的是 SQL 方式：

SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'active' AND pid <> pg_backend_pid();

这条 SQL 会把当前所有活跃会话全部终止，注意pg_terminate_backend不会回滚事务，被终止会话中的未提交修改会丢失。实际运维中，我见过有人图省事直接kill -9主进程，结果共享内存状态残留，重启时报一堆错，只能手动清理 postmaster.pid 文件。除非数据库完全无响应，否则不要越过vb_ctl stop用 kill。

3. 库表与数据操作：从行存列存、表空间到分区表与闪回

手册第 3 章占了将近一半篇幅，核心是规划存储模型、建表、管理分区和约束。这一章我建议按“存储模型 → 表空间 → 表 → 分区 → 约束”的顺序读，因为每一步都在决定下一步的物理布局。

3.1 规划存储模型：先定行存还是列存再建表

手册 3.5 讲规划存储模型，建议在建表之前就要想清楚行存还是列存。行存把一行数据的所有列连续存放，适合点查、频繁更新、事务处理；列存把同一列的数据连续存放，适合聚合分析、批量导入，压缩率高但随机更新代价很大。

维度	行存（ROW）	列存（COLUMN）
适合场景	OLTP、点查、频繁 DML	OLAP、聚合分析、批量导入
压缩率	一般	高，重复值越多的列收益越大
UPDATE/DELETE	正常	性能差，不建议高频操作
典型参数	ORIENTATION=ROW	ORIENTATION=COLUMN, COMPRESSION=HIGH

建表时的写法是：

-- 行存表，适合订单、用户这类被频繁修改的数据 CREATE TABLE orders_row ( id bigint PRIMARY KEY, amount numeric(10,2), status text ) WITH (ORIENTATION = ROW); -- 列存表，适合流水、日志这类只追加、按时间聚合的数据 CREATE TABLE orders_col ( id bigint, amount numeric(10,2), status text ) WITH (ORIENTATION = COLUMN, COMPRESSION = HIGH);

ORIENTATION决定存储格式，COMPRESSION只对列存表生效。我一般把压缩级别设为HIGH，因为列存表的主要成本就是磁盘，而聚合分析场景下 IO 占比很高，压缩能明显提升扫描吞吐。但如果你是更新较多的场景，列存表千万别用，血泪经验是：在列存表上做逐行 UPDATE，性能可能比行存表慢一个数量级还多。

3.2 创建与管理表空间：目录权限和物理路径先对齐

表空间在 Vastbase 里对应一个物理目录，逻辑上解决的是“把不同业务的数据放到不同磁盘”的问题。创建语句：

CREATE TABLESPACE tbs_app LOCATION '/data/vastbase/app';

这里最容易翻车的不是 SQL 本身，而是目录权限。LOCATION指向的目录必须预先创建，并且属主要改成运行数据库的系统用户，否则建表空间时会直接报权限错误。常见做法是：

mkdir -p /data/vastbase/app chown vastbase:vastbase /data/vastbase/app

创建完成后，可以查一下各表空间的使用情况：

SELECT spcname, pg_size_pretty(pg_tablespace_size(spcname)) AS size FROM pg_tablespace;

pg_tablespace_size接受表空间名作为参数，返回字节数，pg_size_pretty负责转成人类可读的 KB/MB/GB。需要提醒的是，表空间创建后不能直接改名，如果规划阶段就预感命名不合适，宁可删掉重建也不要留着将就，后面改物理路径的成本远高于现在删几行 SQL。

3.3 表的增改查删与闪回表：误操作后的后悔药

手册 3.8 讲创建和管理表，核心是五类 DML 操作：INSERT、UPDATE、SELECT、DELETE，以及一个容易被忽略的闪回表。先把常规操作串一遍：

-- 建表 CREATE TABLE smoke_test ( id bigint GENERATED BY DEFAULT AS IDENTITY, val text ); -- 插入 INSERT INTO smoke_test (val) VALUES ('hello'), ('world'); -- 更新 UPDATE smoke_test SET val = 'Vastbase' WHERE id = 2; -- 查询 SELECT id, val FROM smoke_test ORDER BY id; -- 删除 DELETE FROM smoke_test WHERE id = 1;

这里的GENERATED BY DEFAULT AS IDENTITY是 SQL 标准的自增写法，和 PostgreSQL 系的SERIAL效果接近。手册里虽然用的是更传统的建表方式，但信创迁移项目中，不少业务是从 Oracle 转过来的，IDENTITY 语法兼容性更好，建议评估阶段就统一风格。

闪回表是手册 3.8.6 的内容，对应误删表之后的后悔药。使用前要先确认回收站开关打开：

-- 开启回收站 ALTER SYSTEM SET enable_recyclebin = on; -- 误删后查看回收站 SELECT * FROM pg_recyclebin; -- 闪回被删除的表 TIMECAPSULE TABLE smoke_test TO BEFORE DROP;

enable_recyclebin是 openGauss 系参数，不开的话 DROP 的表直接物理清除，闪回无从谈起。pg_recyclebin视图会列出回收站中所有被删对象，恢复时用TIMECAPSULE TABLE ... TO BEFORE DROP语法。注意：闪回恢复的是 DROP 操作，如果是 DELETE 删的数据行，用闪回表救不回来，只能用备份或者提前做的时间点恢复。

3.4 分区表与 default 分区：兜底设计与查询裁剪

手册 3.8.8 专门讲了创建和管理分区表，里面特意提到支持 default 分区。分区表的核心价值有两个：一是数据管理上可以按分区做批量清理，二是查询优化器可以只扫描命中分区，减少 IO。一个典型的 range 分区表写法：

CREATE TABLE logs ( log_time timestamp, level text, msg text ) PARTITION BY RANGE (log_time) ( PARTITION p2024 VALUES LESS THAN ('2025-01-01'), PARTITION p_default DEFAULT );

PARTITION BY RANGE指定按时间范围分区，VALUES LESS THAN定义各个分区的上界，DEFAULT分区用来接收所有不匹配其他分区上界的数据。default 分区最大的价值是兜底：生产环境经常出现业务侧提前写入未来时间的数据，没有 default 分区的话，INSERT 会直接报错，有了 default 分区至少数据能落进去，后面再排查数据为什么进了 default。

但 default 分区也有隐患。如果大部分数据因为没有匹配规则而堆进了 default，分区表的裁剪能力就失效了——查询条件带时间范围时，优化器无法确认数据只属于某个子分区，只能扫描所有分区，性能会明显下滑。验证方法是用EXPLAIN看查询计划：

EXPLAIN (COSTS OFF) SELECT * FROM logs WHERE log_time >= '2024-01-01' AND log_time < '2024-06-01';

如果计划里出现Partition Iterator并且遍历了 p2024 和 p_default 两个分区，说明裁剪没失效；如果只扫了一个分区，说明优化器判断数据范围可收敛。平时巡检时建议定期统计 default 分区行数，发现膨胀就及时补建正式分区。

3.5 约束体系：五类约束与启用禁用

手册 3.11.5 把约束分成检查约束、非空约束、唯一约束、主键、外键五类，并单列了约束启用禁用。五类约束的定位可以用一张表说清：

约束类型	作用	常用语法
检查约束	限定列值范围	`CHECK (amount > 0)`
非空约束	禁止 NULL	`NOT NULL`
唯一约束	保证列值不重复	`UNIQUE (code)`
主键	唯一标识一行	`PRIMARY KEY (id)`
外键	维护表间引用关系	`FOREIGN KEY (dept_id) REFERENCES dept(id)`

约束在大批量数据导入时经常成为性能瓶颈。手册里专门讲了启用禁用，我的做法是：导入前先禁用业务表上的检查约束和外键，导入完成后再启用并校验数据。语法如下：

-- 禁用指定约束 ALTER TABLE orders_row ALTER CONSTRAINT chk_amount DISABLE; -- 启用指定约束 ALTER TABLE orders_row ALTER CONSTRAINT chk_amount ENABLE;

需要留意的是，DISABLE只是停止后续新数据的约束校验，已有数据不会自动回刷校验结果。如果你担心存量数据有问题，启用约束后要主动跑一遍校验 SQL，把不满足约束条件的行揪出来，不要等到业务查询时再让它炸出来。

4. JDBC、ODBC 与 libpq 接入：连接参数、数据源配置与调试的落地姿势

手册第 4 章是应用开发者的核心必读部分，从开发规范、JDBC 到 ODBC 和 libpq 都有覆盖。这一章最实用的价值在于：告诉你怎么在代码里把连接建对、把参数配顺，以及出错时从哪里切入看问题。

4.1 JDBC 驱动准备：版本兼容性与类路径设置

手册 4.2.1 到 4.2.3 交代了 Vastbase JDBC 版本、与 JDK 的兼容性以及主要类和接口。我自己踩过的一个坑是：驱动 jar 包是用 JDK 8 编译的，但应用跑在 JDK 17 上，运行时报NoSuchMethodError，第一反应是代码写错了，排查半天才发现是驱动版本和 JDK 兼容性问题。所以收到新驱动包后，第一件事是确认它对应的 JDK 版本范围，再决定是否升级应用 JDK。

类路径设置是另一道常见门槛。驱动 jar 下载后，要把路径加进 CLASSPATH：

export CLASSPATH=/opt/vastbase/lib/vastbase-jdbc.jar:$CLASSPATH

如果用的是 Maven 或 Gradle，就直接以依赖方式引入，但要确认仓库里坐标对应的版本和手册一致。另外，驱动类的包名，不同厂商封装的实现可能不同。常见做法是兼容 openGauss/PostgreSQL 驱动写法，以org.postgresql.Driver为主；如果应用连不上且报类加载错误，就要去 jar 包里的META-INF/services目录看它声明的真实驱动类名，不要硬猜。

4.2 JDBC 连接与结果集处理：一段最短可跑通的代码

手册 4.2.5 到 4.2.6 讲了导入、加载驱动、连接数据库、执行 SQL。我整理了一段可以直接跑通的最小 Java 代码：

import java.sql.*; public class QuickCheck { public static void main(String[] args) throws Exception { // 加载驱动，JDBC 4 之后可以省略，但保留更稳妥 Class.forName("org.postgresql.Driver"); // 连接参数：host、port、dbname、user、password String url = "jdbc:postgresql://192.0.2.10:5432/vastbase"; try (Connection conn = DriverManager.getConnection(url, "vastbase", "YourPassword"); PreparedStatement ps = conn.prepareStatement( "SELECT id, amount FROM orders_row WHERE amount > ?"); ResultSet rs = ps.executeQuery()) { // 设置参数：下标从 1 开始，对应第一个 ? 占位符 ps.setBigDecimal(1, new BigDecimal("100")); while (rs.next()) { System.out.println("id=" + rs.getLong("id") + ", amount=" + rs.getBigDecimal("amount")); } } } }

这段代码有几个关键点：Class.forName在 JDBC 4 下可以省略，但保留可以让驱动注册时机更明确，也方便排查类路径问题；PreparedStatement的setBigDecimal必须按下标从 1 开始设置，不能从 0 开始；try-with-resources确保连接、语句、结果集都能被自动释放。Vastbase 的 JDBC URL 在不同版本上可能支持不同的前缀，如果jdbc:postgresql://连不通，检查驱动文档里的 URL 格式要求。

4.3 连接池与连接参数：别把连接超时设成无限大

生产环境一般不会裸用DriverManager.getConnection，而是套一层连接池。Vastbase JDBC 支持标准的连接池接口，HikariCP 是常见选择。关键参数配置如下：

HikariConfig config = new HikariConfig(); config.setJdbcUrl("jdbc:postgresql://192.0.2.10:5432/vastbase"); config.setUsername("vastbase"); config.setPassword("YourPassword"); config.setMaximumPoolSize(20); config.setConnectionTimeout(3000); config.setValidationTimeout(1500); config.setPoolName("vastbase-ds");

maximumPoolSize不是越大越好，连接池大小超过数据库实际处理能力后，反而会让数据库端线程上下文切换变多，常见做法是取业务峰值并发数的 1.5 到 2 倍左右；connectionTimeout建议设置 3 到 5 秒，这样数据库假死时应用能快速失败，而不是所有请求都堆在连接获取上，导致雪崩；validationTimeout要小于connectionTimeout，否则校验连接是否有效的动作会先超时。这里要特别提醒：connectionTimeout一定不要设成 0，0 表示无限等待，生产故障时你的应用会变成一堆等待连接的僵尸线程。

4.4 ODBC 数据源配置：unixODBC、驱动替换与 DSN

ODBC 链路比 JDBC 长，但装上之后对应用是透明的。手册 4.3.2 给了安装 openGauss 或 Vastbase、安装 unixODBC、替换客户端驱动、配置数据源的标准流程。我把关键步骤抽出来：

# 安装 unixODBC（以常见发行版包管理器为例） yum install -y unixODBC unixODBC-devel # 确认 Vastbase ODBC 驱动 so 文件位置，通常在安装目录的 lib 下 ls /opt/vastbase/lib/psqlodbcw.so

然后编辑odbc.ini配置数据源：

[VastbaseDSN] Description = Vastbase ODBC DSN Driver = /opt/vastbase/lib/psqlodbcw.so Host = 192.0.2.10 Port = 5432 Database = vastbase Username = vastbase Password = YourPassword

Driver字段必须写 so 文件的绝对路径，不要只写驱动名，否则 unixODBC 会在默认路径下找不到它。配置完成后，用isql做连通性测试：

isql -v VastbaseDSN

如果报Cannot open library，先检查 so 文件路径是否存在，再看文件属主和权限；如果报Specified driver could not be loaded，大概率是 64 位 unixODBC 装了 32 位驱动，或者反过来。ODBC 的坑多数集中在位数不匹配和路径错误上，这两点查完基本就能定位。

4.5 libpq 接入与调试：出错信息先看 PQerrorMessage

libpq 是 Vastbase 提供的 C 语言接口，适合嵌入式场景。手册 4.4 篇幅不多，但调试思路值得单独说。一个最小连接示例：

#include <stdio.h> #include <libpq-fe.h> int main(void) { PGconn *conn = PQconnectdb( "host=192.0.2.10 port=5432 dbname=vastbase user=vastbase password=YourPassword" ); if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection failed: %s\n", PQerrorMessage(conn)); PQfinish(conn); return 1; } printf("Connected successfully\n"); PQfinish(conn); return 0; }

PQconnectdb用连接串一步完成建连，PQstatus返回连接状态，失败时PQerrorMessage会给出具体失败原因。我调试 libpq 程序的原则是：任何连接失败都先打印PQerrorMessage，而不是猜网络或猜密码。它会把认证失败、超时、无法解析主机名这些原因分得很清楚，比逐行检查代码高效得多。另外，libpq 本身不做连接池，连接生命周期必须由业务代码管理，频繁建连会拖垮服务端，有条件时还是建议上层加一层封装。

5. 避坑指南：连接、权限、列存与备份恢复的五个高频故障

手册里每个功能章节都写得很规矩，但实操时坑更多来自“以为看懂了就动手”。我把自己复现手册过程中踩过的和见过的故障按“现象-原因-解决”整理成五条，供你直接对照。

5.1 连接与认证类：远程连不上、认证改完连不上、SSL 证书报错

现象一：本机 vsql 能连数据库，但远程机器执行vsql -h 192.0.2.10 -p 5432报could not connect to server。原因通常是postgresql.conf里的listen_addresses还是默认的127.0.0.1，服务端只在回环地址上监听，远程请求根本到不了数据库进程。解决：把listen_addresses改为实际业务网卡 IP 或'*'，重启数据库，再配合pg_hba.conf放行对应网段。先确认这条，再查防火墙，顺序不要反，否则容易白改一晚上防火墙规则。

现象二：把pg_hba.conf从trust改成scram-sha-256后，应用侧所有连接开始报password authentication failed。原因：trust模式下客户端一直没有配置密码，数据库里也没给这个用户设置过可用口令；认证方式收紧后，老密码哈希和新的加密方式不匹配，自然验不过。解决：先确认数据库账号是否设置了密码，用ALTER USER vastbase PASSWORD '新密码';重置，再把应用连接串里的密码补上。这里注意，password_encryption_type会影响新口令的哈希算法，如果重置后仍然失败，检查这个参数值是否和应用侧支持的认证方式一致。

现象三：开启 SSL 后连接报certificate verify failed或root certificate file not found。原因：客户端找不到 CA 证书文件，或者证书文件权限过大被数据库进程拒绝读取。解决：确认root.crt路径和sslrootcert参数指向一致；证书文件权限建议设为 600，属主为运行数据库的用户。自签证书环境下，还要检查证书里的 CN 是否和连接使用的 IP 或主机名匹配，不匹配会直接触发校验失败。

5.2 数据与备份恢复类：闪回失效、备份恢复路径错位、列存更新慢

现象四：执行TIMECAPSULE TABLE xxx TO BEFORE DROP时报错，或者查pg_recyclebin什么都不显示。原因：enable_recyclebin参数没有开启，或者开启后未生效。这个参数是 openGauss 系特有的回收站开关，默认通常为 off。解决：先执行ALTER SYSTEM SET enable_recyclebin = on;，然后 reload 或重启数据库，确认参数值生效后再做 DROP 和闪回测试。还要注意，闪回恢复的是 DROP TABLE，如果你用的是TRUNCATE TABLE，回收站里不会出现这个表。

现象五：用vb_basebackup做 tar 格式备份，恢复后数据库启动失败，日志提示找不到某个表空间目录。原因：备份时表空间物理路径是/data/vastbase/app，恢复环境里这个目录不存在或者路径不同。解决：恢复前先创建同名目录并设置属主，或者恢复后用符号链接把原路径指到新位置。手册 3.11.7 单独讲了表空间备份恢复，我建议在测试环境完整走一遍：备份、删表空间目录、恢复、启动验证，把路径映射关系提前踩实，不要等生产恢复时才第一次接触这个流程。

现象六：列存表执行大批量 UPDATE，跑了几分钟还没结束，应用侧直接超时。原因：列存表的设计目标是分析型扫描，逐行 UPDATE 意味着每次都要定位到列的物理位置并重写数据块，随机更新代价极高。解决：把列存表上高频更新业务改到行存表，或者把更新转换成“批量导入新分区 + 切换分区”的模式。手册 3.5 规划存储模型一节已经提醒了这一点，但很多人都是等到线上慢查询才回头看它。建表前想清楚数据是“只追加”还是“频繁改”，能省掉后面一整轮优化工作。

6. 进阶验证：把 V2.2 手册拆成一份最小可执行验收清单

手册最有价值的部分不是某一个命令，而是章节之间可以串成一条验证链路。我拿到手后养成习惯：先把“连接 → 建表 → 增删改 → 闪回 → 备份恢复 → SSL 校验”串成一个最小闭环，跑通后才算对版本心里有底。下面的脚本可以直接存成 Bash 文件，在测试机上执行。

6.1 最小验证闭环：五分钟跑通手册主干流程

#!/bin/bash # 1) 连接并创建测试 schema vsql -h 127.0.0.1 -p 5432 -U vastbase -d vastbase -c "CREATE SCHEMA IF NOT EXISTS smoke_test;" # 2) 建行存表和列存表，验证两类存储格式能否正常创建 vsql -h 127.0.0.1 -p 5432 -U vastbase -d vastbase \ -c "CREATE TABLE smoke_test.t_row(id bigint, val text) WITH (ORIENTATION=ROW);" vsql -h 127.0.0.1 -p 5432 -U vastbase -d vastbase \ -c "CREATE TABLE smoke_test.t_col(id bigint, val text) WITH (ORIENTATION=COLUMN, COMPRESSION=HIGH);" # 3) 数据写入与更新，验证基础 DML 路径 vsql -h 127.0.0.1 -p 5432 -U vastbase -d vastbase \ -c "INSERT INTO smoke_test.t_row VALUES (1, 'hello');" vsql -h 127.0.0.1 -p 5432 -U vastbase -d vastbase \ -c "UPDATE smoke_test.t_row SET val='world' WHERE id=1;" # 4) 闪回验证：确认回收站开关生效的情况下 DROP 后能恢复 vsql -h 127.0.0.1 -p 5432 -U vastbase -d vastbase \ -c "DROP TABLE smoke_test.t_row;" vsql -h 127.0.0.1 -p 5432 -U vastbase -d vastbase \ -c "SELECT count(*) FROM pg_recyclebin;" vsql -h 127.0.0.1 -p 5432 -U vastbase -d vastbase \ -c "TIMECAPSULE TABLE smoke_test.t_row TO BEFORE DROP;" # 5) 备份验证：tar 格式全量备份，确认备份目录有产物 vb_basebackup -D /backup/inc -F tar -X stream \ -h 127.0.0.1 -p 5432 -U vastbase -W YourPassword

第 5 步的-D指定备份输出目录，-F tar表示以 tar 格式输出，-X stream表示流式备份 WAL 日志。跑完这五步后，检查/backup/inc目录下是否生成了base.tar和 WAL 文件，有就说明备份链路通了。这套脚本功能上是“穷人的验收清单”：不依赖任何图形工具，一条命令接一条命令地验证手册里的核心承诺。

6.2 从手册到团队验收清单：沉淀成一张可回归的表格

脚本跑通只是第一步。真正有意义的是把脚本映射成一张验收表，之后每个版本升级都带着它回归一遍。

功能模块	验证命令/查询	预期结果
连接	`vsql -h <host> -p <port> -U <user> -d <db> -c "SELECT 1;"`	返回 1
建表	创建行存表和列存表各一张	无报错，`\dt`可看到表
闪回	DROP 后查回收站并恢复	恢复后表数据完整
备份	`vb_basebackup -F tar -X stream`	备份目录含 base.tar 与 WAL
SSL	开启 SSL 后客户端连接	日志显示 SSL 加密协商成功