【Kingbase应用接入与连接池治理】JDBC驱动与连接串实战

JDBC 驱动与连接串实战：从默认 system/test 到业务库与应用账号

这篇文章有个前提要说清楚：默认你已经把基础环境弄好了，我这里以Windows客户端和Linux服务端为例，也就是说 Windows 11 本地开发机能访问 CentOS 7.6 服务器，金仓数据库实例已经跑起来，端口、防火墙、远程访问规则也都配好了。Windows 安装、CentOS 安装，还有 Windows 连 CentOS 上的数据库这几块，前面的文章里已经单独讲过，这里不再重复。

前置教程可参考：

• Windows 本地安装金仓数据库教程：Windows系统下KingbaseES数据库保姆级安装教程（附常见问题解决）
• CentOS 服务器安装金仓数据库教程：CentOS 上安装KingbaseES（ISO包）详细教程_金仓数据库安装教程-CSDN博客
• Windows 连接 CentOS 服务器上的金仓数据库：《Kingbase护城河》------跨平台环境下的数据库联调实战-CSDN博客

应用连接数据库失败，往往不是业务代码复杂，而是最基础的三件事没对齐：驱动包、连接串、账号权限。本文从刚安装完成后的默认状态开始，先用 system 账号连接默认 test 数据库，再创建本专栏后续统一使用的业务库、Schema、应用账号和测试表，最后用一个最小 Java 程序完成 JDBC 查询验证。

@toc

---

一、实验目标

本篇要完成五件事：

• 使用默认 system/test 连接远端服务器。
• 创建后续专栏统一使用的业务库和账号。
• 写出可读、可复用的连接串。
• 准备 JDBC 驱动。
• 用 Java 程序查询远端数据库中的测试表。

统一环境如下，表中 IP 仅为示例，实际使用时替换为自己的服务器地址：

项目	示例值
本地系统	Windows 11
服务端系统	CentOS 7.6
数据库服务端 IP	192.168.10.101
数据库端口	54321
初始数据库	test
初始用户	system
业务数据库	kb_app
业务 Schema	shop
应用账号	app_user
只读账号	report_user
测试表	shop.t_connection_check

开始写 Java 代码前，先用默认账号确认这条链路已经能手工连接：

ksql -h 192.168.10.101 -p 54321 -U system -d test

这里如果还连不上的话，先回到跨平台连接教程排查网络、监听地址、防火墙和认证规则。本专栏从"默认 system/test 已经能远程连接"这个前提出发。

二、创建业务库、Schema 和应用账号

默认的那个 test 数据库，适合做初始验证。但是直接拿它做后续应用开发的库，不太建议。那咱们先用 system 用户建一个业务库 kb_app：

CREATE DATABASE kb_app;

退出当前连接。接着重新连到 kb_app：

ksql -h 192.168.10.101 -p 54321 -U system -d kb_app

然后咱们建业务Schema、应用账号还有只读账号：

CREATE SCHEMA shop;

CREATE USER app_user WITH PASSWORD 'App_user_123';
CREATE USER report_user WITH PASSWORD 'Report_user_123';

GRANT USAGE ON SCHEMA shop TO app_user;
GRANT USAGE ON SCHEMA shop TO report_user;
GRANT CREATE ON SCHEMA shop TO app_user;

如果你环境里已经有同名数据库、Schema或者用户了。那你先确认一下，它们是不是本文要弄的这些。如果不是的话，我建议你换个业务库名或者账号名。这样能避免误操作已有环境。

接着咱们建本专栏第一张测试表：

CREATE TABLE shop.t_connection_check (
    id INT PRIMARY KEY,
    check_name VARCHAR(64),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO shop.t_connection_check(id, check_name)
VALUES (1, 'jdbc_check_ready');

给应用账号读写权限。只读账号给个查询权限就行：

GRANT SELECT, INSERT, UPDATE, DELETE ON shop.t_connection_check TO app_user;
GRANT SELECT ON shop.t_connection_check TO report_user;

最后用应用账号验证一次：

ksql -h 192.168.10.101 -p 54321 -U app_user -d kb_app

进去后执行：

SELECT current_database(), current_user;
SELECT * FROM shop.t_connection_check;

要是你能看到 kb_app、app_user 还有 jdbc_check_ready 这条记录。那就说明，后面需要的基础对象都准备好了。

三、准备 JDBC 驱动

JDBC驱动这个东西，通常来说，在金仓数据库安装目录、客户端工具目录，或者官方提供的驱动包里都能找到。本文Windows安装目录示例用的是 D:\Tools\Kingbase。你安装路径不一样的话，记得换成自己的实际目录。

在Windows 11上咱们可以先搜一下驱动包。下面这个命令是以我本机路径为例的。执行的时候把 $kbHome 换成你自己的实际安装目录就行：

$kbHome = "D:\Tools\Kingbase"

Get-ChildItem -LiteralPath $kbHome -Recurse -File -Filter "kingbase*.jar" -ErrorAction SilentlyContinue |
    Where-Object { $_.FullName -like "*\Interface\jdbc\*" } |
    Select-Object FullName

我环境里搜到的 KingbaseES V9R2C13 JDBC 驱动路径是这样的：

D:\Tools\Kingbase\KESV9R2C13\KES\KESRealPro\V009R002C013\Interface\jdbc\kingbase8-9.0.0.jar

同一个目录下，你可能还会看到 kingbase8-9.0.0.jre6.jar、kingbase8-9.0.0.jre7.jar 这种。这种是兼容旧 JRE 的包。咱们本地用的 JDK 比较新的话，直接选 kingbase8-9.0.0.jar 就行了。

找到 JDBC 驱动后，我建议你统一复制到项目的 lib 目录。比如像这样：

kb-jdbc-demo
|-- lib
|   `-- kingbase8-9.0.0.jar
|-- src
|   `-- DbConnectCheck.java

复制命令如下：

New-Item -ItemType Directory -Force -Path .\lib

Copy-Item -LiteralPath "D:\Tools\Kingbase\KESV9R2C13\KES\KESRealPro\V009R002C013\Interface\jdbc\kingbase8-9.0.0.jar" `
    -Destination ".\lib\kingbase8-9.0.0.jar" `
    -Force

如果你项目用的是 Maven 或者 Gradle。那优先按企业层级里的内部制品库，或者官方推荐的方式去引入驱动。本文为了减少前置依赖，先用最小Java文件演示一下。

四、理解连接串

应用连接数据库的核心就是 JDBC URL。示例形式如下：

jdbc:kingbase8://192.168.10.101:54321/kb_app

其实拆开来看很简单，就是几段拼在一起：

• jdbc:kingbase8：JDBC 协议和驱动识别前缀，以实际驱动说明为准。
• 192.168.10.101：CentOS 数据库服务器 IP。
• 54321：数据库监听端口。
• kb_app：刚才创建的业务数据库名。

如果你的环境启用了额外安全参数或字符集参数，需要按驱动文档追加到 URL 后面。初次接入的话，不建议一次性堆很多参数，先用最小连接串打通，再逐步增加连接超时、应用名等参数。

五、编写最小 Java 连接程序

新建 src\DbConnectCheck.java：

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;

public class DbConnectCheck {
    public static void main(String[] args) throws Exception {
        String url = "jdbc:kingbase8://192.168.10.101:54321/kb_app";
        String user = "app_user";
        String password = "App_user_123";

        String sql = "select id, check_name, created_at from shop.t_connection_check where id = ?";

        try (Connection conn = DriverManager.getConnection(url, user, password);
             PreparedStatement ps = conn.prepareStatement(sql)) {

            System.out.println("connected=" + !conn.isClosed());
            ps.setInt(1, 1);

            try (ResultSet rs = ps.executeQuery()) {
                if (rs.next()) {
                    System.out.println("id=" + rs.getInt("id"));
                    System.out.println("check_name=" + rs.getString("check_name"));
                    System.out.println("created_at=" + rs.getTimestamp("created_at"));
                } else {
                    System.out.println("no data found");
                }
            }
        }
    }
}

这段代码有几个值得注意的地方：

• 使用 PreparedStatement，不要把参数直接拼到 SQL 字符串里。
• 使用 try-with-resources，确保连接、语句、结果集都能正常关闭。
• SQL 显式写业务 Schema，避免依赖默认 Schema 搜索路径。

六、在 Windows 11 上编译运行

进入项目目录：

cd D:\work\kb-jdbc-demo

编译：

javac -encoding UTF-8 -cp ".;lib\kingbase8-9.0.0.jar" src\DbConnectCheck.java

运行：

java -cp ".;lib\kingbase8-9.0.0.jar;src" DbConnectCheck

如果输出类似下面内容，说明 JDBC 链路已经打通：

如果命令执行后很快返回但没有任何结果，通常不是程序"卡住了"，而是查询没有打印出可见信息。上面的示例会先输出 connected=true，再输出查询结果。如果看到 no data found 的话，说明连接已经成功，但 shop.t_connection_check 中没有 id = 1 这条记录，需要回到前面的建表和插入步骤检查一下。

如果你使用的是 PowerShell，注意 classpath 分隔符在 Windows 上是分号 ;。在 Linux 上运行的话，分隔符一般是冒号 :。

七、把连接信息从代码里抽出来

上面的写法适合第一次验证，但不适合长期维护。连接信息不应该硬编码在 Java 类里。

可以先建一个简单的配置文件 db.properties：

db.url=jdbc:kingbase8://192.168.10.101:54321/kb_app
db.user=app_user
db.password=App_user_123

Java 中读取配置：

import java.io.FileInputStream;
import java.sql.Connection;
import java.sql.DriverManager;
import java.util.Properties;

public class DbConfigCheck {
    public static void main(String[] args) throws Exception {
        Properties props = new Properties();
        try (FileInputStream in = new FileInputStream("db.properties")) {
            props.load(in);
        }

        try (Connection conn = DriverManager.getConnection(
                props.getProperty("db.url"),
                props.getProperty("db.user"),
                props.getProperty("db.password"))) {

            System.out.println("connected=" + !conn.isClosed());
            System.out.println("database=" + conn.getCatalog());
        }
    }
}

这样做的好处是，后续迁移到 Spring Boot、测试环境、生产环境时，连接信息可以交给配置中心、环境变量或启动参数管理，不需要动代码。

八、连接成功后要验证什么

不要只看到程序没有报错就算接入成功。至少做三类验证。

1. 身份验证

确认当前连接到底使用了哪个数据库和哪个账号：

SELECT current_database(), current_user;

可以在 Java 程序里执行这条 SQL，也可以通过 ksql 对比。

2. 权限验证

用 app_user 测试正常读写：

INSERT INTO shop.t_connection_check(id, check_name)
VALUES (2, 'jdbc_insert_ok');

SELECT * FROM shop.t_connection_check WHERE id = 2;

再用 report_user 连接 kb_app 测试只读，确认它能查询 shop.t_connection_check，但不能执行写入操作。

3. 异常验证

故意把密码写错，看应用是否能清晰输出认证失败；故意把 IP 写错，看是否有连接超时；故意把表名写错，看是否能定位 SQL 错误。上线前提前看过这些错误，后面排障会快很多。

九、常见错误

1. 找不到驱动类或协议不识别

通常是 JDBC jar 没放进 classpath，或者驱动版本和连接串前缀不匹配。先确认运行命令里包含了驱动 jar。

2. Connection refused

这不是 Java 代码问题，优先回到前置跨平台连接教程，检查端口监听、防火墙、安全组和数据库监听地址。

3. 认证失败

检查用户名、密码、数据库名、认证规则和账号是否被锁定。本文前半部分使用 system/test 做初始连接，后半部分使用 app_user/kb_app 做应用连接，排查时不要把这两组账号和数据库混在一起。

4. relation 或 table 不存在

如果表确实存在，重点检查 Schema。建议 SQL 中明确写 shop.t_connection_check，不要依赖默认搜索路径。

5. 中文乱码

先确认数据库、客户端、Java 源文件、控制台输出编码。Windows 命令行环境下可以优先使用 PowerShell，并在编译时指定 -encoding UTF-8。

十、小结

JDBC 接入的核心不是写多少代码，而是把驱动、连接串、账号权限和验证 SQL 做对。本文从默认 system/test 起步，创建了后续专栏统一使用的 kb_app、shop、app_user、report_user 和 shop.t_connection_check，并用最小 Java 程序完成了第一次 JDBC 查询验证。

下一篇我们进入 Spring Boot，把单文件连接验证升级成更贴近真实项目的应用配置方式。