Alembic Migrator Docker镜像文档

镜像概述

Alembic Migrator是一个基于Alembic的Docker镜像，旨在提供便捷、一致的数据库迁移解决方案。Alembic是SQLAlchemy的***迁移工具，支持多种关系型数据库的结构变更管理。本镜像封装了Alembic及其运行依赖，无需在本地环境安装配置，即可在任何支持Docker的环境中执行数据库迁移操作。

主要用途

• 简化数据库迁移流程，统一多环境迁移操作
• 支持开发、测试、生产等不同环境的数据库结构同步
• 集成到自动化部署流程，实现迁移步骤的标准化执行

核心功能与特性

• 轻量级设计：基于精简基础镜像，最小化资源占用
• 多数据库支持：兼容PostgreSQL、MySQL、SQLite、Oracle等主流关系型数据库
• 灵活配置：通过环境变量或挂载配置文件实现自定义设置
• 零依赖运行：无需本地安装Python、Alembic及数据库驱动
• 原生命令支持：完整支持Alembic所有原生命令，学***成本低
• 版本控制集成：可直接与Git等版本控制系统配合管理迁移脚本

使用场景

适用场景

• 开发环境：快速生成、测试迁移脚本，验证模型变更
• CI/CD流水线：作为部署前置步骤，自动执行迁移验证与应用
• 生产环境：标准化迁移流程，降低手动操作风险
• 多环境同步：确保开发、测试、预发、生产环境数据库结构一致性
• 团队协作：统一迁移工具版本，避免因本地环境差异导致的迁移问题

适用范围

• 使用SQLAlchemy ORM的Python项目
• 需要跨平台、跨环境执行数据库迁移的场景
• 追求自动化运维和DevOps实践的团队
• 需管理多版本数据库结构演进的项目

使用方法

前提条件

• 已安装Docker引擎
• 数据库服务可通过网络访问（本地或远程）
• 已准备Alembic迁移脚本目录（包含alembic.ini配置文件和versions迁移脚本目录）

基本使用命令

1. 执行迁移升级

bash
docker run -v $(pwd)/migrations:/app/migrations \
  -e DATABASE_URL="postgresql://user:password@db-host:5432/dbname" \
  alembic-migrator alembic upgrade head

2. 生成新迁移脚本

bash
docker run -v $(pwd)/migrations:/app/migrations \
  -e DATABASE_URL="mysql://user:password@mysql-host:3306/dbname" \
  alembic-migrator alembic revision --autogenerate -m "add user_email_index"

3. 回滚最近一次迁移

bash
docker run -v $(pwd)/migrations:/app/migrations \
  -e DATABASE_URL="sqlite:///./test.db" \
  alembic-migrator alembic downgrade -1

环境变量配置

Docker Compose配置示例

yaml
version: '3.8'

services:
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: apppass
      POSTGRES_DB: appdb
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 5s
      timeout: 5s
      retries: 5

  migrator:
    image: alembic-migrator
    volumes:
      - ./migrations:/app/migrations
    environment:
      DATABASE_URL: "postgresql://appuser:apppass@db:5432/appdb"
    depends_on:
      db:
        condition: service_healthy
    command: ["alembic", "upgrade", "head"]

自定义配置

如需使用自定义alembic.ini配置文件，可通过挂载文件覆盖默认配置：

bash
docker run -v $(pwd)/custom-alembic.ini:/app/migrations/alembic.ini \
  -v $(pwd)/migrations/versions:/app/migrations/versions \
  -e DATABASE_URL="oracle+cx_oracle://user:pass@host:1521/service" \
  alembic-migrator alembic history

常用Alembic命令

容器支持所有Alembic原生命令，常用命令包括：