pbxx/migrate

Go Migration Tool 镜像文档

镜像概述

Go Migration Tool 是一个轻量级Docker镜像，封装了基于Go语言开发的数据库迁移工具，旨在简化数据库模式的版本化管理。该工具支持主流关系型数据库（如PostgreSQL、MySQL、SQLite、SQL Server等），通过命令行接口提供迁移脚本的创建、应用、回滚等操作，帮助开发团队在协作和部署过程中保持数据库结构一致性。

核心功能与特性

• 多数据库支持：兼容PostgreSQL、MySQL、SQLite、SQL Server等主流关系型数据库
• 版本化迁移管理：通过有序编号的迁移脚本跟踪数据库结构变更历史
• 迁移脚本生成：提供命令快速创建标准化的迁移脚本文件（包含"up"和"down"操作）
• 灵活迁移操作：支持全量迁移、指定版本迁移、回滚到上一版本或指定版本
• 事务安全保障：迁移操作默认在事务中执行，确保变更的原子性
• 轻量级设计：镜像体积小（基于Alpine），无额外依赖，可快速集成到各类环境
• 迁移记录追踪：自动维护迁移状态表，记录已执行的迁移脚本信息

使用场景与适用范围

• 开发环境：团队成员间快速同步数据库结构变更，减少"本地环境正常，测试环境异常"问题
• 持续集成/部署：作为CI/CD流程的环节，在应用部署前自动执行数据库迁移
• 生产环境：通过版本化迁移降低数据库变更风险，支持灰度发布场景下的结构同步
• 多环境一致性：确保开发、测试、预发、生产环境数据库结构的严格一致
• 数据库重构：支持大型数据库结构重构的分步实施与回滚预案

使用方法与配置说明

基本使用流程

1. 准备迁移脚本目录（本地文件系统），目录结构示例：

   migrations/
     ├── 001_create_users_table.up.sql
     ├── 001_create_users_table.down.sql
     ├── 002_add_email_index.up.sql
     └── 002_add_email_index.down.sql
   

2. 通过Docker命令挂载脚本目录并执行迁移操作

Docker Run 命令示例

1. 创建迁移脚本

bash
docker run --rm \
  -v $(pwd)/migrations:/app/migrations \
  go-migration-tool create add_user_status_column

执行后将在migrations目录生成两个文件：XXX_add_user_status_column.up.sql和XXX_add_user_status_column.down.sql（XXX为自动生成的序号）

2. 应用所有未执行的迁移

bash
docker run --rm \
  -v $(pwd)/migrations:/app/migrations \
  -e DB_DRIVER=postgres \
  -e DB_URL="host=db-host port=5432 user=dbuser password=dbpass dbname=mydb sslmode=disable" \
  go-migration-tool up

3. 回滚最近一次迁移

bash
docker run --rm \
  -v $(pwd)/migrations:/app/migrations \
  -e DB_DRIVER=mysql \
  -e DB_URL="root:password@tcp(mysql-host:3306)/mydb?charset=utf8mb4&parseTime=True&loc=Local" \
  go-migration-tool down 1

4. 查看迁移状态

bash
docker run --rm \
  -e DB_DRIVER=sqlite3 \
  -e DB_URL="./mydb.db" \
  go-migration-tool status

Docker Compose 集成示例

yaml
version: '3.8'
services:
  app:
    image: your-app-image
    depends_on:
      - db
      - migrate

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: dbuser
      POSTGRES_PASSWORD: dbpass
      POSTGRES_DB: mydb

  migrate:
    image: go-migration-tool
    volumes:
      - ./migrations:/app/migrations
    environment:
      DB_DRIVER: postgres
      DB_URL: "host=db port=5432 user=dbuser password=dbpass dbname=mydb sslmode=disable"
    command: up
    depends_on:
      - db

配置参数与环境变量

必选环境变量

可选环境变量

常用命令

注意事项

• 迁移脚本命名规范：建议使用{序号}_{描述}.up.sql和{序号}_{描述}.down.sql格式，序号需为整数且递增
• 生产环境迁移：执行前建议备份数据库，复杂变更需先在测试环境验证
• 并发控制：多实例同时执行迁移时，工具会通过锁表机制防止冲突
• SQLite注意：SQLite不支持部分DDL语句的事务回滚，使用时需谨慎设计down脚本