PHP 使用 Pdo_kdb 驱动连接 Kingbase 数据库需先配置环境。介绍如何根据 PHP 版本和线程安全模式选择对应驱动包，分别在 Linux、Windows 及 PHP-FPM 环境下安装部署。通过修改 php.ini 加载扩展并验证模块。提供连接字符串编写、建表、插入查询等完整代码示例，涵盖参数绑定与异常处理。最后总结常见问题如依赖库缺失、符号未定义及 Schema 搜索路径设置，帮助开发者实现国产数据库的高效集成。
在数字化转型的浪潮中，国产数据库正以惊人的速度崛起。作为人大金仓自主研发的核心产品，KingbaseES 凭借其与 PostgreSQL 的高度兼容性、金融级安全特性以及国产化适配优势，已成为政企领域替代 Oracle 的主流选择。然而，对于 PHP 开发者而言，如何高效连接并操作这款国产数据库却成为一道技术门槛。
本文将通过实战案例 + 原理剖析 + 避坑指南的三维视角，系统讲解如何通过 PHP 的 PDO_KDB 驱动实现与 Kingbase 数据库的无缝连接。从环境搭建到 CRUD 操作，从异常处理到性能优化，构建安全可靠的国产化应用。
KingbaseES（人大金仓数据库管理系统）作为国产数据库的代表，具有以下核心优势：
尽管 KingbaseES 与 PostgreSQL 高度兼容，但直接使用 PHP 的 PDO_PGSQL 驱动连接时仍会遇到：
为解决上述问题，人大金仓官方推出了PDO_KDB专用驱动。该驱动：
Pdo_kdb 驱动对 PHP API 版本有严格要求，一般要求 Pdo_kdb 驱动与 PHP 版本完全一致，如 PHP8.0.28 版本最好使用 PHP8.0.28 编译出的 Pdo_kdb 驱动。
PHP 有线程安全 (Thread Safe，简称 TS) 与非线程安全 (Non-Thread Safe，简称 NTS) 版本，Pdo_Kdb 驱动也需要与 PHP 版本是否线程安全相对应，可通过 php -v 查看当前环境的 PHP 版本是否线程安全，以下是 PHP8.0.28 非线程安全版本说明输出的示例：
$ php -v PHP7.2.0(cli)(built: Aug 15 2024 16:59:37)(NTS)Copyright(c)1997-2017 The PHP Group Zend Engine v3.2.0,Copyright(c)1998-2017 Zend Technologies
以下是 Kingbase 默认提供的 Pdo_kdb 驱动包版本：
| PHP 版本 | 是否线程安全 |
|---|---|
| 5.6.22 | 非线程安全 (NTS) |
| 7.2.0 | 非线程安全 (NTS) |
基于 Pdo_kdb 编译开发应用程序，主要步骤如下：
安装部署 PHP 驱动 Pdo_kdb -> 测试能否成功加载 Pdo_kdb 驱动 -> 编写应用程序 -> 运行
下文将通过具体示例说明如何使用 PHP 驱动连接操作数据库：
查看当前环境架构及 PHP 版本，选用合适的 PHP 驱动 Pdo_kdb。
命令行执行 php -v，执行查看 PHP 版本：
$ php -v PHP7.2.0(cli)(built: Aug 15 2024 16:59:37)(NTS)Copyright(c)1997-2017 The PHP Group Zend Engine v3.2.0,Copyright(c)1998-2017 Zend Technologies
当前环境使用的是 x86_64 PHP7.2.0 非线程安全版本，需要使用对应 x86_64 架构的 PHP7.2.0 非线程安全的 Pdo_kdb 驱动包。
可在浏览器输入以下 URL 下载对应版本的驱动（参考 Pdo_kdb 产品手册）：
https://kingbase.oss-cn-beijing.aliyuncs.com/KES_INTERFACE/history/PHP/all/r6/PDO/x86_64/uzts/v9_pdo_kdb_for_php-7.2.0_x86_64_uzts.tar.gz
一般可通过单独编译安装指定版本 PHP，也可通过集成环境安装 PHP，而 WEB 应用实际多是用的 PHP-FPM，故实际生产环境的 PHP 环境无法一言以蔽之，以下以命令行 PHP 环境及 PHP-FPM 环境作简要的 Pdo_kdb 驱动的安装部署说明。
命令行 PHP 环境的加载对应驱动，将 Pdo_kdb 放置在 PHP 安装路径的
lib/php/extensions/no-debug-non-zts-20170718
路径下，再通过 php.ini 配置 Pdo_kdb，最后使用 php -m 命令查看驱动是否成功加载，示例具体步骤如下：
若本地 PHP7.2.0 安装在 /home/kingbase/php/php-7.2.0 路径下，则 PHP 默认驱动的安装路径为 /home/kingbase/php/php-7.2.0/lib/php/extensions/no-debug-non-zts-20170718，否则默认为 /usr/local/lib/php/extensions/no-debug-non-zts-20170718 路径下，如下表所示：
| 安装方式 | PHP 可执行文件路径 | 驱动安装路径 |
|---|---|---|
| 指定路径 | /home/kingbase/php/php-7.2.0/bin/php | /home/kingbase/php/php-7.2.0/lib/php/extensions/no-debug-non-zts-20170718 |
| 默认路径 | /usr/local/bin/php | /usr/local/lib/php/extensions/no-debug-non-zts-20170718 |
将 Pdo_kdb 驱动包解压后得到的库全部拷贝到上述驱动安装路径下即可。
备注 PHP 拓展模块默认安装路径，可在命令行执行
php -i | grep extension_dir
查看对应模块拓展路径。
执行 php --ini 查看 PHP 配置文件路径：
$ php --ini Configuration File(php.ini) Path:/home/kingbase/php/php-7.2.0/lib Loaded Configuration File:/home/kingbase/php/php-7.2.0/lib/php.ini Scan for additional .ini files in:(none) Additional .ini files parsed:(none)
修改 /home/kingbase/php/php-7.2.0/lib/php.ini 的 php.ini 文件，在 extension=pdo; 下方添加一行 extension=pdo_kdb;，让 PHP 能加载 Pdo_kdb 驱动。
extension 也可配置全路径的形式，诸如：extension=/home/kingbase/pdo_kdb.so; 去加载指定路径的 Pdo_kdb 驱动。
修改配置文件后，执行 php -m 查看 Pdo_kdb 是否加载成功，以下是加载成功的正常输出：
$ php -m [PHP Modules]...PDO pdo_kdb ...
此时执行 php -m 出现报错，请参考常见问题说明。
Windows 环境大多数 PHP 环境是直接使用的 PHP 安装包的形式，PHP 驱动包的安装路径相对固定，以下是一个 PHP 安装包的安装路径示例：
| 安装方式 | PHP 可执行文件路径 | 驱动安装路径 |
|---|---|---|
| 安装包 | D:\PHP_install\php-7.2.0 | D:\PHP_install\php-7.2.0\ext |
Pdo_kdb 驱动安装的具体步骤如下：
将 Pdo_kdb 驱动包解压后得到的库 php_pdo_kdb.dll 拷贝到上述驱动安装路径下即可。
需要注意的是 Windows 加载 DLL 的顺序，需要将 Pdo_kdb 驱动的依赖库 libkci.dll 及其依赖库 (即驱动包内非 Pdo_kdb 的库) 拷贝到 PHP 可执行文件路径下，对应上述表格的 D:\PHP_install\php-7.2.0 路径，否则 Windows 无法成功识别对应库导致 PHP 加载 Pdo_kdb 失败。
也可在 Windows 加载 DLL 的任一默认路径放置 Pdo_kdb 驱动的依赖库，本文不对此作详细描述。
执行 php --ini 查看 PHP 配置文件路径：
$ php --ini Configuration File(php.ini) Path:C:\Windows Loaded Configuration File:C:\Windows\php.ini Scan for additional .ini files in:(none) Additional .ini files parsed:(none)
修改 C:\Windows\php.ini 的 php.ini 文件，在 extension=pdo; 下方添加一行 extension=pdo_kdb;，让 PHP 能加载 Pdo_kdb 驱动。
extension 也可配置全路径的形式，诸如：extension=D:\PHP_install\php_pdo_kdb.dll; 去加载指定路径的 Pdo_kdb 驱动。
修改配置文件后，执行 php -m 查看 Pdo_kdb 是否加载成功，以下是加载成功的正常输出：
$ php -m [PHP Modules]...PDO pdo_kdb ...
此时执行 php -m 出现报错，请参考常见问题说明。
PHP-FPM(PHP FastCGI Process Manager)，PHP FastCGI 进程管理器，用于管理 PHP 进程池的软件，用于接受 Web 服务器的请求。
PHP-FPM 主要用于 Web 应用，会有单独的进程处理 HTTP 请求。
从驱动安装部署的角度理解，用户开发环境的命令行执行 php -m 后发现安装了 Pdo_kdb 驱动，但并不一定在 Web 应用使用的 PHP 也安装了对应的 Pdo_kdb，因为命令行使用的 PHP 和 Web 应用使用的 PHP 可能不是同一个。
Web 应用部署的服务器多在 Linux 环境上，下文以 Linux 环境 PHP-FPM 安装部署 Pdo_kdb 作简要说明：
若已知当前 Web 应用使用的 PHP 的驱动安装路径，则将 Pdo_kdb 驱动包解压放置在对应路径下。
若不清楚，也通过当前命令行环境执行 PHP-FPM 进程，如 php-fpm -m 查看是否有输出，若有，可参考命令行执行 PHP 的步骤添加 Pdo_kdb 驱动。
若不清楚 PHP 驱动安装路径，当前命令行环境也没有对应 PHP-FPM 进程，则跳过该步骤，参考下方修改配置文件步骤，修改 extension_dir 参数，让 PHP 加载指定路径的 Pdo_kdb 驱动。
在当前 Web 开发环境下，浏览器可访问的 PHP 源文件开头，添加 phpinfo();，用于查看当前 Web 应用使用的 PHP 的详细信息：
如上图所示，可以清晰地看到 PHP 版本及对应参数信息，其中需要我们关注的是 Loaded Configuration File 栏对应的 php.ini 路径，有的 PHP-FPM 还会加载 Loaded Configuration File 下方两栏对应的额外配置文件，对应 conf.d 路径。
PHP 会优先读取 conf.d 路径下的额外配置文件，再读取 php.ini。
若存在 conf.d 路径的额外配置文件，需要找到该路径下的配置文件有包含 pdo 模块的文件，在 extension=pdo; 下方添加一行 extension=pdo_kdb;，让 PHP 能识别并加载 Pdo_kdb 驱动。
若不存在 conf.d 路径，则直接修改 php.ini 配置文件，在 extension=pdo; 下方添加一行 extension=pdo_kdb; 即可。
备注： 若不清楚 PHP 加载模块路径，也可修改 php.ini 配置文件的 extension_dir 参数，让 PHP 读取指定路径下的 Pdo_kdb 驱动。
修改配置文件后，浏览器刷新页面，查看 phpinfo(); 对应的网页，ctrl+f 搜索是否有 pdo_kdb 加载，若没有，可按以下步骤依次排查：
• PHP 加载依赖库失败
可在命令行执行 ldd pdo_kdb.so 查看系统默认的加载路径是啥，并将 pdo_kdb 驱动的依赖库放置到系统路径下，以下是一个具体示例：
$ ldd pdo_kdb.so ... libc.so.6=>/lib64/libc.so.6(0x0000fffe1cde0000)...
执行 ldd 后，将打印当前环境变量下的默认搜索路径，如示例所示，当前系统默认搜索 /lib64 下的动态库。
将 Pdo_kdb 驱动包内非 pdo_kdb.so 的所有 so 库拷贝到 /lib64 路径下即可。
• PHP 读取到其他的配置文件
若使用了集成环境，如：宝塔、phpstudy 等，对应 PHP 配置文件需要在集成环境页面 PHP 设置页修改，在 extension=pdo; 下方添加一行 extension=pdo_kdb; 即可。
• PHP-FPM 进程需要重启
若当前环境有常驻的 PHP-FPM 进程，则需要在修改 php.ini 配置文件后，重启 PHP-FPM 进程。
按上述步骤排查后，刷新页面，可在网页看到 pdo_kdb 加载成功。
确保 PHP 已成功加载 Pdo_kdb 驱动的前提下，此时可编写测试用例连接并操作数据库，以下是一个具体的操作示例：
创建连接：
$dbh = new PDO($dsn, $user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION));
// 例：
$dbh = new PDO("kdb:host=127.0.0.1;dbname=test;port=54321;", "system", "123456", array(PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION));
使用刚刚创建的 $dbh 对象执行建表语句：
$stmt = $dbh->prepare('drop table if exists test_kdb');
$stmt->execute();
$stmt = $dbh->prepare('create table test_kdb(id int, name varchar(20))');
$stmt->execute();
绑定参数，并执行插入：
# 插入
$name = 'kingbase';
$stmt = $dbh->prepare("insert into test_kdb values(1, :name)");
$stmt->execute(array($name));
插入成功后，执行查询，并打印结果集：
$id = 1;
$stmt = $dbh->prepare('select * from test_kdb where id=?');
$stmt->execute(array($id));
$res = $stmt->fetchAll();
var_dump($res);
完整示例如下：
<?php
$dsn = "kdb:host=127.0.0.1;dbname=test;port=54321;";
$user = 'system';
$password = '123456';
$dbh = null;
$dbh = new PDO($dsn, $user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION));
$stmt = $dbh->prepare('drop table if exists test_kdb');
$stmt->execute();
$stmt = $dbh->prepare('create table test_kdb(id int, name varchar(20))');
$stmt->execute();
# 插入
$name = 'kingbase';
$stmt = $dbh->prepare("insert into test_kdb values(1, :name)");
$stmt->execute(array($name));
# 查询
$id = 1;
$stmt = $dbh->prepare('select * from test_kdb where id=?');
$stmt->execute(array($id));
$res = $stmt->();
();
示例期望输出如下：
array(1){[0]=>array(4){["id"]=>int(1)[0]=>int(1)["name"]=>string(8)"kingbase"[1]=>string(8)"kingbase"}}
php -m，报错：libkci.so.5: cannot open shared object file: No such file or directory
Pdo_kdb 驱动依赖 Libkci 库 (老版本会依赖 Libpq 库)，系统加载 Pdo_kdb 时，无法加载 Pdo_kdb 驱动的依赖库及其依赖导致的问题
处理：
将 Libkci 及其驱动包 (老版本为 Libpq) 放置在 ldd pdo_kdb.so 的系统默认搜索路径下即可。php -m，报错：undefined symbol: pdo_parse_params
PHP 未成功加载 PDO 模块的前提下加载 Pdo_kdb 驱动导致的问题。
处理：
将 extension=pdo_kdb 的配置放置在 extension=pdo 下方即可。php -m，报错：undefined symbol: file_globals_id
PHP 是否线程安全与 Pdo_kdb 驱动包的是否线程安全版本不一致，如：PHP 非线程安全版本使用的线程安全版本的 Pdo_kdb 驱动。
处理：
使用线程安全版本一致的 Pdo_kdb 驱动包。# 如期望搜索 newschema 这个 schema 下的表
$dsn = "kdb:host=127.0.0.1;dbname=test;port=54321;options='-csearch_path=newschema'";
$dbh = new PDO($dsn, $user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION));
KingbaseES 数据库兼具国产数据库的高性能与高可用特性，为各类应用场景提供可靠支持。无论是传统行业数字化转型，还是互联网创新项目，KingbaseES 都能作为理想的数据访问层解决方案。同时，该数据库提供完善的迁移支持，可轻松应对 Oracle/MySQL 等数据库迁移需求，并为使用 PHP 驱动 Pdo_kdb 的开发者提供良好开发体验。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online