方法

connect( parameters… )

connect()用于创建与数据库连接类的构造函数，相关参数如下表所示。

参数	描述
dsn	数据源名称（Data Source Name），可包含数据库用户名、密码、数据库URL等信息，完整格式为user/password@url。在容器数据库中，如需连接PDB只能通过该参数指定数据库URL且必须使用v23.5.1.100及以上版本的Python驱动。 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] 参数含义： *数据库所在服务器的网络地址，可以为IPv4地址、IPv6地址或域名。在共享集群部署中，若已配置SCAN或VIP，还可以使用相应的域名或IP地址。 *port：数据库服务端监听端口，如安装过程中未进行调整，默认为1688。 *pdb_name：仅用于容器数据库，指定连接到具体某个PDB，省略则默认连接至根容器。 *primary：驱动会按指定监听地址的先后顺序连接节点，并通过执行SELECT * FROM DATABASE_ROLE判断节点角色，保留首次与主节点建立的连接。 *loadBalance：驱动会将指定的监听地址随机打乱顺序后进行连接，获取每个节点当前的会话数，选取会话数最小值对应的节点作为目标节点（若最小值存在多个节点则取最先建立连接的节点），保留目标节点的连接并关闭其他连接。
user	数据库用户名。 可选参数，若dsn中未指定则必选。
password	数据库用户密码。 可选参数，若dsn中未指定则必选。

Note:

• 多组监听地址连接的故障切换效率低于多个监听地址连接，分组主要用于尽可能保障仅通过第一组地址建立数据库连接，请根据实际需求选择是否分组。
• 在共享集群/分布式集群部署中，若已配置SCAN或VIP，直接使用数据库服务端提供的高可用能力即可，无需额外配置多地址连接。
• 配置多地址连接共享集群/分布式集群时：
  • 若为单集群部署，驱动会将其所有实例视作主节点。
  • 若为主备集群部署，驱动会将主集群的所有实例视作主节点、备集群的所有实例视作备节点。如需在未配置SCAN或VIP的场景下实现负载均衡，可考虑配置多组地址连接并按需指定primaryLoadBalance或standbyLoadBalance，主集群的所有实例为一个组，备集群的所有实例为另一个组。

如果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

属性

Python DB API v2.0规范中要求数据库模块都应该定义如下3个属性变量：

名称	含义	取值
apilevel	模块支持的Python DB API版本	2.0
paramstyle	参数标记的格式风格 目前固定为named，支持命名绑定（:name格式）和位置绑定（:1、:2格式）	named
threadsafety	模块接口支持的线程安全级别 目前固定为2，表示线程可以共享模块和连接但不能共享游标	2

Python开发人员可通过如下代码查看变量的值：

>>> import yaspy
>>> yaspy.threadsafety
2
>>> yaspy.apilevel
'2.0'
>>> yaspy.paramstyle
'named'

完整示例

import yaspy

# 方法1：使用dsn参数连接（推荐）
conn = yaspy.connect(
    dsn="sales/sales@192.168.1.2:1688"
)

# 方法2：使用dsn、user、password参数连接
# conn = yaspy.connect(
#     dsn="192.168.1.2:1688",
#     user="sales",
#     password="sales"
# )

# 方法3：多地址连接（primary类型，故障转移）
# conn = yaspy.connect(
#     dsn="sales/sales@192.168.1.2:1688,192.168.1.2:1688,192.168.1.2:1688"
# )

# 方法4：多地址连接（loadBalance类型，负载均衡）
# conn = yaspy.connect(
#     dsn="sales/sales@LOADBALANCE:192.168.1.2:1688,192.168.1.2:1688"
# )

# 创建游标
cursor = conn.cursor()

# 创建测试表
cursor.execute("DROP TABLE IF EXISTS test_yaspy")
cursor.execute("""
    CREATE TABLE test_yaspy (
        id INT PRIMARY KEY,
        name VARCHAR(50),
        value DECIMAL(10, 2)
    )
""")
conn.commit()
print('Table created successfully')

# 插入数据
cursor.execute(
    "INSERT INTO test_yaspy VALUES (:id, :name, :value)",
    {"id": 1, "name": "Product A", "value": 99.99}
)
conn.commit()
print('Data inserted successfully')

# 查询数据
cursor.execute("SELECT * FROM test_yaspy WHERE id = :id", {"id": 1})
row = cursor.fetchone()
print(f'Retrieved: id={row[0]}, name={row[1]}, value={row[2]}')

# 清理测试表
cursor.execute("DROP TABLE test_yaspy")
conn.commit()
print('Table cleaned up')

# 关闭游标和连接
cursor.close()
conn.close()
print('Connection closed')

执行：

Table created successfully
Data inserted successfully
Retrieved: id=1, name=Product A, value=99.99
Table cleaned up
Connection closed

其中：

• Table created successfully：测试表创建成功
• Data inserted successfully：数据插入成功
• Retrieved: id=1, name=Product A, value=99.99：查询返回的结果
• Table cleaned up：测试表清理完成
• Connection closed：连接关闭