如何使用Python远程连接本地部署（On-Premise）的Oracle数据库

一、先搞定服务器端核心配置（这步没做好，客户端怎么折腾都没用） #

• 确认Oracle监听服务运行状态：在服务器上执行 lsnrctl status，检查输出里是否有对应数据库的监听条目，默认端口是1521，要是改了端口得记准。
• 开放防火墙端口：服务器防火墙必须允许你的客户端IP访问监听端口（比如1521）。Linux用ufw allow 1521/tcp或firewall-cmd --add-port=1521/tcp --permanent；Windows在防火墙高级设置里添加入站规则。
• 配置用户远程权限：给数据库用户授予远程连接权限，执行SQL语句：GRANT CREATE SESSION TO your_username;，同时确认服务名正确——服务器上执行SELECT value FROM v$parameter WHERE name='service_names';就能查到。

二、客户端环境准备 #

• 安装Oracle Instant Client：不管用cx_Oracle还是新版oracledb，部分场景都需要这个（oracledb有thin模式，适合Oracle 12c+，但老版本Oracle还是得装）。下载对应系统和Oracle版本的基础包，解压后配置环境变量：
  • Linux：export LD_LIBRARY_PATH=/path/to/instantclient:$LD_LIBRARY_PATH
  • Windows：把Instant Client的路径加入系统PATH环境变量
• 安装Python驱动：
  • 用cx_Oracle的话：pip install cx_Oracle
  • 推荐用新版oracledb（cx_Oracle的继任者）：pip install oracledb

三、连接代码示例 #

cx_Oracle写法 #

import cx_Oracle

# 方式1：用makedsn构建连接串
dsn = cx_Oracle.makedsn("服务器IP", 1521, service_name="你的服务名")
conn = cx_Oracle.connect(user="用户名", password="密码", dsn=dsn)

# 方式2：直接用EZCONNECT格式
# conn = cx_Oracle.connect("用户名/密码@服务器IP:1521/服务名")

cursor = conn.cursor()
cursor.execute("SELECT * FROM dual")
print(cursor.fetchone())

cursor.close()
conn.close()

oracledb写法（推荐） #

import oracledb

# Thin模式（无需Instant Client，Oracle 12c+适用）
conn = oracledb.connect(
    user="用户名",
    password="密码",
    dsn="服务器IP:1521/服务名"
)

# 也可以用makedsn方式
# dsn = oracledb.makedsn("服务器IP", 1521, service_name="你的服务名")
# conn = oracledb.connect(user="用户名", password="密码", dsn=dsn)

cursor = conn.cursor()
cursor.execute("SELECT sysdate FROM dual")
print(f"数据库当前时间: {cursor.fetchone()[0]}")

cursor.close()
conn.close()

四、常见问题排查 #

• 报错ORA-12541: TNS:no listener：检查服务器监听是否启动、防火墙端口是否开放、客户端IP是否被允许访问。
• 报错ORA-12514: TNS:listener does not currently know of service requested in connect descriptor：确认服务名是否和服务器上查询到的一致。
• 报错ORA-01031: insufficient privileges：检查用户是否有CREATE SESSION权限，用户名密码是否输入正确。
• cx_Oracle找不到库文件：确认Instant Client的环境变量配置正确，或者切换到oracledb的thin模式试试。

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