如何用python-oracledb替代cx_Oracle实现SQLAlchemy连接OracleDB？

中文提问 #

我尝试用python-oracledb库替代cx_Oracle来创建SQLAlchemy引擎，但系统提示“cx_Oracle模块未找到”。请问有没有办法让SQLAlchemy使用python-oracledb创建引擎？

此前使用cx_Oracle时，我通过以下代码创建引擎：

conn_str = "oracle+cx_oracle://{user}:{password}@{host}:{port}"

我现在用以下代码尝试调用python-oracledb：

import oracledb
from sqlalchemy import create_engine, text

oracledb.init_oracle_client()

engine = create_engine(f'oracle://{p_username}:{p_password}@{p_dns}:{p_port}', max_identifier_length=128)

print(engine)

核心问题是SQLAlchemy默认的oracle://方言仍会尝试查找cx_Oracle，需要明确指定使用python-oracledb，具体操作如下：

1. 确保依赖版本达标 #

SQLAlchemy从1.4.32版本开始支持python-oracledb作为cx_Oracle的兼容替代，先升级依赖到符合要求的版本：

pip install --upgrade sqlalchemy python-oracledb

2. 使用正确的连接串 #

有两种可行的写法：

写法一：兼容cx_Oracle的连接串（推荐） #

python-oracledb安装后自带cx_Oracle的兼容接口，直接沿用原有的oracle+cx_oracle://连接串即可，SQLAlchemy会自动调用python-oracledb：

import oracledb
from sqlalchemy import create_engine

# 仅使用thick模式（依赖本地Oracle客户端）时需要这行，thin模式可跳过
oracledb.init_oracle_client()

conn_str = f"oracle+cx_oracle://{p_username}:{p_password}@{p_dns}:{p_port}"
engine = create_engine(conn_str, max_identifier_length=128)

print(engine)

写法二：直接指定oracledb方言（SQLAlchemy 2.0+支持） #

如果你的SQLAlchemy是2.0及以上版本，可以直接用oracle+oracledb://连接串，语义更清晰：

import oracledb
from sqlalchemy import create_engine

# 仅thick模式需要初始化客户端
oracledb.init_oracle_client()

conn_str = f"oracle+oracledb://{p_username}:{p_password}@{p_dns}:{p_port}"
engine = create_engine(conn_str, max_identifier_length=128)

print(engine)

3. 模式选择提示 #

• thin模式：python-oracledb默认模式，无需本地安装Oracle客户端，可直接去掉oracledb.init_oracle_client()这行代码。
• thick模式：依赖本地Oracle客户端，必须调用oracledb.init_oracle_client()，且需确保客户端路径配置正确。

内容的提问来源于stack exchange，提问作者hootowl