oracledb 8.3+ 默认且仅支持瘦模式，纯Python实现，无需Oracle Client；连接只需user/password/dsn（推荐Easy Connect格式），不支持Wallet、Kerberos等高级功能，需厚模式方可启用。
瘦模式是默认模式，无需额外配置
从 python-oracledb 8.3 版本起，瘦（Thin）模式已是唯一默认模式，不再依赖 Oracle Client。只要安装的是 8.3+ 版本，oracledb.connect() 就自动走纯 Python 实现的瘦路径——你不需要设 mode=oracledb.MODE_THIN，也不用调 oracledb.init_oracle_client()。
验证方式很简单：
import oracledb print(oracledb.version) print(oracledb.thin)
如果输出 True（且版本 ≥ 8.3），说明当前就是瘦模式。
连接字符串里不能含 Oracle Client 相关参数
瘦模式不支持 lib_dir、config_dir、driver_name 这类只在厚（Thick）模式下生效的参数。一旦传入，会静默忽略或引发 NotSupportedError。
立即学习“Python免费学习笔记（深入）”；
常见误配场景：
- 复制旧版
cx_Oracle或厚模式示例，硬塞lib_dir="/path/to/instantclient" - 在
oracledb.init_oracle_client()后仍试图用瘦模式连接（该函数仅对厚模式有效） - 连接 URL 中带
/?wallet_location=...—— 瘦模式暂不支持 Wallet 认证（截至 8.4）
正确写法只需基础连接信息：
conn = oracledb.connect(
user="scott",
password="tiger",
dsn="localhost:1521/orclpdb1"
)
遇到 ORA-12154 或 DNS 解析失败，先检查 DSN 格式
瘦模式解析 dsn 完全靠 Python 自己实现，不调系统 hosts 或 Oracle Net 配置。它只认三种格式：
- Easy Connect 字符串：
"host:port/service_name"（推荐，最轻量） - TNS 别名（需配合
tnsnames.ora）→ 瘦模式不支持，除非你手动启用厚模式 - 完整 TNS 描述符（即括号套括号的字符串）→ 瘦模式支持，但必须语法严格，不能有换行或多余空格
典型错误：
ORA-12154: TNS:could not resolve the connect identifier specified → 很可能用了未被识别的别名，或 tnsnames.ora 路径没生效（瘦模式根本不读它）。
调试建议：
- 优先用
"host:port/service_name"格式，例如"localhost:1521/XEPDB1" - 服务名（service_name）不是 SID；查库可用
SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL; - 如必须用复杂描述符，请确保是单行、无注释、括号匹配，例如：
"(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=XEPDB1)))"
需要高级功能（如 Kerberos、Wallet、AQ）时，瘦模式可能不够用
目前瘦模式功能集仍在收敛中。以下特性在 8.4 版本中仍 仅厚模式支持：
-
externalauth（操作系统认证） - Kerberos 认证（
auth_mode=oracledb.AUTH_MODE_OS等） - Oracle Wallet 文件加载（
wallet_location,wallet_password） - Advanced Queuing（AQ）操作
- 部分 LOB 流式读写优化
若项目依赖上述任一能力，就得切回厚模式：显式调用 oracledb.init_oracle_client()，并确保 Instant Client 已安装且可访问。这时瘦/厚切换就不再是“配置问题”，而是架构取舍——纯 Python 的简洁性 vs Oracle 官方客户端的完整性。
最容易被忽略的一点：同一进程里不能混用瘦和厚模式。初始化厚模式后，所有后续连接都走厚路径，哪怕你没传任何 thick-only 参数。
