dababase-etl-python/ORACLE_CONNECTION_GUIDE.md

Oracle数据库连接指南

Oracle连接角色说明

什么是Oracle角色？

Oracle数据库中的角色（Role）是一组权限的集合，用于简化用户权限管理。角色不是连接参数，而是数据库内部的权限管理机制。

常见的Oracle角色

1. CONNECT - 基本连接权限

   • 允许用户连接到数据库
   • 创建表、视图、序列等基本对象

2. RESOURCE - 资源使用权限

   • 允许用户创建存储过程、触发器等
   • 使用表空间资源

3. DBA - 数据库管理员权限

   • 完全的数据库管理权限
   • 可以管理所有数据库对象

4. SELECT_CATALOG_ROLE - 数据字典查询权限

   • 允许查询数据字典视图

默认角色

对于普通用户（如 bizuser），通常会被授予以下默认角色：

• CONNECT - 基本连接权限
• RESOURCE - 资源使用权限

Oracle连接参数说明

基本连接参数

• 主机地址 (host): Oracle数据库服务器的IP地址或主机名
• 端口 (port): Oracle监听器端口，默认为1521
• 服务名称 (service_name): Oracle数据库的服务名称，如ORCLPDB1
• 用户名 (username): 数据库用户名
• 密码 (password): 数据库密码

高级连接参数

• mode: 连接模式

  • SYSDBA: 系统管理员模式
  • SYSOPER: 系统操作员模式
  • NORMAL: 普通用户模式（默认）

• threaded: 线程模式

  • true: 启用线程模式（推荐）
  • false: 禁用线程模式

连接字符串格式

标准格式

oracle+oracledb://username:password@host:port/service_name

带参数格式

oracle+oracledb://username:password@host:port/service_name?encoding=UTF-8&nencoding=UTF-8&threaded=true

用户提供的连接信息

根据您提供的Navicat连接信息：

主机地址: 192.168.13.27
端口: 1521
服务名称: ORCLPDB1
用户名: bizuser
密码: MySecurePass123
角色: Default (CONNECT + RESOURCE)

连接测试

使用测试脚本

1. 启动API服务：

   python main.py
   

2. 运行Oracle连接测试：

   python test_oracle_connection.py
   

使用API接口

{
  "db_type": "oracle",
  "host": "192.168.13.27",
  "port": 1521,
  "username": "bizuser",
  "password": "MySecurePass123",
  "database": "ORCLPDB1",
  "threaded": true
}

常见连接问题及解决方案

1. TNS: 无法解析指定的连接标识符

原因: 服务名称不正确或Oracle监听器未启动

解决方案:

• 检查服务名称是否正确
• 确认Oracle监听器正在运行
• 使用 lsnrctl status 检查监听器状态

2. ORA-12541: TNS: 无监听程序

原因: Oracle监听器未启动或端口被占用

解决方案:

• 启动Oracle监听器: lsnrctl start
• 检查端口1521是否被占用
• 确认防火墙设置

3. ORA-01017: 用户名/口令无效

原因: 用户名或密码错误

解决方案:

• 验证用户名和密码
• 检查用户账户是否被锁定
• 确认用户是否存在

4. ORA-12514: TNS: 监听程序当前无法识别连接描述符中请求的服务

原因: 服务名称不存在或未注册到监听器

解决方案:

• 检查服务名称是否正确
• 使用 lsnrctl services 查看可用服务
• 确认数据库实例正在运行

连接池配置

本项目为Oracle连接配置了专门的连接池参数：

engine_kwargs = {
    "pool_size": 10,        # 连接池大小
    "max_overflow": 20,     # 最大溢出连接数
    "pool_timeout": 30,     # 连接超时时间（秒）
    "pool_recycle": 3600    # 连接回收时间（秒）
}

环境变量配置

可以通过环境变量配置Oracle连接参数：

# .env文件
ORACLE_HOST=192.168.13.27
ORACLE_PORT=1521
ORACLE_USERNAME=bizuser
ORACLE_PASSWORD=MySecurePass123
ORACLE_SERVICE_NAME=ORCLPDB1

注意事项

1. 角色不是连接参数: Oracle角色是数据库内部的权限管理机制，不需要在连接字符串中指定
2. 服务名称 vs SID: 现代Oracle推荐使用服务名称而不是SID
3. 字符编码: 建议使用UTF-8编码以支持中文字符
4. 连接安全: 在生产环境中，建议使用SSL/TLS加密连接
5. 连接池: 使用连接池可以提高性能和资源利用率

技术支持

如果连接仍然失败，请检查：

1. Oracle客户端库是否正确安装
2. 网络连接是否正常
3. Oracle数据库服务是否运行
4. 防火墙和安全组设置
5. 用户权限是否足够