200 lines
4.6 KiB
Markdown
200 lines
4.6 KiB
Markdown
# 数据库设置指南
|
||
|
||
本项目已配置支持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. **监控数据库连接状态**
|