使用cx_Oracle连接Oracle数据库时遭遇ORA-12569错误求助

问题场景 #

使用Python 3.9.18 + cx_Oracle连接Oracle数据库时，执行以下代码报错：

connection = cx_Oracle.connect(user=username, password=password, dsn=dsn, mode=cx_Oracle.SYSDBA)

错误信息：

cx_Oracle.DatabaseError: ORA-12569: TNS:packet checksum failure

但使用相同TNS字符串通过sqlplus sys@ as sysdba及tnsping均可正常连接，且已尝试在脚本中设置os.environ['LD_LIBRARY_PATH']，问题仍未解决。

排查与解决步骤 #

• 确认cx_Oracle与Oracle客户端版本兼容性
  cx_Oracle对Oracle Instant Client版本有严格依赖，需确保两者版本匹配（比如Python3.9建议搭配cx_Oracle 8.x系列，对应Oracle Instant Client 19c或21c）。同时注意：脚本内设置LD_LIBRARY_PATH可能时机过晚，cx_Oracle加载时已读取环境变量，建议在终端先执行export LD_LIBRARY_PATH=/path/to/oracle/client/lib，再运行Python脚本，或在虚拟环境激活脚本中配置该变量。

• 禁用或调整TCP校验和配置
  在Oracle客户端的sqlnet.ora文件中添加以下配置（若没有该文件，可在客户端lib目录下新建）：

  SQLNET.CRYPTO_CHECKSUM_CLIENT = OFF
  

  或者在TNS连接字符串中直接指定参数，示例：

  (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=your_host)(PORT=your_port))(CONNECT_DATA=(SID=your_sid))(SECURITY=(CRYPTO_CHECKSUM_CLIENT=OFF)))
  

• 排查SYSDBA模式的特殊限制
  尝试去掉mode=cx_Oracle.SYSDBA参数，用普通用户权限连接测试。若普通连接正常，说明SYSDBA模式触发了额外校验：

  • 检查数据库端sqlnet.ora是否设置了SQLNET.CRYPTO_CHECKSUM_SERVER = REQUIRED，此时客户端需同步开启校验（将SQLNET.CRYPTO_CHECKSUM_CLIENT设为REQUIRED，并指定匹配的校验算法如(MD5)）。

• 排查网络层干扰
  尽管tnsping正常，但数据包传输可能被防火墙、代理或网络设备修改：

  • 尝试用数据库服务器IP代替主机名写入TNS字符串；
  • 关闭本地防火墙或测试直连数据库服务器的网络环境。

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