Python连接管理金仓数据库的完全指南：从安装到高可用配置

更新时间：2026-10-10 09:59:45　来源：本站整理　浏览：0

开篇：为什么需要这篇指南

去年做一个数据分析平台，后端用Python开发，需要连接金仓数据库进行数据清洗和统计。最初使用普通数据库驱动，遇到不少问题：代码中遍布try-catch-finally，可读性差；并发量上升时连接频繁超时；数据库主备切换时应用直接宕机。后来改用ksycopg2驱动，这些问题基本得到解决。本文分上下两篇，上篇重点讲解连接管理、高可用配置和数据类型映射，下篇将介绍SQL执行、批量操作和扩展功能。

一、ksycopg2 是什么

ksycopg2是金仓数据库的Python驱动，使用C语言编写，性能表现良好，完整实现了Python DB API 2.0规范，是Python连接金仓数据库的标准方式。该驱动依赖libkci库，而libkci又依赖OpenSSL，因此安装时若提示缺少库文件，多半是这两个依赖未正确配置。

二、安装配置

2.1 版本选择

ksycopg2的版本号需要与Python版本匹配。例如，包名为ksycopg2‑python2.7的驱动仅适用于Python 2.7。官方支持情况如下：

Python 2.7：支持Linux（x86_64、arm、loongarch、mips、sw64位）和Windows
Python 3.5-3.13：支持Linux（x86_64、arm、loongarch、mips64位）和Windows

笔者使用Python 3.9，对应驱动运行稳定。

2.2 安装步骤

最简单的安装方式是使用pip，但需先确认pip对应的Python版本。

# 查看 pip 对应的 Python 版本
pip --version
# 安装 ksycopg2
pip install ksycopg2

若pip安装失败或需离线安装，可前往金仓官网下载对应版本的驱动包，解压后将ksycopg2文件夹放入Python的site-packages目录。查找该目录的方法：

import sys
sys.path

输出列表中包含site-packages的路径即为目标目录。

2.3 依赖库配置

ksycopg2依赖libkci.so（Linux）或libkci.dll（Windows）。驱动安装成功但导入报错，通常是因为系统找不到这些库。常见错误信息：

ImportError: libkci.so: cannot open shared object file: No such file or directory

解决办法：将libkci所在目录加入LD_LIBRARY_PATH环境变量。

export LD_LIBRARY_PATH=/home/kingbase/lib:$LD_LIBRARY_PATH

Windows平台则将libkci.dll放入Python安装目录或系统PATH。另一个常见问题：Windows下导入ksycopg2报DLL load failed，多半是缺少MSVC运行库，安装Visual C++ Redistributable即可解决。

2.4 验证安装

import ksycopg2
print(ksycopg2.__version__)

若无报错且输出版本号，说明安装成功。

三、连接数据库

3.1 三种连接方式

方式一：键值对字符串

import ksycopg2
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='127.0.0.1',
    port='54321',
    client_encoding='UTF8'
)

方式三：URI格式

conn = ksycopg2.connect(
    "kingbase://SYSTEM:123456@127.0.0.1:54321/TEST"
)

也支持postgresql前缀：

conn = ksycopg2.connect(
    "postgresql://SYSTEM:123456@127.0.0.1:54321/TEST"
)

支持postgresql前缀主要是历史原因，实际连接的仍是金仓数据库。

3.2 连接参数说明

host：服务器地址，默认localhost
port：端口，默认54321
user：用户名，默认当前系统用户
password：密码，无默认值
dbname：数据库名，默认同用户名
connect_timeout：连接超时秒数，默认无限等待
client_encoding：客户端编码，默认数据库编码
sslmode：SSL模式，默认prefer

建议设置connect_timeout，避免网络异常时无限等待。

3.3 关闭连接

连接使用完毕后务必关闭，否则会占用数据库连接数：

conn.close()

也可使用with语句自动管理资源：

with ksycopg2.connect(database='TEST', user='SYSTEM') as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT 1")
        print(cur.fetchone())
# 退出 with 块时自动提交事务，但连接不会自动关闭，仍需手动 conn.close()

四、高可用配置（重点）

这是ksycopg2的实用功能之一。若金仓数据库采用集群部署（主备模式），合理配置高可用参数，主备切换时应用可自动重连。

4.1 多主机配置

hosts = "192.168.1.100,192.168.1.101"
ports = "54321"
conn = ksycopg2.connect(
    f"dbname=TEST user=SYSTEM password=123456 host={hosts} port={ports}"
)

驱动会按顺序尝试连接，第一个失败自动切换至第二个。

4.2 连接重试

集群主备切换期间数据库服务短暂不可用，配置重试参数可避免应用直接报错：

conn = ksycopg2.connect(
    f"dbname=TEST user=SYSTEM password=123456 host={hosts} port={ports} "
    "connect_timeout=3 retries=5 delay=3"
)

retries=5：最多重试5次
delay=3：每次重试间隔3秒
connect_timeout=3：每次连接尝试最长等待3秒

主备切换通常10-15秒完成，5次重试足够应对。

4.3 自动找主

集群环境中仅主节点支持读写，可配置target_session_attrs=read-write让驱动自动连接主节点：

conn = ksycopg2.connect(
    f"dbname=TEST user=SYSTEM password=123456 host={hosts} port={ports} "
    "connect_timeout=3 target_session_attrs=read-write"
)

驱动会逐个尝试主机，直到找到支持读写的节点。该配置在读写分离场景下尤为实用。

4.4 快速故障转移

conn = ksycopg2.connect(
    f"dbname=TEST user=SYSTEM password=123456 host={hosts} port={ports} "
    "fastswitch=on retries=3 delay=5"
)

开启fastswitch=on后，驱动会记住故障主机，后续连接自动跳过，无需每次等待超时。参数对比：

retries/delay：连接失败时重试，适用于主备切换、网络抖动
target_session_attrs：只连主节点，适用于读写分离、写操作
fastswitch：跳过故障主机，适用于短连接、高并发

4.5 连接负载均衡

若后端有多个备节点，可开启负载均衡分散连接压力：

conn = ksycopg2.connect(
    f"dbname=TEST user=SYSTEM password=123456 host={hosts} port={ports} "
    "loadbalance=on connect_timeout=6"
)

loadbalance=on开启后，驱动会在多个主机间轮询分配连接，适合读多写少、多备节点的场景。

五、连接池

5.1 SimpleConnectionPool（单线程）

单线程场景（如定时任务脚本）可使用SimpleConnectionPool：

import ksycopg2
from ksycopg2 import pool
connection_pool = ksycopg2.pool.SimpleConnectionPool(
    minconn=1,
    maxconn=10,
    database='TEST',
    user='SYSTEM',
    password='123456',
    host='127.0.0.1',
    port='54321'
)
conn = connection_pool.getconn()
cur = conn.cursor()
cur.execute("SELECT * FROM test_user")
rows = cur.fetchall()
cur.close()
connection_pool.putconn(conn)
connection_pool.closeall()

5.2 ThreadedConnectionPool（多线程）

多线程Web应用（如Flask、Django部署）建议使用ThreadedConnectionPool：

connection_pool = ksycopg2.pool.ThreadedConnectionPool(
    minconn=5,
    maxconn=20,
    database='TEST',
    user='SYSTEM',
    password='123456',
    host='127.0.0.1',
    port='54321'
)

使用方法与SimpleConnectionPool相同。注意：putconn()仅将连接放回池中，不会关闭连接。多线程环境下，多个线程同时获取同一连接可能引发问题，需在应用层加锁控制。切勿对getconn()获取的连接直接调用close()，否则连接池数量减少，最终报connection pool exhausted错误。连接池满时getconn()会直接报错，可调大maxconn或排查业务代码是否及时putconn()。

5.3 完整的多线程示例

import threading
import ksycopg2
from ksycopg2 import pool
connection_pool = ksycopg2.pool.ThreadedConnectionPool(
    1, 5, database='TEST', user='SYSTEM',
    password='123456', host='127.0.0.1', port='54321'
)
def worker(n):
    conn = connection_pool.getconn()
    cur = conn.cursor()
    cur.execute("INSERT INTO test_user VALUES (%s, %s)", (n, f"user_{n}"))
    conn.commit()
    cur.close()
    connection_pool.putconn(conn)
threads = []
for i in range(10):
    t = threading.Thread(target=worker, args=(i,))
    threads.append(t)
    t.start()
for t in threads:
    t.join()
connection_pool.closeall()

六、自动提交模式

ksycopg2默认手动提交模式，执行INSERT、UPDATE后必须调用commit()，否则数据不会真正写入。

conn = ksycopg2.connect(database='TEST', user='SYSTEM')
conn.autocommit = False   # 默认值
cur = conn.cursor()
cur.execute("INSERT INTO test_user VALUES (1, 'test')")
conn.commit()  # 必须调用

若需自动提交，可设置：

conn.autocommit = True

开启后每条语句执行完立即提交，适合原型开发，生产环境不建议使用，以免事务控制混乱。

七、数据类型映射

Python类型与金仓数据库类型的对应关系：

NULL：None
smallint, integer, bigint：int
real, double：float
numeric, decimal：Decimal
bool：bool
char, varchar, text, clob：str
date：datetime.date
timestamp, timestamptz：datetime.datetime
interval：timedelta
bytea, blob：memoryview / bytes
ARRAY：list

注意事项：Python 2中字符串为str和unicode，Python 3统一为str。金仓的date类型最大到9999-12-31，与Python的datetime一致。bytea类型在Python 3中返回memoryview，需用tobytes()转换获取原始字节。

cur.execute("SELECT bytea_column FROM test_lob")
row = cur.fetchone()
if isinstance(row[0], memoryview):
    data = row[0].tobytes().decode('utf-8')

八、编码设置

连接时可指定客户端编码，避免中文乱码：

conn = ksycopg2.connect(
    database='TEST',
    user='SYSTEM',
    password='123456',
    client_encoding='UTF8'
)

也可在连接后动态设置：

conn.set_client_encoding('UTF8')

若不指定，默认使用数据库编码，建议统一使用UTF8。

九、小结

上篇主要讲解ksycopg2的安装配置、连接管理、高可用和连接池。要点总结：

ksycopg2是Python连接金仓数据库的标准方式，支持Python 2.7到3.13
安装时注意依赖库libkci的路径配置
高可用参数（多主机、重试、自动找主、快速故障转移）配置得当，集群切换对应用影响小
连接池使用ThreadedConnectionPool，连接用完需putconn，不要close

原文链接：本站整理

本文来自互联网用户投稿，该文章观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。

如若内容造成侵权/违法违规/事实不符，请将相关资料发送至 service@2cto.cc 进行投诉反馈，一经查实，立即处理！

您可能感兴趣的文章:

上一篇：没有了
下一篇：Python执行多行cmd命令：单&与双&&的区别详解

软件下载

源码下载

软件编程

网络编程

数据库

CMS

常用工具

Python连接管理金仓数据库的完全指南：从安装到高可用配置

开篇：为什么需要这篇指南

一、ksycopg2 是什么

二、安装配置

2.1 版本选择

2.2 安装步骤

2.3 依赖库配置

2.4 验证安装

三、连接数据库

3.1 三种连接方式

3.2 连接参数说明

3.3 关闭连接

四、高可用配置（重点）

4.1 多主机配置

4.2 连接重试

4.3 自动找主

4.4 快速故障转移

4.5 连接负载均衡

五、连接池

5.1 SimpleConnectionPool（单线程）

5.2 ThreadedConnectionPool（多线程）

5.3 完整的多线程示例

六、自动提交模式

七、数据类型映射

八、编码设置

九、小结

您可能感兴趣的文章:

软件下载

源码下载

软件编程

网络编程

数据库

CMS

常用工具

Python连接管理金仓数据库的完全指南：从安装到高可用配置

开篇：为什么需要这篇指南

一、ksycopg2 是什么

二、安装配置

2.1 版本选择

2.2 安装步骤

2.3 依赖库配置

2.4 验证安装

三、连接数据库

3.1 三种连接方式

3.2 连接参数说明

3.3 关闭连接

四、高可用配置（重点）

4.1 多主机配置

4.2 连接重试

4.3 自动找主

4.4 快速故障转移

4.5 连接负载均衡

五、连接池

5.1 SimpleConnectionPool（单线程）

5.2 ThreadedConnectionPool（多线程）

5.3 完整的多线程示例

六、自动提交模式

七、数据类型映射

八、编码设置

九、小结

您可能感兴趣的文章:

相关内容