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. 安装依赖

pip install -r requirements.txt

2. 配置数据库

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

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

3. 初始化数据库

使用数据库管理脚本：

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

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

4. 启动应用

python main.py

数据库管理

使用数据库管理脚本

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进行迁移

# 初始化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 中配置：

# 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         # 连接回收时间（秒）

环境变量

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

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日志：

DB_ECHO=true
LOG_LEVEL=debug

开发建议

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