连接池对象（Connection Pool Object）用于管理和复用Python应用程序与数据库之间的连接。

仅yaspy模块支持池化连接。

对象创建方式

连接池对象需通过poolname = yaspy.SessionPool(parameters…)创建，相关参数如下表所示。

参数	描述
user	数据库用户名。必填参数。
password	数据库用户密码。必填参数。
dsn	数据源名称（Data Source Name），格式为host:port[/pdb_name]。在容器数据库中，如需连接PDB只能通过该参数指定数据库URL且必须使用v23.5.1.100及以上版本的Python驱动。 Note：SessionPool的dsn参数仅支持host:port格式（不含user/password@前缀），用户名和密码必须通过独立的user和password参数指定。若将user/password@url格式用于SessionPool，会将整串当作主机名解析，导致连接失败（YAS-00402）。 URL格式如下： * 单地址连接：host:port[/pdb_name] * 多地址连接（primary类型）：host:port,host:port,host:port[/pdb_name]或PRIMARY:host:port,host:port,host:port[/pdb_name] * 多地址连接（loadBalance类型）：LOADBALANCE:host:port,host:port,host:port[/pdb_name] 参数含义： *host：数据库所在服务器的网络地址，可以为IPv4地址、IPv6地址或域名。在共享集群部署中，若已配置SCAN或VIP，还可以使用相应的域名或IP地址。 *port：数据库服务端监听端口，如安装过程中未进行调整，默认为1688。 *pdb_name：仅用于容器数据库，指定连接到具体某个PDB，省略则默认连接至根容器。 *primary：驱动会按指定监听地址的先后顺序连接节点，并通过执行SELECT * FROM DATABASE_ROLE判断节点角色，保留首次与主节点建立的连接。 *loadBalance：驱动会将指定的监听地址随机打乱顺序后进行连接，获取每个节点当前的会话数，选取会话数最小值对应的节点作为目标节点（若最小值存在多个节点则取最先建立连接的节点），保留目标节点的连接并关闭其他连接。
min	当前连接池的最小连接数，取值范围为正整数，可选参数，默认值为1。
max	当前连接池的最大连接数，取值范围为正整数，可选参数，默认值为4。
increment	单次可创建的连接数，可选参数，默认值为1。 当池内连接耗尽但总连接数不超过max值时，新请求会根据increment值创建新连接。
getmode	连接获取模式，可选参数，目前固定为1，具体表现为： - 如果池内存在空闲连接，直接获得连接。 - 如果池内连接耗尽但总连接数不超过max值时，新请求会根据increment值创建新连接。 - 如果池内连接耗尽且总连接数已达到max值时，直接报错。

如果user和password中有特殊字符/、@、\，需要使用符号\进行转义，举例如下：

dsn	user	password	host	port
192.168.1.2:1688	未指定	未指定	192.168.1.2	1688
sys@192.168.1.2:1688	sys	未指定	192.168.1.2	1688
sys/yasdb_123@192.168.1.2:1688	sys	yasdb_123	192.168.1.2	1688
sys/yasdb\@_123@192.168.1.2:1688	sys	yasdb@_123	192.168.1.2	1688
sys\//yasdb\@_123@192.168.1.2:1688	sys/	yasdb@_123	192.168.1.2	1688
s\/ys\@\\/yasdb\@_123@192.168.1.2:1688	s/ys@\	yasdb@_123	192.168.1.2	1688

连接池方法

方法	说明
poolname.acquire()	获取连接。
poolname.release()	归还连接。
poolname.close()	立即关闭连接池。

上下文管理协议

连接池对象支持Python的上下文管理器协议，可使用with语句自动管理连接的获取和归还。

# 使用with语句管理连接池连接
with pool.acquire() as conn:
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM table")
    for row in cursor:
        print(row)
# 连接自动归还到连接池

完整示例

import yaspy

# 创建连接池
pool = yaspy.SessionPool(
    user="sales",
    password="sales",
    dsn="192.168.1.2:1688",
    min=1,
    max=4,
    increment=1
)
print('Connection pool created')
print(f'Pool status: min={pool.min}, max={pool.max}')

# 1. acquire() - 获取连接
conn1 = pool.acquire()
print('Connection 1 acquired')

conn2 = pool.acquire()
print('Connection 2 acquired')

# 使用连接进行数据库操作
cursor1 = conn1.cursor()
cursor2 = conn2.cursor()

# 创建测试表
cursor1.execute("DROP TABLE IF EXISTS test_pool")
cursor1.execute("""
    CREATE TABLE test_pool (
        id INT PRIMARY KEY,
        name VARCHAR(50)
    )
""")
conn1.commit()
print('Table created')

# 使用连接1插入数据
cursor1.execute("INSERT INTO test_pool VALUES (1, 'Product A')")
cursor1.execute("INSERT INTO test_pool VALUES (2, 'Product B')")
conn1.commit()
print('Data inserted via connection 1')

# 使用连接2查询数据
cursor2.execute("SELECT * FROM test_pool ORDER BY id")
rows = cursor2.fetchall()
print(f'Queried via connection 2: {len(rows)} records:')
for row in rows:
    print(f'  id={row[0]}, name={row[1]}')

# 2. release() - 归还连接
pool.release(connection=conn1)
print('Connection 1 released')

pool.release(connection=conn2)
print('Connection 2 released')

# 再次获取连接
conn3 = pool.acquire()
print('Connection 3 acquired (reused from pool)')

cursor3 = conn3.cursor()
cursor3.execute("SELECT * FROM test_pool")
rows = cursor3.fetchall()
print(f'Connection 3 query result: {len(rows)} records')

# 清理测试表
cursor3.execute("DROP TABLE test_pool")
conn3.commit()
print('Table cleaned up')

# 关闭游标和归还连接
cursor3.close()
pool.release(connection=conn3)
print('Connection 3 released')

# 3. close() - 关闭连接池
pool.close()
print('Connection pool closed')

Note：

本示例在fetchall()后用len(rows)统计SELECT结果行数。rowcount在查询刚执行完尚未获取时为0；获取过程中会累计已取行数，但不宜在未取数时用rowcount表示结果集总行数。

执行：

Connection pool created
Pool status: min=1, max=4
Connection 1 acquired
Connection 2 acquired
Table created
Data inserted via connection 1
Queried via connection 2: 2 records:
  id=1, name=Product A
  id=2, name=Product B
Connection 1 released
Connection 2 released
Connection 3 acquired (reused from pool)
Connection 3 query result: 2 records
Table cleaned up
Connection 3 released
Connection pool closed

其中：

• Connection pool created：连接池创建成功
• Pool status: min=1, max=4：连接池状态（最小1个，最大4个连接）
• Connection 1 acquired：从连接池获取第1个连接
• Connection 2 acquired：从连接池获取第2个连接
• Table created：测试表创建成功
• Data inserted via connection 1：使用连接1插入数据成功
• Queried via connection 2：使用连接2查询数据
• Connection 1 released：归还连接1到连接池
• Connection 2 released：归还连接2到连接池
• Connection 3 acquired (reused from pool)：获取连接3（从连接池复用）
• Connection 3 query result：连接3查询结果
• Table cleaned up：测试表清理完成
• Connection 3 released：归还连接3到连接池
• Connection pool closed：连接池已关闭