# 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服务：
   ```bash
   python main.py
   ```

2. 运行Oracle连接测试：
   ```bash
   python test_oracle_connection.py
   ```

### 使用API接口

```json
{
  "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连接配置了专门的连接池参数：

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

## 环境变量配置

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

```bash
# .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. 用户权限是否足够