Python 原生实现 KaiwuDB 时序数据库连接池方案

背景

鉴于官方文档缺失，本文提供自主构建方案。

经测试验证可用。

KaiwuDB 连接池架构方案

由于 KaiwuDB (KWDB) 目前未内置连接池组件，为了在生命科学大数据高频读写场景下降低连接握手开销（约 30-100ms/次），我们需要自主构建一个高性能的 Python 数据库连接池。

一、架构设计逻辑

应用请求连接 -> 池中是否有空闲连接？
    是 -> 获取空闲连接 -> 执行 SQL 业务逻辑 -> 逻辑释放连接
    否 -> 当前总连接数 < 最大上限？
        是 -> 物理创建新连接 -> 进入等待队列
        否 -> 超时报错

自动维护逻辑：定时巡检 -> 连接是否超时/失效？
    是 -> 心跳重连/移除销毁
    否 -> 回收到空闲队列

注：此方案采用 Python 原生 threading 与 psycopg2 开发，不依赖外部 SQLAlchemy 以保持轻量化。

二、核心模块设计

文件名	核心职责	详细功能点说明
manager.py	资源调度与生命周期管理	1. 单例模式实现：通过 new 确保全局唯一连接池实例。

2. 动态扩缩容：管理 min_size 与 max_size，支持在高并发下自动排队。
3. 健康巡检 (Check-on-Borrow)：借出连接前执行 SELECT 1 验证。
4. 线程安全控制：利用 threading.Condition 实现多线程同步与唤醒机制。 | | connection.py | 连接包装与逻辑回收 | 1. 代理模式包装：使用 PooledConnection 封装原生 psycopg2 连接对象。
5. 拦截 close() 方法：将'物理关闭'重定向为'逻辑归还'，将连接重新压入空闲队列。
6. 上下文管理支持：实现 enter 与 exit，支持 with 语句安全调用。
7. 透明属性转发：通过 getattr 保持对原生连接属性的无缝访问。 | | exceptions.py | 异常定义与分类管理 | 1. 统一基类定义：定义 PoolError 作为所有连接池异常的父类。
8. 精准异常捕获：提供 PoolEmptyError 处理获取连接超时或池满的情况。