CI/CD 流水线中如何自动执行 SQLite 数据库迁移脚本

在 CI/CD 流水线中自动执行 SQLite 迁移，最稳妥的方式是将迁移命令放在部署阶段，确保数据库文件路径持久化且无并发写入。

命令速用版

如果你直接使用 sqlite3 命令行工具，可以在流水线脚本中加入以下命令来执行迁移文件或检查状态：

sqlite3 /path/to/database.db < migration.sql
sqlite3 /path/to/database.db ".schema"

如果是通过 ORM 框架（如 SQLAlchemy/Alembic 或 Django），通常使用框架自带的迁移命令：

alembic upgrade head
python manage.py migrate

为什么会这样

SQLite 与其他数据库最大的不同在于它是文件型的，没有独立的服务器进程。CI/CD 环境通常是临时的容器或虚拟机，构建结束后环境会被销毁。如果把数据库文件放在构建目录里，迁移完部署后文件可能就丢了。另外，SQLite 在写入时会锁住整个数据库文件，如果流水线多个任务同时尝试写入，或者应用正在运行时流水线强行迁移，容易导致数据库锁定错误。

分步处理

1. 脚本版本控制：确保所有迁移脚本（SQL 文件或 ORM 迁移文件）都提交到代码仓库，不要依赖本地生成。

2. 持久化存储配置：在 CI/CD 配置中，将数据库文件所在目录挂载为持久卷（Volume）或确保部署产物中包含该文件。例如在 GitHub Actions 中，可能需要上传构建产物（Artifact）并在部署步骤下载，或者直接操作远程服务器上的文件。

3. 执行迁移命令：在部署步骤（Deploy Stage）而非构建步骤（Build Stage）执行迁移。确保此时应用服务已暂时停止或处于只读模式，避免写入冲突。

# 示例：在部署脚本中
stop_application
run_migration_command
start_application

4. 错误处理：配置流水线在迁移失败时自动回滚或停止部署，不要忽略非零退出码。

怎么验证是否生效

1. 检查版本表：大多数迁移工具会维护一张版本表（如 alembic_version 或 django_migrations）。查询该表确认当前版本号是否符合预期。

sqlite3 app.db "SELECT * FROM alembic_version;"

2. 查看结构变更：使用 `.schema` 命令查看新表或新字段是否已存在。

3. 应用日志：启动应用后，观察启动日志中是否有数据库连接错误或表不存在的报错。

常见坑

1. 文件路径不一致：构建环境中的相对路径与运行环境不一致，导致迁移脚本找不到数据库文件。建议使用绝对路径或环境变量配置。

2. 数据库锁定：如果在应用运行时执行迁移，可能会遇到 "database is locked" 错误。务必确保迁移期间无写入操作。

3. 权限问题：CI/CD 运行用户可能没有数据库文件的写入权限。检查文件所有者和 chmod 设置。

4. WAL 模式文件丢失：如果开启了 WAL 模式，除了主数据库文件外，还要确保 .wal 和 .shm 文件也被正确持久化或清理，否则可能导致数据损坏。