如何将 Vue-FastAPI-Admin 项目的数据库从 SQLite 切换到 MySQL？

近期在github上看到一个开源项目，vue-fastapi-admin。它基于 FastAPI + Vue3 + Naive UI 的现代化前后端分离开发平台，融合了 RBAC 权限管理、动态路由和 JWT 鉴权，助力中小型应用快速搭建，也可用于学习参考。
由于该项目中数据库用的是SQLite本地数据库，其自身具有的一些局限性，现决定将 Vue-FastAPI-Admin 项目的数据库从 SQLite 切换到 MySQL！以下是具体操作步骤和注意事项：

---

一、环境准备

1. 安装 MySQL 驱动

pip install pymysql  # 或 mysql-connector-python

2. 创建 MySQL 数据库

CREATE DATABASE fastapi_admin 
  CHARACTER SET utf8mb4 
  COLLATE utf8mb4_unicode_ci;

---

二、配置修改

1. 修改数据库连接配置

找到项目中的数据库配置文件（通常是 .env 或 config.py），将 SQLite 配置改为 MySQL：

原 SQLite 配置：

SQLALCHEMY_DATABASE_URL = "sqlite:///./sql_app.db"

修改为 MySQL 配置：

SQLALCHEMY_DATABASE_URL = "mysql+pymysql://<用户名>:<密码>@<主机>/<数据库名>"
# 示例：
SQLALCHEMY_DATABASE_URL = "mysql+pymysql://root:password@localhost/fastapi_admin"

2. 调整 ORM 配置（以 SQLAlchemy 为例）

# 添加连接池配置（可选但推荐）
engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    pool_size=20,          # 连接池大小
    max_overflow=10,       # 最大溢出连接数
    pool_pre_ping=True     # 自动检测连接有效性
)

---

三、代码调整

1. 修改模型定义（如有必要）

检查模型中 SQLite 特定语法：

# 原 SQLite 自增配置（通常无需修改）
id = Column(Integer, primary_key=True, index=True, autoincrement=True)

# MySQL 同样支持 autoincrement，无需改动

2. 调整 DDL 生成

如果使用 alembic 进行迁移：

# alembic/env.py
target_metadata = models.Base.metadata

---

四、数据库迁移

1. 初始化数据库结构

alembic upgrade head  # 如果使用迁移工具
# 或通过 ORM 自动创建表

2. 数据迁移（如果已有数据）

使用 sqlite3 导出数据：

sqlite3 sql_app.db .dump > dump.sql

处理 SQL 差异后导入 MySQL：

mysql -u root -p fastapi_admin < dump.sql

注意处理以下差异：

1. 移除 AUTOINCREMENT 关键字
2. 转换 BOOLEAN 类型（0/1 → TRUE/FALSE）
3. 调整 DATETIME 格式（推荐统一使用 UTC 时间）

---

五、常见问题处理

1. 字符编码问题

在 MySQL 连接字符串显式指定编码：

SQLALCHEMY_DATABASE_URL = "mysql+pymysql://root:password@localhost/fastapi_admin?charset=utf8mb4"

2. 时区配置

# 连接字符串追加时区参数
SQLALCHEMY_DATABASE_URL += "&sql_mode=STRICT_TRANS_TABLES&timeout=28800&connect_timeout=60&charset=utf8mb4&time_zone=+8:00"

3. 连接超时问题

在 SQLAlchemy 配置中添加：

engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    pool_recycle=3600  # 每小时回收连接
)

---

六、验证测试

1. 连接测试

from sqlalchemy import text
with engine.connect() as conn:
    result = conn.execute(text("SELECT version()"))
    print(result.fetchone())  # 应输出 MySQL 版本号

2. 功能回归测试

重点检查：

• 事务提交/回滚
• 并发写入操作
• 时间类型字段的存储

---

七、部署注意事项

1. 备份策略：从文件备份改为 mysqldump
2. 性能调优：根据负载调整连接池参数
3. 监控配置：添加 MySQL 的慢查询日志监控

---

完整修改示例：

# 修改后的 database.py 示例
from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

SQLALCHEMY_DATABASE_URL = "mysql+pymysql://root:password@localhost/fastapi_admin?charset=utf8mb4"

engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    pool_size=20,
    max_overflow=10,
    pool_pre_ping=True,
    pool_recycle=3600
)

SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

完成以上修改后，重启 FastAPI 服务即可使用 MySQL 作为后端数据库。建议在切换前做好数据备份和测试验证。