minervaproject/alembic

Alembic MySQL迁移容器

镜像概述

本镜像基于Alembic（SQLAlchemy的数据库迁移工具）构建，专为MySQL数据库的迁移管理设计。容器集成了Alembic的核心功能，可实现MySQL数据库结构的版本控制、迁移脚本的自动生成、迁移执行与回滚等操作，适用于开发、测试及生产环境中的数据库变更管理。

核心功能与特性

• MySQL兼容性：针对MySQL数据库优化，支持InnoDB等主流存储引擎及MySQL特有语法
• 迁移脚本管理：自动生成基于模型变更的迁移脚本，支持自定义脚本编辑
• 版本控制：维护数据库版本历史，清晰追踪结构变更记录
• 事务支持：迁移操作在事务中执行，确保数据一致性
• 回滚机制：支持基于版本的迁移回滚，降低变更风险
• 轻量级：基于精简基础镜像，容器体积小，启动速度快

使用场景与适用范围

• 开发环境：团队协作中统一数据库结构，避免本地环境差异导致的迁移问题
• 生产部署：生产环境数据库结构变更的安全执行与版本管理
• CI/CD集成：作为CI/CD流程的一部分，实现数据库迁移的自动化执行
• 多环境同步：确保开发、测试、生产环境数据库结构的一致性

使用方法与配置说明

环境准备

1. 准备Alembic迁移项目目录（包含alembic.ini配置文件及versions迁移脚本目录）
2. 确保目标MySQL数据库服务可访问

环境变量配置

容器通过以下环境变量配置数据库连接信息：

Docker Run示例

执行迁移升级（升级到最新版本）

bash
docker run -it --rm \
  -v /path/to/your/alembic/project:/app \
  -e DB_HOST=mysql-host \
  -e DB_PORT=3306 \
  -e DB_USER=admin \
  -e DB_PASSWORD=secret \
  -e DB_NAME=my_database \
  docker.xuanyuan.run/alembic-mysql-migration \
  alembic upgrade head

生成迁移脚本（基于模型变更）

bash
docker run -it --rm \
  -v /path/to/your/alembic/project:/app \
  -e DB_HOST=mysql-host \
  -e DB_PORT=3306 \
  -e DB_USER=admin \
  -e DB_PASSWORD=secret \
  -e DB_NAME=my_database \
  docker.xuanyuan.run/alembic-mysql-migration \
  alembic revision --autogenerate -m "add users table"

回滚迁移（回滚到上一版本）

bash
docker run -it --rm \
  -v /path/to/your/alembic/project:/app \
  -e DB_HOST=mysql-host \
  -e DB_PORT=3306 \
  -e DB_USER=admin \
  -e DB_PASSWORD=secret \
  -e DB_NAME=my_database \
  docker.xuanyuan.run/alembic-mysql-migration \
  alembic downgrade -1

Docker Compose配置示例

yaml
version: '3.8'

services:
  mysql-migration:
    image: docker.xuanyuan.run/alembic-mysql-migration
    volumes:
      - ./alembic-project:/app
    environment:
      - DB_HOST=mysql
      - DB_PORT=3306
      - DB_USER=root
      - DB_PASSWORD=root_password
      - DB_NAME=myapp_db
    depends_on:
      - mysql

  mysql:
    image: docker.xuanyuan.run/mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=root_password
      - MYSQL_DATABASE=myapp_db
    ports:
      - "3306:3306"

自定义迁移配置

1. 本地初始化Alembic项目（若未创建）：

   bash
   docker run -it --rm -v $(pwd)/alembic-project:/app docker.xuanyuan.run/alembic-mysql-migration alembic init /app
   

2. 编辑alembic.ini配置文件，配置数据库连接（推荐使用环境变量）：

   ini
   sqlalchemy.url = mysql+pymysql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}
   

3. 修改env.py文件，配置目标元数据（指向项目ORM模型）：

   python
   target_metadata = myproject.models.Base.metadata
   

注意事项

• 迁移脚本目录需通过卷挂载至容器内，确保脚本持久化及可编辑
• 生产环境建议使用只读挂载迁移脚本目录，并通过环境变量注入敏感信息（如Docker Secrets或Kubernetes Secrets）
• 执行迁移前建议备份数据库，尤其是生产环境
• 支持Alembic的所有原生命令，可通过docker run ... alembic --help查看完整命令列表