KingbaseES客户端编程接口指南-PHP_PDO.pdf

KingbaseES 客户端编程接口指南-PHP-PDO 金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024） 发布日期：2023 年 10 月 12 日 北京人大金仓信息技术股份有限公司 目 目 录 录 第 1 章 前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.4 手册约定 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 概述 3 2.1 PHP PDO 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 KingbaseES PHP PDO 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 第 3 章 PHP 配置连接 KingbaseES 4 3.1 Linux 下 PHP 配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2 Linux 平台上支持的 PHP 版本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 第 4 章 KingbaseES PDO 的函数说明 5 4.1 PDO 标准模块 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.2 KingbaseES 函数（PDO_KDB） . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 第 5 章 PDO 示例 8 版权声明 10 服务周期承诺 11 I 第 1 章 前言 1 第 章 前言 本文档描述了 KingbaseES 对 PHP PDO 的兼容情况，指导如何使用 PHP PDO 连接 KingbaseES 数据库。 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 《KingbaseES PHP PDO 指南》面向所有使用 KingbaseES 数据库的用户，主要是数据库管理员和应用程序开 发人员。 在开始阅读本文档之前，您需要了解以下内容： PHP PDO 的安装/配置 1.2 相关文档 有关 PHP PDO 的更多信息，请参阅以下资源： PHP:PDO - Manual 1 第 1 章 前言 1.3 术语 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 2 第 2 章 概述 2 第 章 概述 • PHP PDO 简介 • KingbaseES PHP PDO 简介 2.1 PHP PDO 简介 PHP PDO（数据对象）扩展为 PHP 访问数据库定义了一个轻量级的一致接口。实现 PDO 接口的每个数据库驱 动可以公开数据库的特性作为标准扩展功能。 PDO 提供了一个数据访问抽象层，不管使用哪种数据库，都可以使用相同的函数来查询和获取数据。PDO 不提 供数据库抽象层，它不会重写 SQL，也不会模拟缺失的特性，需要使用一个完整的抽象层来完成数据库操作。 2.2 KingbaseES PHP PDO 简介 利用 PDO 扩展本身并不能实现任何数据库功能，必须使用一个具体的数据库驱动来访问数据库服务。 KingbaseES PHP 是通过 PHP 提供的 ZEND ENGINE 来开发的针对 PHP 访问 KingbaseES 服务器的驱动程 序。通过 KingbaseES PHP 库，应用程序可以完成与数据库的连接、执行 SQL 语句、从数据库中获取结果、获取状 态及错误信息、终止连接等操作。 本手册的内容主要是描述 PHP 如何通过 KingbaseES 提供的库访问 KingbaseES ，KingbaseES 为 PHP 提供的 库文件名在 Linux 平台下为 pdo_kdb.so。 3 第 3 章 PHP 配置连接 KINGBASEES 3 第 章 PHP 配置连接 KingbaseES 本节主要介绍在 Linux 平台下如何将 KingbaseES 库添加为 PHP 的扩展库。 • Linux 下 PHP 配置 • Linux 平台上支持的 PHP 版本 3.1 Linux 下 PHP 配置 1. 打开 PHP 目录下的 php.ini ，找到 extension_dir=”./”，修改其为 pdo_kdb.so 文件所在目录的路径。 2. 添加扩展库，在 php.ini 中找到“;extension=*.so”(前面的“;”表示注释)。 3. 添加 extension=pdo_kdb.so ，表示将 KingbaseES 库作为扩展库供 PHP 加载。 4. 验证是否加载成功，在 php 的安装目录下找到程序 php，在当前路径下，在终端程序中运行./php -m（最好安 装 php 在默认路径 /usr/local 下，可以直接在终端运行程序 php -m），查看输出列表中是否有“pdo_kdb”， 如果有表示加载成功，没有表示加载失败。 3.2 Linux 平台上支持的 PHP 版本 pdo_kdb 的版本需要和 php 版本相对应，否则会出现版本不匹配或者在 php -m 显示扩展时，提示找不到驱动。 PHP 目前在 x86 和飞腾环境下支持 php5.5.3 至 8.0.12 版本，其它平台支持以官网版本为准，PHP 多版本驱动 下载路径：https://bbs.kingbase.com.cn/thread-14457-1-1.html?_dsign=87f12756 4 第 4 章 KINGBASEES PDO 的函数说明 4 第 章 KingbaseES PDO 的函数说明 本章节介绍了 PDO 的组成模块，以及 KingbaseES 实现 PHP 数据对象接口的 PDO_KDB 函数用法。 • PDO 标准模块 • KingbaseES 函数（PDO_KDB） 4.1 PDO 标准模块 具体参考 PHP 标准手册, 主要分为以下几部分。 a. PDO 类 代表 PHP 和数据库服务之间的一个连接，更多信息请参见 PHP 官网文档。 b. PDOStatement 类 代表一条预处理语句，并在该语句被执行后返回一个相关的结果集，更多信息请参见 PHP 官网文档。 c. PDOException 类 代表一个由 PDO 产生的错误。在正确的代码中不应抛出一个 PDOException 异常。关于 PHP 异常的更多信息 请参见 PHP 官网文档。 4.2 KingbaseES 函数（PDO_KDB） PDO_KDB 是一个驱动程序，它实现了 PHP 数据对象（PDO）接口，以此支持从 PHP 到 KingbaseES 数据库 的访问。 a. DSN 语法格式： $dsn = 'kdb:host=localhost;dbname=TEST;port=54321'; 5 第 4 章 KINGBASEES PDO 的函数说明 功能： 连接到 KingbaseES 数据库。 b. kdbCopyFromArray 语法格式： public bool PDO::kdbCopyFromArray ( string $table_name , array $rows [, string $delimiter = '\t' [, string $null_as = "\\\\N" [, string $fields ]]] ) 功能： 将数据从 PHP 数组复制到表中。 c. kdbCopyFromFile 语法格式： public bool PDO::kdbCopyFromFile ( string $table_name , string $filename [, string $delimiter = '\t' [, string $null_as = "\\\\N" [, string $fields ]]] ) 功能： 将文件中的数据复制到表中。 d. kdbCopyToArray 语法格式： public array PDO::kdbCopyToArray ( string $table_name [, string $delimiter = '\t' [, string $null_as = "\\\\N" [, string $fields ]]] ) 功能： 将数据库表中的数据复制到 PHP 数组中。 e. kdbCopyToFile 语法格式： public bool PDO::kdbCopyToFile ( string $table_name , string $filename [, string $delimiter = '\t' [, string $null_as = "\\\\N" [, string $fields ]]] ) 功能： 6 第 4 章 KINGBASEES PDO 的函数说明 将表中的数据复制到文件中。 f. kdbLOBCreate 语法格式： public string PDO::kdbLOBCreate ( void ) 功能： 创建一个新的大对象。 g. kdbLOBOpen 语法格式： public resource PDO::kdbLOBOpen ( string $oid [, string $mode = "rb" ] ) 功能： 打开现有的大型对象流。 h. kdbLOBUnlink 语法格式： public bool PDO::kdbLOBUnlink ( string $oid ) 功能： 删除大对象。 7 第5章 5 第 章 PDO 示例 PDO 示例 您可前往 人大金仓官网 下载 PHP 测试用例 。 下面给出示例，描述了如何通过 KingbaseES PDO 访问 KingbaseES 数据库。 a. 数据库连接示例 $dsn = 'kdb:host=localhost;dbname=TEST;port=54321'; $user = 'SYSTEM'; $password = '123456'; $dbh = null; try { $dbh = new PDO($dsn,$user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION)); } catch (Exception $e) { echo 'Connection Failed: ' . $e->getMessage() ."\n"; } return $dbh; b. 大对象操作示例 $stmt = $dbh->prepare("insert into TESTBLOB (id, bb, cb) " . "VALUES (?, ?, ?)"); $id=1; $fp = fopen("./testblob.png", "rb") or die("Unable to open file!"); $fp2 = "clob test,aaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbb cccccccccccccccccdddddddddddddddd"; $stmt->bindParam(1, $id); $stmt->bindParam(2, $fp, PDO::PARAM_LOB); $stmt->bindParam(3, $fp2, PDO::PARAM_STR,strlen($fp2)); $dbh->beginTransaction(); $stmt->execute(); $dbh->commit(); fclose($fp); 8 第5章 PDO 示例 $stmt = $dbh->prepare("select bb, cb from TESTBLOB where id=1"); $stmt->execute(); $stmt->bindColumn(1, $bb, PDO::PARAM_LOB); $stmt->bindColumn(2, $cb, PDO::PARAM_LOB); $stmt->fetch(PDO::FETCH_BOUND); $wblobfp = fopen("blob_out.jpg", "wb+"); stream_copy_to_stream($bb, $wblobfp); $wclobfp = fopen("./testclob_out.log", "w+"); fwrite($wclobfp, $cb); 9 版权声明 版权声明 北京人大金仓信息技术股份有限公司（简称：人大金仓）版权所有，并保留对本手册及本声明的一切权利。 未得到人大金仓的书面许可，任何人不得以任何方式或形式对本手册内的任何部分进行复制、摘录、备份、修 改、传播、翻译成其他语言、将其全部或部分用于商业用途。 免责声明 本手册内容依据现有信息制作，由于产品版本升级或其他原因，其内容有可能变更。人大金仓保留在没有任何通 知或者提示的情况下对手册内容进行修改的权利。 本手册仅作为使用指导，人大金仓在编写本手册时已尽力保证其内容准确可靠，但并不确保手册内容完全没有错 误或遗漏，本手册中的所有信息也不构成任何明示或暗示的担保。 技术支持 • 人大金仓官方网站：http://www.kingbase.com.cn/ • 人大金仓文档中心：http://help.kingbase.com.cn/ • 全国服务热线：400-601-1188 • 人大金仓技术支持与反馈信箱：support@kingbase.com.cn 10 服务周期承诺 服务周期承诺 由于市场需求在不断变化，技术创新和发展的进程不断加剧，产品的版本更迭不可避免。人大金仓对于产品版本 生命周期的有效管理，有助于您提前规划项目，更好地从产品服务终止上过渡。 表 1: KingbaseES 产品生命周期里程碑 关键里程碑点 定义 产品发布日期 产品正式发布版本，即 GA（general availability）版本的发布日期。 停止销售日期 正式停止销售的日期，版本停止接受订单日。该日之后，产品将不再销售。 停止功能升级日期 在该日期之后，不再提供新特性和新硬件支持。但依旧提供错误修复、安全修复、功 能维护等服务。 停止功能维护日期 在该日期之后，不再维护功能，修复问题。但依旧提供安全修复等服务 停止安全维护日期 在该日期之后，不再发布补丁版本修复中高风险漏洞，仅提供有限的支持。 产品服务终止日期 停止提供产品服务和支持的日期。包括软件维护版本，缺陷修复，以及针对该产品的 所有服务支持（包括服务热线和远程/现场支持）。 服务周期策略 金仓数据库管理系统 KingbaseES 产品确保以下的服务周期： 1）产品自发布之日起至产品停止功能升级（包含新特性、新硬件支持）之日不少于 5 年。 2）产品停止功能升级之日起至产品停止功能维护（主要包括问题修复）之日不少于 4 年。 3）产品功能维护停止之日起至产品停止安全维护（包括中高风险漏洞修复）之日不少于 2 年。 服务终止策略 金仓数据库管理系统 KingbaseES 产品确保在销售后，至少提供 6 年的服务支持。 注意: 人大金仓将会综合各方因素来确定产品服务终止日期。并将在实际产品服务终止日期之前至少 90 天，通过公 11 服务周期承诺 开方式宣布产品服务终止日期。 12