推荐优先使用 oracledb（Oracle 官方推荐、纯 Python 实现、默认 Thin 模式无需客户端），安装 pip install oracledb，支持 Easy Connect 连接字符串、连接池、Thick 模式及常见问题处理。

Python 连接 Oracle 数据库，主流方式是使用 cx_Oracle（旧版）或其继任者 oracledb（Oracle 官方推荐、纯 Python 实现、无需 Oracle 客户端）。推荐优先使用 oracledb，尤其新项目。

安装 oracledb（推荐）

执行命令安装：

pip install oracledb

注意：oracledb 无需安装 Oracle Instant Client（除非使用 Thick 模式），默认运行在 Thin 模式，开箱即用。

基本连接与查询

使用用户名、密码、主机、端口和 SID 或服务名构造连接字符串。常见写法如下：

• 使用 Easy Connect 字符串（最简）："username/password@host:port/service_name"
• 使用完整 TNS 格式（适合复杂网络配置）："username/password@//host:port/service_name"

示例代码：

import oracledb
连接
conn = oracledb.connect(
user="scott",
password="tiger",
dsn="localhost:1521/orclpdb1"  # 或 "localhost:1521/ORCLPDB1"
)
创建游标并查询
cursor = conn.cursor()
cursor.execute("SELECT * FROM employees WHERE ROWNUM <= 5")
for row in cursor:
print(row)
cursor.close()
conn.close()

处理连接参数与配置

生产环境建议用连接池提升性能，避免频繁创建/关闭连接：

• 调用 oracledb.create_pool() 创建连接池
• 从池中获取连接：pool.acquire()，用完归还：pool.release(conn)
• 可设置最小/最大连接数、超时时间等参数

若需兼容旧系统或使用高级功能（如 LDAP、高级队列），可启用 Thick 模式（需先安装 Oracle Instant Client）：

oracledb.init_oracle_client(lib_dir="/path/to/instantclient")

常见问题提醒

• 报错 DPY-3002（无法解析连接描述符）：检查 service_name 是否正确，可用 sqlplus 验证
• 中文乱码：确保数据库字符集（如 AL32UTF8）与 Python 环境一致；oracledb 默认 UTF-8，一般无需额外设置
• 连接被拒绝：确认 Oracle 监听器运行中，防火墙放行端口（默认 1521），且数据库已 open
• 旧项目还在用 cx_Oracle？它已停止维护，建议逐步迁移到 oracledb（API 高度兼容，仅需替换 import 和少量初始化代码）