# kes-python

**Repository Path**: king-db/kes-python

## Basic Information

- **Project Name**: kes-python
- **Description**: Ksycopg2 是 KingbaseES 数据库的 Python 编程语言的客户端接口驱动。Ksycopg2 主要基于 libkci 加以封装实现而成，具有客户端及服务端游标、异步通信和通知及 COPY 支持。许多 Python 类型可以开箱即用，并适配 KingbaseES 数据库的大部分类型，也支持自定义类型扩展。Ksycopg2 基于 Psycopg2-2.8.5 开发。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: 2_9_1
- **Homepage**: https://gitee.com/king-db/kes-python
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-12-31
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Python

## README

Ksycopg2
===========================

## 简介

Ksycopg2 是 KingbaseES 数据库的 Python 编程语言的客户端接口驱动。

(电科金仓数据库管理系统 KingbaseES(KES) 是一款面向全行业、全客户关键应用的企业级大型通用数据库管理系统，适用于联机事务处理、查询密集型数据仓库、要求苛刻的互联网应用等场景，提供全部应用开发及系统管理功能，提供性能增强特性，可支持主备集群、读写分离集群、多活共享存储集群等全集群架构，具有高性能、高安全、高可用、易使用、易维护的特点，数据库支持国内外大部分的主流CPU、操作系统与云平台部署。)



Ksycopg2 主要特点是完全实现了 Python DB 2.0 规范，并实现了线程安全(多个线程可共用一个连接)。

Ksycopg2 主要基于 libkci 加以封装实现而成，具有客户端及服务端游标、异步通信和通知及COPY支持。且许多 Python 类型可以开箱即用，并适配 Kingbase 数据库的大部分类型，也支持自定义类型扩展。



Ksycopg2 基于 Psycopg2-2.8.5 开发。

## 编译说明

### 环境依赖

- Python开发环境，当前版本 Ksycopg2 支持的Python版本如下所示：

| Python版本 | Linux                     | Windows          |
| ---------- | ------------------------- | ---------------- |
| Python2.7  | x86/arm/loongarch/mips/sw | 默认提供64位支持 |
| Python3.5  | x86/arm/loongarch/mips/sw | 默认提供64位支持 |
| Python3.6  | x86/arm/loongarch/mips/sw | 默认提供64位支持 |
| Python3.7  | x86/arm/loongarch/mips/sw | 默认提供64位支持 |
| Python3.8  | x86/arm/loongarch/mips/sw | 默认提供64位支持 |
| Python3.9  | x86/arm/loongarch/mips/sw | 默认提供64位支持 |
| Python3.10 | x86/arm/loongarch/mips/sw | 默认提供64位支持 |
| Python3.11 | x86/arm/loongarch/mips/sw | 默认提供64位支持 |
| Python3.12 | x86/arm/loongarch/mips/sw | 默认提供64位支持 |
| Python3.13 | x86/arm/loongarch/mips/sw | 默认提供64位支持 |

- libkci动态库，可以从[KES数据库下载页面](https://www.kingbase.com.cn/xzzx/index.htm)获取对应平台架构的驱动包：

| 操作系统 | 依赖库                 |
| -------- | ---------------------- |
| Linux    | libkci.so、libkci.so.5 |
| Windows  | libkci.dll             |

### 编译步骤

1. 将libkci动态库放置在 config/lib 路径下(libkci 动态库可从 Kingbase 官网获取)，config文件夹目录如下所示：

config/  
├── include										// 编译时需要依赖的libkci头文件  
│   ├── kingbase_ext.h  
│   ├── libkci  
│   │   └── libkci_fs.h  
│   ├── libkci_fe.h  
│   └── sys_config_ext.h  
├── lib												// 存放libkci及其依赖库  
└── sys_config.c							   // 指定libkci依赖库及头文件的搜索路径  



2. 配置sys_config

可以使用数据库安装路径下的 bin 路径下的 sys_config，也可以使用源码包提供的 config 路径的 sys_config.c 来编译生成 sys_config：

```
// Linux
gcc -o sys_config sys_config.c

// Windows
cl sys_config.c
```

3. 执行setup.py构建生成

   构建生成Ksycopg2需要配置sys_config可执行文件的路径。

   以下提供两种方式构建生成驱动：

   1. 修改setup.cfg，添加sys_config的路径：

      ```
      ...
      # Linux
      sys_config = ../config/sys_config
      
      # Windows
      sys_config = ../config/sys_config.exe
      ...
      ```

      配置后执行编译安装：

      ```shell
      python setup.py build
      python setup.py install
      ```

   2. 编译时指定入参

      ```shell
      python setup.py build_ext --sys-config ../config/sys_config build
      python setup.py build_ext --sys-config ../config/sys_config install
      ```

   ​		PS：若在 Windows 上构建，需要将编译源码文件的字符集编码格式转为 UTF8-BOM，或使用scripts路径下 Python 脚本 add_bom.py 将指定路径下的所有文件统一进行格式转换：

   ```shell
   python add_bom.py ../ksycopg
   python add_bom.py ../config/include
   ```

4. 拷贝依赖库

   由于当前提供的 Ksycopg2 依赖库 libkci 都是以动态库的形式提供，所以系统可能出现找不到对应依赖库libkci而无法加载的场景，需要将libkci及其依赖库拷贝到 Ksycopg2 安装路径下即可。

## 安装测试

### 安装

由于当前没有提供 libkci 静态库，所以 Python 加载 Ksycopg2 时会依赖 libkci，libkci 可能额外依赖 SSL 或其他依赖库，故需要配置环境变量使系统能成功加载依赖库，以下是一个 Linux 添加环境变量的示例：

```
export LD_LIBRARY_PATH=libkci的路径
```

### 测试

考虑到部分内网环境，测试用例未使用pytest框架，方便用户直接执行 tests 路径下的用例测试。

需要注意的是，用例默认在数据库的 public 的 schema 下执行，其中用例有显示指定搜索 public 下的表或自定义类型。

1. 修改test_ksycopg2_utils.py，配置数据库连接参数

```python
database = "TEST"
user = "SYSTEM"
password = "123456"
host = "127.0.0.1"
port = "54321"
```

2. 根据不同 Python 版本执行用例

```shell
# python2
python test_ksycopg2-for-py2.py

# python3
python test_ksycopg2-for-py3.py
```

​	其中，涉及数据库通知等部分用例不一定在所有版本的数据库都能测试成功，不同版本可能有部分用例测试不过，这是由于数据库版本差异导致的问题，其主要功能如执行、拷贝等接口执行成功可忽略，或升级到最新版本的数据库。