结论：应弃用 cx_Oracle，改用 Oracle 官方维护的纯 Python 驱动 oracledb，避开 Windows PATH 依赖陷阱；其 thin 模式免客户端、兼容 Python 3.8–3.12，支持 Easy Connect Plus 连接串、Oracle Wallet 安全认证及健壮连接池配置。
直接说结论：用 cx_Oracle 不再可靠，必须切换到 oracledb（Oracle 官方维护的纯 Python 驱动），且需避开 Windows 上的 PATH 依赖陷阱。
为什么 cx_Oracle 现在不推荐用了
Oracle 官方自 2022 年起已将主力转向 oracledb，cx_Oracle 停止新功能开发，且对 Python 3.12+ 支持滞后。更关键的是，cx_Oracle 强依赖本地 Oracle Client（如 instantclient），Windows 下容易因 PATH 冲突、位数不匹配（32/64）、DLL 加载失败导致 ImportError: DLL load failed 或运行时 ORA-12154。
-
oracledb默认是“thin 模式”，纯 Python 实现，无需安装客户端，开箱即连 - 若需高级特性（如 Kerberos、高级队列），可显式启用“thick 模式”，再按需部署
instantclient - Python 3.8–3.12 全版本兼容，PyPI 安装即用：
pip install oracledb
连接字符串怎么写才不容易出错
Oracle 连接字符串格式灵活但易混淆，尤其在服务名、SID、Easy Connect 之间。生产环境强烈建议统一用 Easy Connect Plus 格式，它明确、可读、支持高可用配置。
- 基础写法：
"username/password@host:port/service_name"—— 注意不是sid，除非你确认数据库用的是 SID（极少见） - 带 wallet 的 TLS 连接：
"username/password@tcps://host:2484/service_name?wallet_location=/path/to/wallet" - 故障转移示例：
"username/password@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=primary)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=standby)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=mydb)))"，但更推荐用 TNSNAMES.ORA +config_dir参数加载
如何安全传入用户名密码又不硬编码
硬写密码在代码或 .env 里都存在泄露风险，oracledb 原生支持外部认证和凭据缓存，优先级高于明文。
立即学习“Python免费学习笔记（深入）”；
- 用 Oracle Wallet（推荐）：
oracledb.connect(dsn="mydb", wallet_location="/secure/wallet", wallet_password="walletpass")，此时完全不用传用户名密码 - 用操作系统凭证（仅 Linux/macOS）：
oracledb.connect(dsn="mydb", externalauth=True)，依赖sqlnet.ora中SQLNET.AUTHENTICATION_SERVICES = (BEQ, TCPS) - 若必须用环境变量，请用
os.getenv("DB_USER")+getpass.getpass()交互式输入密码，避免日志打印明文
连接池配置不当会导致超时或资源耗尽
Web 应用或批量任务中，不配连接池或参数不合理，会触发 ORA-12519: no appropriate service handler 或频繁重连拖慢性能。
- 最小可用池：
oracledb.create_pool(min=2, max=10, increment=1, user="u", password="p", dsn="mydb") - 关键参数必须设：
getmode=oracledb.POOL_GETMODE_WAIT（阻塞获取）、timeout=60（空闲连接自动回收）、ping_interval=60（健康检查间隔） - 切勿在每次请求中新建 pool —— pool 是全局复用对象，初始化一次，全程共享
- 验证是否生效：查
v$session，看到PROGRAM列含python且STATUS多数为INACTIVE，说明复用正常
真正难的不是连上，而是连得稳、断得清、换得快。比如 wallet 路径权限不对、oracledb 在 thick 模式下仍残留旧 instantclient 的 PATH、连接池未正确 close 导致 fd 耗尽——这些细节不出现在文档首页，但每天都在线上报错里反复出现。
