简介：这份用户手册是北京海量数据技术股份有限公司为国产化数据库 Vastbase G100 V2.2 编写的官方指南，面向数据库管理员、运维工程师及信创领域学习者，系统讲解基于 openGauss 的数据库逻辑结构、数据查询请求处理过程、事务管理及相关核心概念。包体为单个 PDF 文件，约 8.76MB，内容从概述延伸至具体操作，目录清晰，便于按需查阅。手册重点介绍了从连接数据库到日常管理的完整流程，包括配置服务端远程连接、使用 vsql 工具、调用应用程序接口，以及创建和管理数据库、规划存储模型、列存数据压缩、表空间管理等实用方法。对于希望深入了解或上手操作 Vastbase G100 的用户而言，这份资料能帮助快速建立知识框架并掌握关键操作细节。目前已有 198 人学习下载，适合作为信创数据库入门与日常参考的配套文档。

1. Vastbase G100 V2.2 用户手册：信创数据库落地前，值得先通读的一份资料

Vastbase G100 是一款基于 openGauss 生态打造的信创数据库产品，V2.2 用户手册把逻辑结构、连接方式、存储规划、应用开发接口、安全认证和备份恢复串成了一条完整可落地的操作链。这份手册最打动我的是它不堆概念：从实例到数据文件的映射关系用逻辑结构图画清楚了；远程连接、vsql、JDBC/ODBC/libpq 这些接入方式都有参数级说明；分区表、闪回表、default 分区、tar 格式备份这些高频运维点都给了可照做的操作。适合正在做数据库选型评估、存量应用迁移适配，或者刚接手 Vastbase 日常运维的开发者。我拆这份手册时重点验证了三块：连接与认证、开发接口的连接参数、备份恢复流程，本文按这个顺序展开。

2. Vastbase 的体系结构与设计逻辑：先弄懂内部机制再上手操作

2.1 数据库逻辑结构：实例、表空间与数据文件的三层映射

Vastbase G100 的逻辑结构可以拆成四层嵌套：数据库是最高层逻辑容器，一个实例可以管理多个数据库；数据库下面挂多个表空间，表空间对应磁盘上的物理目录；表、索引、视图这些对象属于某个 schema，数据最终落在表空间指定的数据文件中。手册开篇的逻辑结构图把这四层关系画得很清楚——表和索引数据最终写入表空间对应的数据文件，而 undo、redo 这类日志在独立存储路径上，不占用表空间数据文件。

理解这层关系对日常运维最直接的帮助是：建表之前先想好表空间规划。如果所有表都堆在默认表空间里，数据文件膨胀后做数据迁移的成本会非常高。我一般会在初始化数据库时就建好几个独立的表空间，一个放业务表、一个放索引、一个放临时数据，按目录划分磁盘占用，后续做备份排除和磁盘扩容都方便。

提示：与 PostgreSQL 的体系类似，Vastbase 里「数据库」不是操作系统目录，「表空间」才是真正决定数据落盘位置的物理抽象。

验证当前实例下的表空间和数据文件，可以查系统视图：

SELECT spcname FROM pg_tablespace;

这个视图返回所有已创建的表空间名称。你还可以配合 pg_relation_filepath 查看某张表实际落盘的文件路径，这能帮你快速确认表是否建到了预期的表空间里。

2.2 数据查询请求处理过程：一条 SQL 的完整旅程与排错切入点

手册用独立小节描述了数据查询请求的处理过程：客户端把 SQL 发送到服务端后，首先经过词法语法解析，生成解析树；然后查询优化器基于表统计信息和代价模型生成执行计划；接着执行器按照计划访问表数据或索引，从缓冲区或磁盘读取数据页，最终把结果集封装后返回客户端。权限检查发生在解析和优化阶段，连接数限制在接入层完成校验。

这条链路的价值在排错时体现得最明显。一条慢查询出现后，第一步不是调参数，而是用 EXPLAIN 看执行计划——如果计划显示走了全表扫描而表上有索引，问题出在优化器没有选对索引；如果计划正常但实际执行仍然很慢，问题可能出在磁盘 IO 或缓冲区命中率。定位方向的差异决定了后续动作完全不同。

EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_id = 2001;

EXPLAIN ANALYZE 会真实执行这条查询，并输出每步的实际耗时和行数。判断标准很简单：看有没有走 Index Scan，看实际行数与预估行数是否偏差过大。如果偏差大，多半是统计信息过期，执行一次 ANALYZE 后再看计划。

2.3 事务管理：提交、回滚与并发场景处理方式

手册将事务管理单独成节。Vastbase 支持显式事务和隐式事务，显式事务通过 BEGIN、COMMIT、ROLLBACK 控制，隐式事务是每条语句自动提交。底层基于多版本并发控制实现读不阻塞写、写不阻塞读，这是它处理高并发的基础能力。隔离级别支持读已提交等标准级别，应用侧可以根据业务对一致性的要求去选择。

实际运维中，长事务是并发问题的常见来源。事务过大会导致 undo 日志膨胀，拖慢后续所有更新操作的版本链扫描。手册也在相关提示里强调事务要短小。我处理过类似场景：一个批量导入程序把几十万条 INSERT 包在一个事务里，结果业务高峰期其他会话的查询延迟飙升。改成每几千条提交一次后，影响立刻消失。

BEGIN; UPDATE accounts SET balance = balance - 100 WHERE id = 1; SAVEPOINT sp_before_check; UPDATE accounts SET balance = balance + 100 WHERE id = 2; ROLLBACK TO sp_before_check; COMMIT;

SAVEPOINT 的用途是事务内的部分回滚，常用于批处理中跳过单条异常数据。它比整体 ROLLBACK 粒度更细，但保存点本身也有资源开销，循环中使用时要控制数量。

2.4 核心概念对照：数据库、Schema、表空间与数据文件

这组概念是新手最容易搞混的地方。Vastbase 里一个实例可以创建多个数据库，数据库之间是逻辑隔离的；每个数据库包含多个 schema，schema 是对象的命名空间，表、视图、序列都挂在 schema 下；表空间是物理存储的抽象，一个表空间可以包含多个数据文件；数据文件是操作系统层面的真实文件，文件大小和增长策略会影响磁盘占用。

实际选型时，业务系统之间完全独立，用多库隔离更干净；同一套应用的不同模块，用 schema 划分更省资源。手册里的操作路径也兼顾了这两种场景。需要注意的是 schema 授权要单独处理，默认权限机制下新用户并不能任意访问其他 schema 下的表，需要在授权阶段显式赋予。

3. 数据库日常使用实战：连接、存储规划、建表与数据维护

3.1 连接数据库：vsql 本地连接与远程连接两个前置配置

手册「从这里开始」一节把连接方式统一到 vsql，命令格式和 PostgreSQL 生态的交互终端很像：

vsql -h 192.168.1.10 -p 15432 -U vastbase -d postgres -W

参数含义：-h 指定服务端 IP，本机连接可省略；-p 指定端口，具体端口以安装配置为准；-U 指定登录用户；-d 指定数据库名；-W 表示连接时提示输入密码。首次登录后，建议立刻执行一次 SELECT version(); 确认服务端版本和连接链路正常。

远程连接有两个前置条件容易被忽略：一是服务端需要监听对外网卡地址，而不是只监听 localhost；二是接入认证配置文件里要允许对应 IP 或网段的访问。手册 3.2.1 节专门讲了服务端远程连接的配置方法，这是典型的「连不上先查配置再查网络」的场景，不要上来就怀疑密码问题。

认证配置文件里加一条授权的思路如下：

host all vastbase 192.168.1.0/24 scram-sha-256

这行的含义是：允许 192.168.1.0/24 网段的主机以 vastbase 用户访问所有数据库，认证方式为 scram-sha-256。修改后需要 reload 配置才生效。

3.2 创建与管理数据库：DDL 操作和两种关闭方式

创建数据库用标准 SQL：

CREATE DATABASE vastbase_db WITH ENCODING 'UTF8' TEMPLATE template0;

指定 ENCODING 是为了统一字符集，指定 TEMPLATE template0 是为了避免从默认模板继承不必要的对象和区域设置。手册同时介绍了关闭数据库的两种方式：一条 SQL 语句执行受控关闭，以及使用 vb_ctl 工具关闭。

vb_ctl stop -D /data/vastbase

-D 指定数据目录，该命令适用于维护窗口的常规停库。SQL 方式适合数据库运行中需要快速关停的场景，但会在应用侧产生连接中断，使用时要想清楚影响范围。我一般只在确认无业务流量时停库，并且停库前先做一次日志检查。

3.3 存储模型规划：行存与列存的选型逻辑与列存压缩

行存表和列存表的选择直接决定业务性能表现。行存适合 OLTP 场景：点查、按主键更新、返回整行记录；列存适合 OLAP 场景：大范围扫描、聚合统计、只读取少量列。手册「列存下的数据压缩」一节给出的思路是：压缩比取决于列的数据特征，重复值越高压缩效果越好，枚举类字段比 UUID 类字段更适合列存。

CREATE TABLE fact_sales ( sale_date DATE, region VARCHAR(32), amount NUMERIC(12,2) ) WITH (ORIENTATION = COLUMN);

ORIENTATION 参数决定存储模型，COLUMN 表示列存，默认是 ROW。列存表在压缩和宽表扫描上有优势，但更新和点查性能通常不如行存，所以不要让 OLTP 核心表盲目列存化。判断标准：如果一条查询要扫描百万行但只取两列，列存收益明显；如果查询总是 WHERE 主键取整行，行存更合适。

3.4 表数据的增删改查与闪回表：数据维护的完整闭环

数据维护部分手册给出了 INSERT、UPDATE、DELETE、SELECT 的标准写法，并单独讲了闪回表。误操作后的恢复命令如下：

FLASHBACK TABLE orders TO TIMESTAMP '2025-01-15 10:00:00';

这条命令把 orders 表恢复到指定时间点的状态，前提是相关参数开启且数据还处在回收窗口内。闪回表确实是误删数据的后悔药，但依赖回收窗口，窗口一过就无能为力。核心表要做定期物理备份，闪回只作为第二道防线。DELETE 全表数据前先确认行数，UPDATE 不带 WHERE 的语句执行前先开一个事务，这些习惯比任何恢复手段都可靠。

BEGIN; UPDATE orders SET status = 'PROCESSING' WHERE order_id = 20240001; SELECT * FROM orders WHERE order_id = 20240001; -- 确认无误后提交 COMMIT;

先 BEGIN 再执行变更，确认结果后再 COMMIT，这是防止语句本身写错导致全表数据被改的最简单手段。手册里反复强调的也是这个操作顺序。

3.5 分区表实践：default 分区与分区键的选择

分区表是 Vastbase 处理大表的主流手段。手册 3.8.8 节讲范围分区和列表分区，并强调支持 default 分区，用于承接所有未命中其他分区边界的数据：

CREATE TABLE logs ( log_time TIMESTAMP, content TEXT ) PARTITION BY RANGE (log_time) ( PARTITION p2024_q1 VALUES LESS THAN ('2024-04-01'), PARTITION p2024_q2 VALUES LESS THAN ('2024-07-01'), PARTITION p_default VALUES LESS THAN (MAXVALUE) );

default 分区是双刃剑。它能防止边界外的数据插入时报错，但一旦分区边界计算错误，本应落在常规分区的数据会全部堆进 default，导致查询扫描数据量异常变大。分区键优先选时间列这种自然维度，并且查询条件必须带上分区键才能触发分区剪枝。判断是否走剪枝的最快方式是 EXPLAIN 看执行计划里扫描的分区数量。

注意：新增分区时如果不调整 default 的边界，原有 default 里的数据不会自动迁到新分区。线上操作前先评估存量数据分布，必要时做一次数据搬移。

4. 应用开发接入实战：JDBC、ODBC 与 libpq 的配置和代码细节

4.1 JDBC 驱动与 JDK 兼容性：选错版本直接加载失败

手册 4.2.1 和 4.2.2 节明确了 Vastbase JDBC 驱动版本与 JDK 版本的对应关系。不同 JDK 大版本需要匹配对应的驱动编译版本，JDK 8 和 JDK 11 的驱动不能直接互换使用。

这个坑在实际项目中非常常见。应用服务器是 JDK 11，驱动 jar 却是按 JDK 8 编译的旧版，加载时直接抛 UnsupportedClassVersionError。解决方式是在官方获取与运行环境匹配的驱动包，下载后先确认 jar 的类文件版本，再部署到应用 lib 目录。驱动放错位置还有个隐蔽版本：classpath 里有多个版本的驱动 jar，类加载器加载了旧的那个，排查时要逐个检查。

验证驱动版本可以用 javap 读取类文件版本：

javap -verbose vastbase_jdbc.jar | grep "major version"

major version 对应关系：52 是 JDK 8，55 是 JDK 11，61 是 JDK 17。我看到版本号不匹配时，第一反应就是替换驱动而不是改代码。

4.2 JDBC 连接与查询：驱动加载、连接参数与结果集处理

JDBC 标准开发流程在手册 4.2.5 节有完整示例，核心骨架如下：

import java.sql.*; import java.util.Properties; public class VastbaseJDBCDemo { public static void main(String[] args) { String url = "jdbc:vastbase://192.168.1.10:15432/postgres"; Properties props = new Properties(); props.setProperty("user", "vastbase"); props.setProperty("password", "your_password"); props.setProperty("prepareThreshold", "1"); try (Connection conn = DriverManager.getConnection(url, props); Statement stmt = conn.createStatement(); ResultSet rs = stmt.executeQuery("SELECT id, name FROM users LIMIT 10")) { while (rs.next()) { System.out.println(rs.getInt("id") + ", " + rs.getString("name")); } } catch (SQLException e) { e.printStackTrace(); } } }

逻辑说明：DriverManager 负责加载驱动并建立连接，Statement 执行 SQL，ResultSet 遍历结果集，最后通过 try-with-resources 自动释放资源。参数说明：prepareThreshold 控制语句预编译的触发阈值，设为 1 表示同一条 SQL 第二次执行就自动走服务端预编译。对高频固定 SQL 效果明显，对动态拼接 SQL 反而增加开销。连接串里的 jdbc:vastbase 是 Vastbase 特有的子协议前缀，和通用的 jdbc:postgresql 不通用。

批量写入场景建议使用 PreparedStatement 的批量接口：

PreparedStatement ps = conn.prepareStatement("INSERT INTO orders (id, amount) VALUES (?, ?)"); for (int i = 1; i <= 1000; i++) { ps.setInt(1, i); ps.setBigDecimal(2, new BigDecimal("10.00")); ps.addBatch(); if (i % 500 == 0) { ps.executeBatch(); } } ps.executeBatch();

setInt、setBigDecimal 按列顺序绑定参数，addBatch 累积批次，每 500 条执行一次。这样能显著减少网络往返，比单条循环执行快很多。

4.3 ODBC 接入流程：unixODBC 安装、数据源配置与测试

ODBC 接入分四步：安装 unixODBC 运行时、注册 Vastbase 驱动库、配置数据源、用 isql 测试连通性。手册 4.3.2 节把这四步拆得更细，包括安装依赖和替换客户端驱动。数据源配置在 odbc.ini 中：

[vastbase_odbc] Driver = Vastbase ODBC Driver Host = 192.168.1.10 Port = 15432 Database = postgres Username = vastbase Password = your_password

配置项说明：Driver 指定驱动名称，需要和 odbcinst.ini 里注册的名称一致；Host 和 Port 决定网络连接位置；Username 和 Password 决定认证身份。配置完成后执行：

isql -v vastbase_odbc

如果返回连接信息和 SQL 提示符，说明数据源配置成功。ODBC 最常见的坑是架构不匹配：64 位 isql 配了 32 位驱动库，或者在 32 位应用环境里装了 64 位驱动。这种情况下 isql 会提示找不到驱动或加载失败，先确认应用和驱动的位数一致再继续排查。

4.4 libpq 开发注意点：连接串格式与错误处理

libpq 是 C 语言客户端接口，手册 4.4 节直接推荐使用连接字符串方式初始化连接：

PGconn *conn = PQconnectdb("host=192.168.1.10 port=15432 dbname=postgres user=vastbase password=your_password"); if (PQstatus(conn) != CONNECTION_OK) { fprintf(stderr, "Connection failed: %s\n", PQerrorMessage(conn)); PQfinish(conn); return -1; }

逻辑说明：PQconnectdb 建立连接句柄，PQstatus 检查连接状态，失败时通过 PQerrorMessage 拿到具体错误文本，程序结束前用 PQfinish 释放。libpq 的错误信息比 JDBC 更原始，经常能直接看到认证失败、SSL 协商失败或端口不通等根因。

编译时链接 pq 库：

cc -o demo demo.c -lpq

-lpq 告诉链接器使用 libpq 动态库。做接入层诊断时，我通常建议先写一个最小可复现程序，排除应用逻辑干扰，这样能把问题快速收敛到网络、认证或驱动三个层面。

4.5 连接池与大数据类型处理：二进制与字符串读写

手册 4.2.9 节建议生产环境使用连接池，池大小按业务峰值估算，避免频繁创建和销毁连接。连接池的初始大小、最大连接数和空闲超时是三个核心参数，最大连接数不要超过数据库服务端允许的上限。

PreparedStatement ps = conn.prepareStatement("INSERT INTO files (id, data, note) VALUES (?, ?, ?)"); ps.setInt(1, 1001); ps.setBytes(2, fileBytes); ps.setString(3, "备注文本"); ps.executeUpdate();

setBytes 对应二进制列，setString 对应字符列。实践中容易出问题的是字符集不一致导致中文乱码，客户端、驱动、数据库三端的编码要保持同一套。手册 4.2.8 节专门提醒了这点，尤其是异构系统迁移时经常出现文件乱码问题。

5. Vastbase 常见问题排查：连接失败、认证报错与配置踩坑记录

5.1 密码正确却提示认证失败

现象：vsql 或 JDBC 连接时输入正确密码，服务端仍返回认证失败，日志里能看到 FATAL 级别的认证错误。

原因：接入认证配置文件里对该用户或该来源网段配置了不匹配的认证方式，或者密码加密方式与客户端不兼容。还有一种常见情况是数据库里存在同名用户，客户端连接的数据库匹配到了另一个用户的认证规则。

解决：先查看认证配置文件中对应的条目，确认当前命中的认证方式；再核对密码是否在近期被重置过。如果改过密码加密参数，重新设置一次密码再连接，必要时把认证方式统一成双方都支持的加密算法。

5.2 远程连接超时或被拒绝

现象：本机 vsql 连接正常，远程客户端连接超时或直接拒绝，报错信息指向网络层。

原因：服务端监听地址只绑定了 localhost；防火墙未放行数据库端口；或者认证文件没有包含远程网段规则，请求被默认策略拒绝。

解决：把监听地址改为实际业务网卡地址并重启服务；确认防火墙放行对应端口；在认证文件里加入允许的远程网段并 reload 生效。排查顺序我固定是：先 ping 网络，再测端口，最后看认证日志，三步能定位九成问题。

5.3 SSL 连接报证书相关错误

现象：启用 SSL 后客户端提示证书不可信、证书过期或主机名不匹配，连接被迫回退或中断。

原因：服务器使用自签名证书，客户端没有把对应 CA 加入信任链；或者证书的 CN 与客户端连接的主机名不一致。手册 5.1.4 节提到用 SSL 进行安全 TCP/IP 连接时，证书链路必须完整。

解决：把自签名证书的 CA 导入客户端信任库，或重新签发与主机名匹配的证书。测试阶段可以在客户端侧临时关闭严格校验，但生产环境不建议，这会让加密形同虚设。

5.4 分区表查询不走分区剪枝

现象：查询条件包含分区键，执行计划却显示扫描了全部分区，响应时间随分区数量线性增长。

原因：分区键被函数包裹，比如 WHERE date(create_time) = '2025-01-01'，优化器无法直接推导分区范围；或者查询参数类型与分区键类型不一致，索引没法直接匹配。

解决：把函数从分区键上去掉，改为范围条件；统一参数类型；用 EXPLAIN 复查执行计划，确认扫描的分区数量符合预期。这条经验同样适用于索引列，对索引列做函数运算基本都会导致索引失效。

5.5 ODBC 数据源测试失败

现象：isql 或应用连接 ODBC 数据源时报错，提示找不到驱动、加载库失败或数据源名称不存在。

原因：驱动路径配置错误；应用位数与驱动位数不匹配；环境变量 LD_LIBRARY_PATH 没有指向驱动目录；odbc.ini 与 odbcinst.ini 中的名称不一致。

解决：逐一核对 odbcinst.ini 的驱动路径、应用位数、环境变量，修正后重新测试。ODBC 踩坑时先用 isql 验证，不要直接改应用代码，把环境问题定位清楚再动应用层。

6. 进阶落地：接入认证配置与 vb_basebackup 备份恢复实操

6.1 客户端接入认证：认证文件规则速查

手册 5.1 节的接入认证配置，规则格式与 PostgreSQL 生态的体系一致。每一行由连接类型、数据库名、用户名、来源地址和认证方式组成，规则从上到下匹配，命中的第一条生效。生产环境我习惯把远程账号收敛到具体网段，认证方式优先使用带强加密的选项，禁止用宽松的 trust 方式。常用认证方式对比：trust 免密只适合本地调试；md5 兼容性好；scram-sha-256 安全性更高。指定网段、明确用户、用强认证，这三条做到位，接入层基本不会出大问题。

6.2 SSL 证书生成：让 TCP/IP 连接加密

手册 5.1.3 节给出证书生成流程，核心是两步：生成自签名 CA 证书，再生成服务器证书并用 CA 签名，最后把证书和私钥放到服务端配置目录，开启 SSL 参数。验证方式很简单，客户端连接时开启 SSL，连接成功后查看会话状态即可确认加密链路已生效。自签名证书用于测试环境足够，生产环境建议对接已有 CA 体系。证书过期是这类配置里最容易被忽略的隐患，建议在证书到期前一个月就规划替换窗口。

6.3 vb_basebackup 备份为 tar 格式：备份与表空间级恢复

手册 3.11.6 和 3.11.7 节介绍了 vb_basebackup 的 tar 格式备份：

vb_basebackup -h 127.0.0.1 -p 15432 -U vastbase -D /backup/tar -F tar -X stream

参数说明：-F tar 指定备份格式为 tar，-X stream 表示流式复制预写日志，-D 指定备份输出目录。备份完成后，恢复时把 tar 包解开到目标数据目录，确保目录权限正确，再启动数据库实例。表空间备份需要额外指定表空间映射，恢复时路径发生变化要重新建立符号链接或映射关系。

从那以后，我每次做 Vastbase 备份演练都强制走一遍「备份—校验—恢复」三件套，先在一个临时实例上完成恢复验证再收工。备份文件能生成不代表能恢复，只有真正恢复成功后这份备份才算有效，希望这个习惯能帮到正在搭建备份方案的你。

本文还有配套的精品资源，点击获取