通过cx_Oracle连接Oracle实例时遇ORA-12154错误求助

问题背景 #

在AWS EC2实例部署的Oracle实例上，通过Linux终端执行以下命令可成功连接：

ubuntu@ip-xxx-xx-xx-xxx:~$ sqlplus user101/pass101@ip-xxx-xx-xx-xxx:1521/XE

但使用cx_Oracle以相同参数连接时，抛出错误："ORA-12154: TNS:could not resolve the connect identifier specified"。附上tnsnames.ora文件内容：

XE =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = ip-172-xx-xx-xx)(PORT = 1521))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = XE)
    )
  )

EXTPROC_CONNECTION_DATA =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC_FOR_XE))
    )
    (CONNECT_DATA =
      (SID = PLSExtProc)
      (PRESENTATION = RO)
    )
  )

~       

核心原因分析 #

sqlplus用的是**EZ Connect（简易连接）**模式，不需要依赖tnsnames.ora就能直接解析host:port/service_name格式的连接串。但cx_Oracle若配置不当，会尝试从tnsnames.ora查找连接标识符，当前环境存在以下潜在问题：

• tnsnames.ora末尾的~符号会导致文件解析失败
• cx_Oracle未识别EZ Connect格式，或未配置TNS_ADMIN环境变量指向正确的tnsnames.ora路径
• tnsnames.ora里的HOST是EC2内网IP，若cx_Oracle运行在外部环境则无法访问

解决方案 #

方案1：直接用EZ Connect字符串连接 #

确保cx_Oracle版本（建议8.0+）支持EZ Connect格式，代码中直接传入完整连接串：

import cx_Oracle

# 方式1：直接传入完整连接串
conn = cx_Oracle.connect("user101/pass101@ip-xxx-xx-xx-xxx:1521/XE")

# 方式2：用DSN对象构建连接
dsn = cx_Oracle.makedsn("ip-xxx-xx-xx-xxx", 1521, service_name="XE")
conn = cx_Oracle.connect("user101", "pass101", dsn)

方案2：修复tnsnames.ora并配置环境变量 #

1. 清理文件：删除tnsnames.ora末尾的~符号，避免解析错误。
2. 配置TNS_ADMIN环境变量：
   • 先找到tnsnames.ora的实际路径，通常在Oracle安装目录下的$ORACLE_HOME/network/admin
   • 运行Python脚本前设置环境变量（Linux）：

     export TNS_ADMIN=/path/to/oracle/network/admin
     

   • 或在Python代码中直接设置：

     import os
     os.environ['TNS_ADMIN'] = '/path/to/oracle/network/admin'
     

3. 用TNS别名连接：

   import cx_Oracle
   conn = cx_Oracle.connect("user101/pass101@XE")
   

方案3：调整tnsnames.ora的HOST配置 #

如果cx_Oracle运行在EC2实例外部，把tnsnames.ora中的HOST改为EC2的公网IP或弹性域名，同时确保EC2安全组开放1521端口的入站规则。

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