使用Python 驱动 Ksycopg2 连接和使用 金仓数据库Kingbase

本文介绍如何通过 Python 驱动 Ksycopg2 连接和使用 Kingbase 数据库。

不同版本的 Python 环境需要使用不同版本的驱动。

前提条件​

• 确保已设置基本的应用开发环境。

• 确保已安装与驱动对应版本的数据库，且数据库连接可用。

• 确保 Ksycopg2 支持开发环境：

  • 系统架构：

    Linux：x86_64、arm、loongarch、mips、sw

    Windows：提供64位支持

  • 编译器：

    Linux：仅支持依赖 glibc 的编译的 Python。

    Windows：依赖 msvc120 的运行时库。

  • Python 环境：

    Python版本	支持平台
    Python2.7	Linux： 提供支持x86_64、arm、loongarch、mips、sw的驱动 Windows：提供64位支持
    Python3.5
    Python3.6	Linux： 提供支持x86_64、arm、loongarch、mips的驱动 Windows：提供64位支持
    Python3.7
    Python3.8
    Python3.9
    Python3.10

    备注

    Ksycopg2 驱动需要和 Python 大版本一致，如 Python3.5 的 Ksycopg2 驱动支持 Python3.5.x 的任意小版本。

    Ksycopg2 驱动区分系统架构，如 x86 架构只能使用驱动包名为 x86 的 Ksycopg2 驱动，否则无法加载。

    其中，Python2.7 和 Python3.5 的 Ksycopg2 驱动包默认提供， Python2.7 版本默认提供 UCS2 版本。

    其余版本按需提供，x86 和 Windows 64 位平台，可通过 pip install ksycopg2 尝试下载对应平台驱动。

满足以上条件后，可通过金仓官网下载页面（电科金仓-成为世界卓越的数据库产品与服务提供商）获取对应版本架构的 Ksycopg2 驱动。

操作实例​

基于 Ksycopg2 编译开发应用程序，主要步骤如下：

安装部署 Python 驱动 -> 测试能否成功加载 Ksycopg2 驱动 -> 编写应用程序 -> 运行

下文将通过具体示例说明如何使用 Python 驱动连接操作数据库：

安装部署驱动​

查看当前环境架构及 Python 版本，选用合适的 Python 驱动 Ksycopg2。

命令行执行 python -V，执行查看 Python 版本：

$ python -V
Python 3.5.6

当前环境使用的是 Python3.5，若对应架构是 x86_64，则应该选用 x86 架构的 Python3.5 版本的 Ksycopg2 驱动包安装。

注意

Python 驱动 Ksycopg2 基于在不同系统架构不同 Python 版本间不通用，如当前开发环境为 Linux x86_64，需要使用 Python3.5.6 操作连接数据库，则用户需要安装 Linux x86_64 架构对应的 Python3.5 驱动包，否则会出现 Python 无法识别对应模块的报错。

Linux 环境的 Python 基本是 64 位的，Windows 环境的 Python 有 32 位和 64 位两种安装包，当前默认提供的 Python 驱动包都是 64 位，可以通过在 Python 命令行执行以下代码查看 Python 操作位数：

>>> import platform
>>> print(platform.architecture())
('64bit', 'ELF')

另外，Python2 是有 UCS2 和 UCS4 两个 Python 版本的，这是由于对 UNICODE 的不同编码方案导致的，主要区别在于它们可以表示的字符范围，在 Python3.3 及以上版本没有这个区分了。

故用户使用 Linux 自行编译安装 Python2.7 并使用对应 Python2.7 的 Ksycopg2 驱动包时，需要注意 UCS 版本区分，可通过在 Python 命令行执行以下代码查看 Python 是 UCS 哪个版本：

>>> import sys
>>> print sys.maxunicode
# 65535 -> ucs2, 1114111 -> ucs4
65535

将对应架构及 Python 版本的 Ksycopg2 驱动包解压，Linux 环境 Python3.5 驱动解压后的目录结构如下：

ksycopg2
├── compat.py
├── errorcodes.py
├── errors.py
├── extensions.py
├── extras.py
├── init.py
├── _ipaddress.py
├── _json.py
├── _ksycopg.cpython-35m-x86_64-linux-gnu.so
├── libcrypto.so.1.1
├── libkci.so.5
├── libssl.so.1.1
├── _lru_cache.py
├── pool.py
├── _range.py
├── sql.py
└── tz.py

其中，_ksycopg 开头的这个库就是 Python 驱动，后缀为 .py 的文件是 Ksycopg2 驱动提供的可拓展的 Python 文件，包括了一些游标工厂、批量执行、连接池等功能。

将 ksycopg2 这个文件夹拷贝到对应 Python 安装目录下的 site-packages 路径下(site-packages 路径是 Python 默认加载模块的搜索路径)，以下是模块路径示例：

安装到指定路径后，Python 命令行执行 import ksycopg2 ，查看是否有报错提示。

在确认驱动包使用无误的前提，若导入模块仍然报错，错误提示如下：

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/python/py-3.5/lib/python3.5/site-packages/ksycopg2/__init__.py", line 51, in <module>
    from ksycopg2._ksycopg import (                     # noqa
ImportError: libkci.so.5: cannot open shared object file: No such file or directory

这是由于 Ksycopg2 驱动以动态库的形式提供，Ksycopg2 会依赖 Libkci 库，而 Python 加载 Ksycopg2 时，只识别到 Ksycopg2，并未识别到 Ksycopg2 驱动的依赖库导致的错误提示。

可通过在当前命令行环境配置环境变量 LD_LIBRARY_PATH 配置 Linux 系统默认库搜索路径解决(Ksycopg2 驱动包内会提供依赖库，若无依赖库，也可配置任意依赖库路径)：

# Ksycopg2 驱动包内一般会提供依赖库
export LD_LIBRARY_PATH=/home/python/py-3.5/lib/python3.5/site-packages/ksycopg2:$LD_LIBRARY_PATH

而 Windows 环境一般会默认识别 site-packages/ksycopg2 是否存在对应依赖库，不需要额外配置环境变量，但是要求 Windows 环境有对应 MSVC120(VS2013) 运行时库，否则无法加载对应驱动。

若无报错，表示 Ksycopg2 驱动成功导入，可正常使用，继续下面步骤创建测试用例。

备注

当前已发布 x86_64 和 Windows 两个版本的 Ksycopg2 驱动，用户可通过 pip install ksycopg2 尝试下载当前环境是否有支持的 Ksycopg2 驱动包。

开发源程序​

1. 创建文件夹用于存放测试示例

   创建测试程序文件夹 test_ksycopg2，新建源码文件 test_ksycopg2.py，目录示例如下：

   test_ksycopg2
   └── test_ksycopg2.py

2. 开发源程序 test_ksycopg2.py，以下是一个具体的示例：

   导入Ksycopg2：

   import ksycopg2
   

   使用 ksycopg2.connect() 创建连接，并连接到数据库：

   conn = ksycopg2.connect("dbname=dbname user=user password=pwd host=host port=port")
   例：
   conn = ksycopg2.connect("dbname=test user=system password=123456 host=127.0.0.1 port=54321")
   

   备注

   Ksycopg2 提供了键值对形式和 URI 形式的连接串形式连接数据库，URI 形式的连接串是 Libkci 支持的形式，通常使用键值对的连接方式，具体说明请参考 Ksycopg2 手册连接说明。

   支持的连接拓展参数完全依赖 Libkci，Ksycopg2 不会对参数进行识别辨认，故 Libkci 支持的连接参数，Ksycopg2 驱动也支持，更多连接参数说明请参考 Libkci 手册的连接参数说明。

   创建连接后，使用刚刚创建的连接新建一个 Cursor 对象，用于操作数据库：

   cur = conn.cursor()
   

   使用 cur.execute() 执行 SQL 语句：

   # 创建新表
   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, '！@#￥%……'))
   

   备注

   Ksycopg2 遵循 DB API 2.0 标准，完整实现了标准对应的基本 Python 接口，对应的标准接口用法也是一致的，如 cursor.execute() 就是 DB API 2.0 的一个标准接口。

   插入成功后，使用 cur.execute() 执行查询，接着使用 cur.fetchall() 获取结果集并打印：

   # 执行查询，并获取结果集
   cur.execute("select * from test_ksy")
   rows = cur.fetchall()
   
   # 打印结果集
   print("result for query:")
   for row in rows:
       print("\t", row)
   

   备注

   Ksycopg2 默认获取的结果集是以列表嵌套元组的形式存放结果集的，比如上述示例中的 rows 类型为列表，rows[0] 类型为元组，即查询的结果是一个列表， 列表每一项为元组。

   Ksycopg2 还提供了其他形式的游标类型，比如返回字典形式的结果集，可通过扩展模块 extras.py 中的 ksycopg2.extras.Dictcursor 游标类型，这样每一行返回的结果就是一个字典，其中建是列名，值是该列的实际值。

   查询结束后，需要关闭游标及连接。

   以下是完整示例，示例使用 Python3 语法：

   # -*- coding: utf-8 -*-
   import ksycopg2
   
   database = "TEST"
   user = "SYSTEM"
   password = "123456"
   host = "127.0.0.1"
   port = "54321"
   
   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, '！@#￥%……'))
   
       cur.execute("select * from test_ksy")
       rows = cur.fetchall()
   
       print(type(rows), type(rows[0]))
       print("result for query:")
       for row in rows:
           print("\t", row)
   
       cur.close()
       conn.close()
   except Exception as e:
       print(e)
       exit()
   

运行程序​

编写好测试相关代码后，使用 Python 执行即可：

python test_ksycopg2.py

示例期望输出如下所示：

<class 'list'> <class 'tuple'>
result for query:
         (1, 'John')
         (2, '中文测试文字')
         (3, '！@#￥%……')

常见问题​

1. 驱动包 SSL 库与系统环境的 SSL 库冲突

   原因：系统环境的依赖库版本过高，或应用程序运行时错误加载了系统环境的SSL库。

   解决：通过 ldd _ksycopg 开头的驱动 ， 查看当前环境下的依赖关系，确保运行应用程序时加载驱动包提供的 SSL 库，若仍然有 SSL 相关报错，则确定是驱动包提供的 SSL 库无法在当前环境下使用，此时请联系技服获取 Ksycopg2静态依赖 SSL 库的驱动包来解决 SSL 依赖冲突问题。

2. Ksycopg2 加载失败，报错 No module named 'ksycopg2._ksycopg'

   原因：使用与当前环境架构不符或 Python 版本不一致的驱动包，也有可能是驱动包安装路径不对，Python 无法识别。

   解决：先确保使用对应架构及对应 Python 版本的驱动包，若确认驱动包无误，则可能是 Python 未成功识别到对应 Ksycopg2 模块，可通过在 Python 强制设置模块搜索路径解决：

   >>> import sys
   >>> sys.path.insert(0, "Ksycopg2 驱动包的父目录")