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

KingbaseES 客户端编程接口指南-Python 金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024） 发布日期：2023 年 10 月 12 日 北京人大金仓信息技术股份有限公司 目 目 录 录 第 1 章 前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.4 手册约定 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 概述 3 2.1 python 数据库驱动说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 KingbaseES 兼容版本信息 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.3 ksycopg2 连接 KingbaseES 数据库配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.4 检查安装情况 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 第 3 章 数据库管理连接 6 3.1 连接数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2 关闭连接 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.3 数据类型映射 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.4 多主机连接负载均衡 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 第 4 章 执行 SQL 语句 9 4.1 查询和结果集处理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.2 执行非查询 SQL 语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.3 参数传递 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 5 章 程序示例 11 5.1 连接数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.2 获取结果集 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.3 存储过程 13 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 版权声明 14 服务周期承诺 15 I 第 1 章 前言 1 第 章 前言 本文档介绍了使用 Python 语言连接 KingbaseES 数据库的 ksycopg2 驱动，描述了该驱动如何安装配置以及语法 格式。 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 KingbaseES Python 指南面向所有使用 KingbaseES 数据库的用户，主要是数据库管理员和应用程序开发人员。 1.2 相关文档 有关 Python 的数据库适配器的更多信息，请参阅以下资源： Psycopg 2.9.3 documentation 1.3 术语 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 1 第 1 章 前言 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 2 第 2 章 概述 2 第 章 概述 • python 数据库驱动说明 • KingbaseES 兼容版本信息 • ksycopg2 连接 KingbaseES 数据库配置 • 检查安装情况 2.1 python 数据库驱动说明 ksycopg2 是 Python 编程语言的 KingbaseES 数据库适配器。它的主要特点是 Python DB API 2.0 规范的完整实 现和线程安全。 ksycopg2 主要在 C 程序中作为 libpq 包装器实现，因此既高效又安全。它拥有客户端和服务端游标，支持异步 通信和通知、复制。 Python DBAPI 2.0 的官方文档可以访问 https://www.python.org/dev/peps/pep-0249 。 2.2 KingbaseES 兼容版本信息 目前提供的 ksycopg2 支持情况如下表所示： 表 2.2.1: ksycopg2 支持情况 Python 版本 系统架构 说明 Python2.7 Linux amd64 仅提供 64 位支持 Linux aarch64 仅提供 64 位支持 Linux mips64le 仅提供 64 位支持 见续表 3 第 2 章 概述 表 2.2.1 – 续表 Python 版本 Python3.5 系统架构 说明 Windows 提供 32 和 64 位支持，32 位需要 VC9 运行时，64 位需要 VC12 运行时 Linux amd64 仅提供 64 位支持 Linux aarch64 仅提供 64 位支持 Linux mips64le 尚不支持该版本 Windows 提供 32 和 64 位支持，都需要 VC12 运行时 Windows 中如果没有安装对应的 Python 版本时，在导入 ksycopg2 模块时会有以下报错： ImportError: DLL load failed: 找不到指定的模块。 2.3 ksycopg2 连接 KingbaseES 数据库配置 首先，需要安装 Python，且配置 kingbase 数据库。 将对应 Python 版本的 ksycopg2 驱动解压后，把 ksycopg2 文件夹放在 Python 的模块路径中，如“D: \Python27\Lib\site-packages”或“/usr/lib/python35/dist-packages”。 如果不确定 Python 模块路径，可以在命令行中执行以下语句： import sys sys.path 即可查看 Python 搜索模块的路径，如图所示，从中选一个路径放入其中即可。 将 libpq 库文件路径添加到 $LD_LIBRARY_PATH 环境变量中 (环境变量中已存在该路径可省略该步骤)，命令 行中执行： export LD_LIBRARY_PATH=/home/kingbase/lib:$LD_LIBRARY_PATH 4 第 2 章 概述 2.4 检查安装情况 打开 Python 命令行，执行以下语句即可检查是否安装成功，如图所示： 5 第 3 章 数据库管理连接 3 第 章 数据库管理连接 • 连接数据库 • 关闭连接 • 数据类型映射 • 多主机连接负载均衡 3.1 连接数据库 我们可以使用以下语句连接到数据库： conn = ksycopg2.connect("dbname=TEST user=SYSTEM password=123456 host=127.0.0.1 port=54321") conn = ksycopg2.connect(database='TEST', user='SYSTEM', password='123456', host='54321', port='54321') 连接参数说明可参考表 3.1.1 。 表 3.1.1: 连接参数说明 参数名 说明 备注 host 数据库服务器的地址，包括域名、主机名、 默认为 localhost 主机的 IP 地址等，也可以是 UNIX socket port 端口号 user 登录的用户名 password 用户名的密码 dbname 连接至的数据库名 见续表 6 第 3 章 数据库管理连接 表 3.1.1 – 续表 参数名 说明 备注 sslmode 是否使用 SSL 默认为 prefer 可选参数为 disable, allow, prefer, require, verify-ca, verify-full connect_timeout 连接的最长等待时间，单位为秒 0 值或未指定均为无限等待，最小值为 2 关闭连接 3.2 要关闭与数据库的连接，只需要对数据库对象 conn 调用 close 方法。 conn.close() 数据类型映射 3.3 当 Python 应用和 Kingbase 服务器交换信息时，需要在 Kingbase 数据类型和标准 Python 类型之间进行转换。 类型映射说明可参考下表。 表 3.3.1: 类型映射说明 Kingbase 数据类 Python 类型 说明 型 NULL None smallint, integer, int 或 long long 类型仅存在于 Python2 中，int 型数据溢出后会自 动转换为 long 类型 bigint real, double numeric, float deci- Decimal mal bool char, bool varchar, str 或 unicode 型。 text, clob date Python2 上使用 unicode 类型，Python3 上使用 str 类 date Kingbase 中可以存储几乎无限的日期、时间和间隔类 型，而 Python 中有最大值限制，如 date 类型最大值 见续表 为 9999-12-31,time 类型最大值为 23:59:59.999999 7 第 3 章 数据库管理连接 表 3.3.1 – 续表 Kingbase 数据类 Python 类型 说明 型 time, timetz time timestamp, datetime timestamptz interval timedelta bytea, blob buffer 或 memoryview, bytearray, buffer 类型仅在 Python2 中使用，接收时 Python2 会转 bytes 换为 buffer 类型，Python3 则转换为 memoryview 类型 ARRAY 3.4 list 多主机连接负载均衡 多主机连接负载均衡，主要用于数据库集群环境，在负载均衡模式及配置了多个主机地址的情况下，实现对多个 数据库实例的均衡连接负载。 在连接参数中增加’loadbalance’ , 通过该参数来控制是否使用数据库连接负载均衡机制。默认值为 off，表示关 闭；值为 on，表示打开。 连接示例如下所示： # 配置多主机地址, 逗号分隔 hosts = "10.10.11.153,10.10.11.151,10.10.11.152" # 配置多主机端口（逗号分隔，相同则只需配置一个） ports = "54321" # 连接参数 conn = ksycopg2.connect("dbname={} user={} password={} host={} port={} loadbalance=on connect_timeout=6". format(database, user, password, hosts, ports)) 8 第 4 章 执行 SQL 语句 4 第 章 执行 SQL 语句 • 查询和结果集处理 • 执行非查询 SQL 语句 • 参数传递 4.1 查询和结果集处理 使用 cursor 函数来获取游标对象，然后调用 execute 函数来发送查询语句。 fetchall 函数可以获取全部结果集，也可以使用 fetchone 函数获取单行结果，若为空，将返回空列表。 cur = conn.cursor() cur.execute("select id from test") rows = cur.fetchall() for row in rows: print(row) cur.close() 4.2 执行非查询 SQL 语句 获取游标对象后，直接执行 execute 函数即可。 cur = conn.cursor() cur.execute('create table test(id integer, name TEXT)') cur.exeute("INSERT INTO TEST(id, name) VALUES(1, 'John')") cur.close() 9 第 4 章 执行 SQL 语句 4.3 参数传递 ksycopg2 实际上并没有 prepare 和 bind 功能，而是使用了参数传递将 Python 类型转换为 SQL 类型来防止 SQL 注入。 占位符使用% 标记，使用%s 表示按位置占位符，%(name)s 表示命名占位符。 cur.exeute("INSERT INTO TEST(id, name) VALUES(%s, %s)", (2, "position placeholder")) cur.exeute("INSERT INTO TEST(id, name) VALUES(%(id)s, %(val)s)", {'val': 'name placeholder', 'id': 3}) 10 第5章 程序示例 5 第 章 程序示例 • 连接数据库 • 获取结果集 • 存储过程 您可前往 人大金仓官网 下载 Python 测试用例 。 连接数据库 5.1 import ksycopg2 database = "TEST" user = "SYSTEM" password = "123456" host = "127.0.0.1" port = "54321" if __name__ == "__main__": try: conn = ksycopg2.connect("dbname={} user={} password={} host={} port={}" .format(database, user, password, host, port)) except Exception, e: print(e) print("Fail") else: print("Success") 11 第5章 程序示例 获取结果集 5.2 import ksycopg2 database = "TEST" user = "SYSTEM" password = "123456" host = "127.0.0.1" port = "54321" if __name__ == "__main__": try: conn = ksycopg2.connect("dbname={} user={} password={} host={} port={}" .format(database, user, password, host, port)) cur = conn.cursor() cur.execute('drop table if exists test_ksy') cur.execute('create table test_ksy(id integer, name TEXT)') cur.execute("insert into test_ksy values(%s, %s)", (1, "John")) cur.execute("insert into test_ksy values(%s, %s)", (2, '中文测试文字')) cur.execute("insert into test_ksy values(%s, %s)", (3, '！@#￥%……')) conn.commit() cur.execute("select * from test_ksy") rows = cur.fetchall() for row in rows: print(cell) cur.close() conn.commit() conn.close() except Exception, e: print(e) print("Fail") else: print("Success") 12 第5章 5.3 程序示例 存储过程 CREATE FUNCTION reffunc(refcursor) RETURNS refcursor AS $$ BEGIN OPEN $1 FOR SELECT col FROM test; RETURN $1; END; $$ LANGUAGE plsql； curl = conn.cursor() curl.callproc('reffunc', ['curname']) cur2 = conn.cursor('curname') for record in cur2: print(record) pass 13 版权声明 版权声明 北京人大金仓信息技术股份有限公司（简称：人大金仓）版权所有，并保留对本手册及本声明的一切权利。 未得到人大金仓的书面许可，任何人不得以任何方式或形式对本手册内的任何部分进行复制、摘录、备份、修 改、传播、翻译成其他语言、将其全部或部分用于商业用途。 免责声明 本手册内容依据现有信息制作，由于产品版本升级或其他原因，其内容有可能变更。人大金仓保留在没有任何通 知或者提示的情况下对手册内容进行修改的权利。 本手册仅作为使用指导，人大金仓在编写本手册时已尽力保证其内容准确可靠，但并不确保手册内容完全没有错 误或遗漏，本手册中的所有信息也不构成任何明示或暗示的担保。 技术支持 • 人大金仓官方网站：http://www.kingbase.com.cn/ • 人大金仓文档中心：http://help.kingbase.com.cn/ • 全国服务热线：400-601-1188 • 人大金仓技术支持与反馈信箱：support@kingbase.com.cn 14 服务周期承诺 服务周期承诺 由于市场需求在不断变化，技术创新和发展的进程不断加剧，产品的版本更迭不可避免。人大金仓对于产品版本 生命周期的有效管理，有助于您提前规划项目，更好地从产品服务终止上过渡。 表 1: KingbaseES 产品生命周期里程碑 关键里程碑点 定义 产品发布日期 产品正式发布版本，即 GA（general availability）版本的发布日期。 停止销售日期 正式停止销售的日期，版本停止接受订单日。该日之后，产品将不再销售。 停止功能升级日期 在该日期之后，不再提供新特性和新硬件支持。但依旧提供错误修复、安全修复、功 能维护等服务。 停止功能维护日期 在该日期之后，不再维护功能，修复问题。但依旧提供安全修复等服务 停止安全维护日期 在该日期之后，不再发布补丁版本修复中高风险漏洞，仅提供有限的支持。 产品服务终止日期 停止提供产品服务和支持的日期。包括软件维护版本，缺陷修复，以及针对该产品的 所有服务支持（包括服务热线和远程/现场支持）。 服务周期策略 金仓数据库管理系统 KingbaseES 产品确保以下的服务周期： 1）产品自发布之日起至产品停止功能升级（包含新特性、新硬件支持）之日不少于 5 年。 2）产品停止功能升级之日起至产品停止功能维护（主要包括问题修复）之日不少于 4 年。 3）产品功能维护停止之日起至产品停止安全维护（包括中高风险漏洞修复）之日不少于 2 年。 服务终止策略 金仓数据库管理系统 KingbaseES 产品确保在销售后，至少提供 6 年的服务支持。 注意: 人大金仓将会综合各方因素来确定产品服务终止日期。并将在实际产品服务终止日期之前至少 90 天，通过公 15 服务周期承诺 开方式宣布产品服务终止日期。 16