fastapi-demo/DATABASE_SETUP.md

# 数据库设置指南

本项目已配置支持MySQL数据库，包含完整的数据库模型、迁移脚本和管理工具。

## 目录结构

```
sql/
├── migrations/          # 数据库迁移文件
│   └── 001_create_tables.sql
├── seeds/              # 种子数据文件
│   └── sample_data.sql
└── schemas/            # 数据库架构文件
    └── init_database.sql

alembic/                # Alembic迁移工具
├── versions/           # 自动生成的迁移版本
├── env.py             # Alembic环境配置
└── script.py.mako     # 迁移模板

app/database/           # 数据库相关代码
├── __init__.py
├── connection.py       # 数据库连接管理
├── base.py            # 基础模型类
└── models.py          # SQLAlchemy模型
```

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置数据库

创建 `.env.dev` 文件（参考 `.env.example`）：

```env
# MySQL 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=fastapi_demo
DB_CHARSET=utf8mb4
```

### 3. 初始化数据库

使用数据库管理脚本：

```bash
# 初始化数据库（创建数据库和表，插入示例数据）
python database_manager.py init

# 或者分步执行
python database_manager.py create-db      # 创建数据库
python database_manager.py create-tables  # 创建表
python database_manager.py seed          # 插入示例数据
```

### 4. 启动应用

```bash
python main.py
```

## 数据库管理

### 使用数据库管理脚本

```bash
python database_manager.py init      # 初始化数据库
python database_manager.py reset     # 重置数据库
python database_manager.py create-db # 仅创建数据库
python database_manager.py create-tables # 仅创建表
python database_manager.py seed      # 仅插入示例数据
python database_manager.py help      # 显示帮助
```

### 使用Alembic进行迁移

```bash
# 初始化Alembic（首次使用）
alembic init alembic

# 创建新的迁移
alembic revision --autogenerate -m "描述信息"

# 执行迁移
alembic upgrade head

# 回滚迁移
alembic downgrade -1

# 查看迁移历史
alembic history

# 查看当前版本
alembic current
```

## 数据库模型

### 用户表 (users)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int(11) | 主键，自增 |
| username | varchar(50) | 用户名，唯一 |
| email | varchar(100) | 邮箱，唯一 |
| full_name | varchar(100) | 全名，可空 |
| is_active | tinyint(1) | 是否激活 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### 产品表 (products)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int(11) | 主键，自增 |
| name | varchar(200) | 产品名称 |
| description | text | 产品描述，可空 |
| price | decimal(10,2) | 价格 |
| stock | int(11) | 库存数量 |
| is_available | tinyint(1) | 是否可用 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

## 配置说明

### 数据库连接配置

在 `app/core/config.py` 中配置：

```python
# MySQL 数据库配置
DB_HOST: str = "localhost"          # 数据库主机
DB_PORT: int = 3306                 # 数据库端口
DB_USER: str = "root"               # 数据库用户名
DB_PASSWORD: str = ""               # 数据库密码
DB_NAME: str = "fastapi_demo"       # 数据库名称
DB_CHARSET: str = "utf8mb4"         # 字符集

# 数据库连接池配置
DB_POOL_SIZE: int = 5               # 连接池大小
DB_MAX_OVERFLOW: int = 10           # 最大溢出连接数
DB_POOL_TIMEOUT: int = 30           # 连接超时时间（秒）
DB_POOL_RECYCLE: int = 3600         # 连接回收时间（秒）
```

### 环境变量

支持通过环境变量覆盖配置：

```bash
export DB_HOST=localhost
export DB_PORT=3306
export DB_USER=root
export DB_PASSWORD=your_password
export DB_NAME=fastapi_demo
```

## 故障排除

### 常见问题

1. **连接失败**
   - 检查MySQL服务是否启动
   - 验证数据库配置信息
   - 确认用户权限

2. **字符编码问题**
   - 确保数据库使用utf8mb4字符集
   - 检查连接字符串中的charset参数

3. **迁移失败**
   - 检查Alembic配置
   - 确认数据库连接正常
   - 查看迁移文件语法

### 日志调试

启用SQL日志：

```env
DB_ECHO=true
LOG_LEVEL=debug
```

## 开发建议

1. **使用迁移管理数据库结构变更**
2. **在开发环境中使用示例数据**
3. **定期备份生产数据库**
4. **使用连接池优化性能**
5. **监控数据库连接状态**