blainehansen/postgres_migrator

镜像概述

该Docker镜像是一个专注于PostgreSQL数据库的原始SQL迁移工具，主要用于生成和管理数据库的SQL迁移脚本。它允许开发者通过简单的命令行操作，创建、组织和执行原生SQL格式的数据库迁移文件，确保数据库结构变更过程可追踪、可重复，简化数据库版本控制和多环境同步。

核心功能

• 迁移脚本生成：支持自动或交互式生成符合规范的PostgreSQL SQL迁移脚本，包含版本信息和描述，便于区分不同迁移操作。
• 迁移管理：跟踪已执行的迁移脚本状态，防止重复执行；提供迁移历史查询功能，清晰展示数据库变更记录。
• 原生SQL支持：专注于原始SQL脚本的处理，不依赖特定ORM框架，保留数据库操作的灵活性和原生特性。
• 跨环境兼容：支持通过配置适配不同PostgreSQL版本和环境，确保迁移脚本在开发、测试和生产环境中一致执行。

使用场景

• 新项目初始化：为新启动的PostgreSQL项目快速生成初始数据库结构迁移脚本，建立规范化的迁移管理流程。
• 数据库结构变更：在应用迭代过程中，管理表结构修改、字段增减、索引调整等SQL迁移操作。
• 多环境同步：通过统一的迁移脚本，确保开发、测试、预发布及生产环境的数据库结构保持一致。
• 团队协作：通过版本化的迁移脚本，实现团队成员间的数据库变更同步，避免手动SQL操作导致的结构不一致问题。

使用方法### 基本要求

• 本地需安装Docker环境。
• 需提前准备PostgreSQL数据库连接信息（主机、端口、数据库名、用户名、密码）。
• 建议通过本地目录挂载存储迁移脚本，确保数据持久化。

基本使用（docker run命令）#### 1. 生成迁移脚本

通过以下命令生成新的迁移脚本（需挂载本地目录存储脚本）：

bash
docker run -v $(pwd)/migrations:/app/migrations blainehansen/postgres-migration-tool generate --name create_users_table

• 参数说明：
  • -v $(pwd)/migrations:/app/migrations：将本地当前目录下的migrations文件夹挂载到容器内的/app/migrations目录，用于存储生成的迁移脚本。
  • generate --name create_users_table：执行生成命令，--name指定脚本名称（建议使用描述性名称，如create_users_table、add_email_index_to_users）。

执行后，migrations目录下会生成类似V1__create_users_table.sql的文件（V后为版本号，__后为脚本名称），可直接编辑该文件添加具体SQL语句。

2. 执行迁移脚本

通过以下命令执行已生成的迁移脚本（需配置数据库连接信息）：

bash
docker run -v $(pwd)/migrations:/app/migrations \
  -e POSTGRES_HOST=your-postgres-host \
  -e POSTGRES_PORT=5432 \
  -e POSTGRES_DB=your-db-name \
  -e POSTGRES_USER=your-db-user \
  -e POSTGRES_PASSWORD=your-db-password \
  blainehansen/postgres-migration-tool migrate

• 环境变量说明：
  • POSTGRES_HOST：PostgreSQL数据库主机地址。
  • POSTGRES_PORT：PostgreSQL数据库端口（默认5432）。
  • POSTGRES_DB：目标数据库名称。
  • POSTGRES_USER：数据库连接用户名（需具备执行DDL/DML权限）。
  • POSTGRES_PASSWORD：数据库连接密码。

3. 查看迁移历史

查询已执行的迁移记录：

bash
docker run -v $(pwd)/migrations:/app/migrations \
  -e POSTGRES_HOST=your-postgres-host \
  -e POSTGRES_PORT=5432 \
  -e POSTGRES_DB=your-db-name \
  -e POSTGRES_USER=your-db-user \
  -e POSTGRES_PASSWORD=your-db-password \
  blainehansen/postgres-migration-tool history

配置说明#### 环境变量配置

除上述基本连接参数外，支持以下可选环境变量：

• MIGRATION_TABLE：自定义迁移状态跟踪表名（默认schema_migrations），用于记录已执行的迁移版本。
• POSTGRES_SSL_MODE：PostgreSQL连接SSL模式（可选值：disable、allow、prefer、require，默认disable）。

迁移脚本规范

生成的迁移脚本需遵循以下规范：

• 文件名格式：V<版本号>__<脚本名称>.sql（如V2__add_email_to_users.sql），版本号需为整数且递增。
• 脚本内容：直接编写原生PostgreSQL SQL语句（如CREATE TABLE、ALTER TABLE等），无需额外格式封装。

示例：完整工作流

1. 初始化迁移目录：本地创建migrations文件夹。
2. 生成迁移脚本：执行docker run ... generate --name create_users_table，编辑生成的V1__create_users_table.sql文件，添加：

   sql
   CREATE TABLE users (
     id SERIAL PRIMARY KEY,
     username VARCHAR(50) NOT NULL UNIQUE,
     created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
   );
   

3. 执行迁移：配置数据库连接信息，执行docker run ... migrate，将表结构应用到数据库。
4. 验证迁移：通过history命令确认迁移已执行，或直接查询数据库验证表结构。

注意事项

• 迁移脚本一旦执行，建议避免修改已提交到版本库的历史脚本，如需回滚，建议生成新的回滚迁移脚本（如V2__drop_users_table.sql）。
• 生产环境执行迁移前，建议先在测试环境验证脚本正确性。
• 确保挂载的migrations目录有读写权限，避免容器内无法生成或读取脚本文件。