hastyai/pg-migrator

PostgreSQL版本控制与迁移工具镜像文档

镜像概述

本镜像是一个针对PostgreSQL数据库的版本控制与迁移工具，旨在简化数据库架构变更的管理流程。通过版本化迁移脚本，实现数据库结构在开发、测试、生产等多环境中的一致性，支持迁移脚本的执行、回滚及历史记录追踪，是团队协作开发和自动化部署中数据库变更管理的核心工具。

核心功能与特性

• 版本化迁移脚本管理：按版本号组织SQL迁移脚本，支持增量更新与版本追踪
• 迁移执行与回滚：自动执行未应用的迁移脚本，支持指定版本回滚操作
• 环境隔离配置：支持多环境（开发/测试/生产）独立配置，避免环境间干扰
• 迁移历史记录：记录所有执行过的迁移操作，包括版本、时间、执行人等信息
• CI/CD集成：可无缝嵌入自动化部署流程，支持通过命令行或API触发迁移
• 错误处理与日志：详细记录迁移过程日志，迁移失败时提供清晰错误信息

使用场景与适用范围

• 多环境数据库同步：确保开发、测试、生产环境的PostgreSQL数据库结构一致
• 团队协作开发：多人协作时统一管理数据库变更，避免脚本冲突与覆盖
• 数据库升级与回滚：安全执行数据库架构升级，支持故障时快速回滚到稳定版本
• 自动化部署流程：在应用部署流水线中自动执行数据库迁移，减少人工操作
• 历史变更审计：追踪数据库结构变更历史，满足合规性与审计需求

使用方法与配置说明

1. 镜像获取

bash
docker pull <镜像名称>:<版本标签>  # 替换为实际镜像名称和版本

2. 基本使用（Docker Run）

前提条件

• 准备迁移脚本目录，按规范命名（如V1__create_users_table.sql、V2__add_email_column.sql）
• 确保PostgreSQL数据库服务可访问

执行命令

bash
docker run -it --rm \
  -v /本地迁移脚本目录:/app/migrations \  # 挂载迁移脚本目录
  -e POSTGRES_HOST=数据库主机IP \          # PostgreSQL主机地址
  -e POSTGRES_PORT=5432 \                  # PostgreSQL端口（默认5432）
  -e POSTGRES_USER=数据库用户名 \          # 数据库访问用户
  -e POSTGRES_PASSWORD=数据库密码 \        # 数据库访问密码
  -e POSTGRES_DB=目标数据库名 \            # 目标数据库名称
  -e MIGRATION_TABLE=schema_migrations \   # 迁移历史记录表名（默认schema_migrations）
  <镜像名称>:<版本标签> \                  # 镜像名称和版本
  migrate                                 # 执行迁移命令（或指定"rollback <版本号>"回滚）

3. Docker Compose配置示例

yaml
version: '3.8'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: myappdb
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d myappdb"]
      interval: 5s
      timeout: 5s
      retries: 5

  db-migration:
    image: <镜像名称>:<版本标签>
    volumes:
      - ./migrations:/app/migrations  # 本地迁移脚本目录（需提前创建）
    environment:
      POSTGRES_HOST: postgres         # 容器网络中PostgreSQL服务名
      POSTGRES_PORT: 5432
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: myappdb
    depends_on:
      postgres:
        condition: service_healthy
    command: migrate  # 启动时自动执行迁移

4. 迁移脚本规范

• 命名格式：V<版本号>__<描述>.sql（版本号为整数，双下划线分隔）
  • 示例：V1__init_schema.sql、V2__add_user_roles.sql
• 内容要求：
  • 每个脚本包含一个或多个SQL语句（需以分号结尾）
  • 建议避免破坏性操作（如DROP TABLE），如需执行需明确标注
  • 支持--rollback注释块定义回滚SQL（部分工具支持）：

    sql
    -- 迁移SQL
    CREATE TABLE users (id SERIAL PRIMARY KEY, name VARCHAR(50));
    
    --rollback
    DROP TABLE users;
    

5. 核心环境变量说明

常用命令

• 执行所有未应用迁移：docker run ... <镜像> migrate
• 回滚到指定版本：docker run ... <镜像> rollback <版本号>
• 查看已应用迁移：docker run ... <镜像> history
• 检查迁移状态：docker run ... <镜像> status（显示待执行/已执行迁移）