哎呀，碰到ORA-12170连接超时和ORA-12154 TNS解析错误确实让人头疼！不过既然Toad能正常连接目标数据库，说明数据库服务本身、基础网络链路是通的，问题大概率出在cx_Oracle依赖的Oracle客户端配置或者代码细节上，咱们一步步来排查：

1. 检查cx_Oracle与Oracle客户端的版本兼容性 #

cx_Oracle对Oracle客户端（Instant Client或完整客户端）的版本有严格要求，不匹配的版本会导致各种奇怪的连接问题——而Toad通常自带兼容的客户端，和你Python环境里的可能不是同一套。

• 排查步骤：

  1. 用命令查看当前cx_Oracle版本：

     pip show cx_Oracle
     

  2. 对照Oracle官方的兼容规则（比如cx_Oracle 8.x需要Oracle Client 12.2及以上版本，cx_Oracle 7.x支持11.2及以上），确认你安装的Oracle客户端版本是否匹配。

• 解决方法：
  卸载不兼容的Oracle客户端，安装对应版本的Oracle Instant Client，并将客户端的bin目录添加到系统环境变量PATH中，之后重启Python运行环境（IDE/命令行窗口）再尝试连接。

2. 确认TNS_ADMIN环境变量的配置 #

Toad会自动识别系统中的tnsnames.ora文件，但cx_Oracle默认需要通过TNS_ADMIN环境变量指向该文件的所在目录，否则无法正确解析TNS连接标识符。

• 排查步骤：

  1. 在Toad中查看你的连接属性，找到它使用的tnsnames.ora文件路径；
  2. 检查系统环境变量中是否存在TNS_ADMIN，且其值是否指向上述路径。

• 解决方法：

  • 添加或修改系统环境变量TNS_ADMIN，使其指向tnsnames.ora所在目录；
  • 或者在Python代码开头手动设置该环境变量（无需修改系统变量）：

    import os
    # Windows示例
    os.environ['TNS_ADMIN'] = 'C:\\app\\oracle\\product\\19c\\client_1\\network\\admin'
    # Linux/macOS示例
    # os.environ['TNS_ADMIN'] = '/opt/oracle/instantclient_19_12/network/admin'
    import cx_Oracle
    # 后续连接代码...
    

3. 排查防火墙与端口访问限制 #

虽然Toad能连接，但可能你的Python进程被本地防火墙拦截，或者数据库服务器的防火墙对不同进程的访问策略有区别。

• 排查步骤：

  1. 暂时关闭本地系统防火墙，尝试重新连接；
  2. 确认数据库服务器的防火墙允许你的IP访问Oracle服务端口（默认1521），同时注意：TNS解析可能需要UDP 1521端口，部分环境下Toad用TCP直接连接，而cx_Oracle默认尝试UDP解析。

• 解决方法：

  • 给Python.exe添加本地防火墙的出站规则，允许其访问Oracle端口；
  • 联系数据库管理员，确认你的IP在服务器防火墙的白名单中，且TCP（及UDP 1521，若需要）端口已开放。

4. 区分Service Name与SID的使用 #

你在代码中一直用service_name，但可能Toad连接时用的是SID而非Service Name，二者混淆会导致解析错误。

• 排查步骤：
  查看Toad的连接配置，确认它使用的是「Service Name」还是「SID」。

• 解决方法：
  如果Toad用的是SID，修改代码中的连接参数：

  import cx_Oracle
  ip = '[IP ADDRESS]'
  port = [PORT]
  sid = '[SID NAME]'
  dsn = cx_Oracle.makedsn(ip, port, sid=sid)
  db = cx_Oracle.connect('[USERNAME]', '[PASSWORD]', dsn)
  

5. 检查Oracle客户端的sqlnet.ora配置 #

sqlnet.ora文件中的参数会影响连接超时时间和解析方式，比如默认超时时间过短、限制了解析方式等。

• 排查步骤：
  找到sqlnet.ora文件（位于TNS_ADMIN目录下），检查是否有以下参数：

  • SQLNET.INBOUND_CONNECT_TIMEOUT：连接超时时间，默认可能过短；
  • NAMES.DIRECTORY_PATH：指定TNS解析方式，若只设置了TNSNAMES，则无法使用EZCONNECT格式（@host:port/service）。

• 解决方法：
  修改sqlnet.ora，增加超时时间并支持多种解析方式：

  SQLNET.INBOUND_CONNECT_TIMEOUT=60
  SQLNET.SEND_TIMEOUT=60
  SQLNET.RECV_TIMEOUT=60
  NAMES.DIRECTORY_PATH=(EZCONNECT, TNSNAMES)
  

先从版本兼容性和TNS_ADMIN配置开始排查，这两个是最常见的诱因，毕竟Toad能连接已经排除了核心的网络和数据库问题。

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