dababase-etl-python/API_USAGE.md

# 数据库接口服务 API 使用说明

## 项目启动

1. 安装依赖：
```bash
pip install -r requirements.txt
```

2. 启动服务：
```bash
python main.py
```

3. 访问API文档：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## 主要功能

### 1. 数据库连接管理

#### 创建连接
```http
POST /api/v1/connections
Content-Type: application/json

{
    "db_type": "mysql",
    "host": "localhost",
    "port": 3306,
    "username": "root",
    "password": "password",
    "database": "test_db"
}
```

#### 获取所有连接
```http
GET /api/v1/connections
```

#### 关闭连接（POST，JSON传参）
```http
POST /api/v1/connections/close
Content-Type: application/json

{
    "connection_id": "mysql_localhost_3306_test_db"
}
```

### 2. 数据库信息查询

#### 获取数据库信息（使用query参数）
```http
GET /api/v1/databases/info?connection_id=<conn_id>
```

#### 获取表信息（使用query参数）
```http
GET /api/v1/databases/tables/info?connection_id=<conn_id>&table_name=<table>
```

### 3. SQL执行

#### 执行查询SQL
```http
POST /api/v1/query
Content-Type: application/json

{
    "connection_id": "mysql_localhost_3306_test_db",
    "sql": "SELECT * FROM users WHERE age > :age",
    "params": {"age": 18}
}
```

#### 执行非查询SQL
```http
POST /api/v1/execute
Content-Type: application/json

{
    "connection_id": "mysql_localhost_3306_test_db",
    "sql": "UPDATE users SET name = :name WHERE id = :id",
    "params": {"name": "新名称", "id": 1}
}
```

### 4. 表数据CRUD操作

#### 查询表数据
```http
POST /api/v1/tables/data/select
Content-Type: application/json

{
    "connection_id": "mysql_localhost_3306_test_db",
    "table_name": "users",
    "page": 1,
    "page_size": 10,
    "where_clause": "age > 18",
    "order_by": "id DESC"
}
```

#### 插入数据
```http
POST /api/v1/tables/data/insert
Content-Type: application/json

{
    "connection_id": "mysql_localhost_3306_test_db",
    "table_name": "users",
    "data": {
        "name": "张三",
        "age": 25,
        "email": "zhangsan@example.com"
    }
}
```

#### 更新数据（改为POST）
```http
POST /api/v1/tables/data/update
Content-Type: application/json

{
    "connection_id": "mysql_localhost_3306_test_db",
    "table_name": "users",
    "data": {
        "name": "李四",
        "age": 30
    },
    "where_clause": "id = 1"
}
```

#### 删除数据（改为POST）
```http
POST /api/v1/tables/data/delete
Content-Type: application/json

{
    "connection_id": "mysql_localhost_3306_test_db",
    "table_name": "users",
    "where_clause": "id = 1"
}
```

### 5. 表结构管理

#### 创建表
```http
POST /api/v1/tables/create
Content-Type: application/json

{
    "connection_id": "mysql_localhost_3306_test_db",
    "table_name": "new_table",
    "columns": [
        {
            "name": "id",
            "type": "INT",
            "primary_key": true,
            "not_null": true
        },
        {
            "name": "name",
            "type": "VARCHAR(100)",
            "not_null": true,
            "comment": "用户名称"
        }
    ]
}
```

#### 删除表（POST，JSON传参）
```http
POST /api/v1/tables/delete
Content-Type: application/json

{
    "connection_id": "mysql_localhost_3306_test_db",
    "table_name": "users"
}
```

#### 修改表结构（改为POST）
```http
POST /api/v1/tables/alter
Content-Type: application/json

{
    "connection_id": "mysql_localhost_3306_test_db",
    "table_name": "users",
    "operation": "ADD",
    "column_definition": {
        "name": "phone",
        "type": "VARCHAR(20)",
        "not_null": false
    }
}
```

### 6. 备注管理

#### 修改表或字段备注（改为POST）
```http
POST /api/v1/tables/comment
Content-Type: application/json

{
    "connection_id": "mysql_localhost_3306_test_db",
    "table_name": "users",
    "column_name": "name",
    "comment": "用户姓名字段"
}
```

### 7. 其他GET接口（统一使用query参数）

#### 获取数据库中的所有表
```http
GET /api/v1/tables?connection_id=<conn_id>
```

#### 获取表的所有字段信息
```http
GET /api/v1/tables/columns?connection_id=<conn_id>&table_name=<table>
```
```

## 支持的数据库类型

- **MySQL**: 使用 PyMySQL 驱动
- **Oracle**: 使用 oracledb 驱动
- **SQL Server**: 使用 pymssql 驱动
- **PostgreSQL**: 使用 psycopg2 驱动

## 响应格式

所有API接口都遵循统一的响应格式：

```json
{
    "success": true,
    "message": "操作成功",
    "data": {},
    "error": null
}
```

- `success`: 布尔值，表示操作是否成功
- `message`: 字符串，操作结果描述
- `data`: 对象，返回的数据（可选）
- `error`: 字符串，错误信息（仅在失败时存在）

## 注意事项

1. 连接ID格式：`{db_type}_{host}_{port}_{database}`
2. SQL参数使用命名参数格式，如 `:param_name`
3. 所有接口都支持CORS跨域访问
4. 服务启动后会自动管理数据库连接池
5. 应用关闭时会自动清理所有数据库连接