MyBatis Migrations 教程

官网地址：http://mybatis.org/migrations
GitHub地址：https://github.com/mybatis/migrations

简介

MyBatis Migrations 是一款基于 SQL 的数据库版本控制系统，它由 MyBatis 团队开发。该工具的设计目的是为了简化数据库迁移过程，以便更好地追踪、管理和应用数据库模式的变更。

以下是 MyBatis Migrations 的一些主要特性：

SQL 为中心：MyBatis Migrations 是基于 SQL 的，这意味着数据库迁移脚本是用 SQL 语言编写的。这样的设计使得数据库管理员和开发人员可以直接使用熟悉的 SQL 语言来管理数据库模式的变更。
支持撤销操作：MyBatis Migrations 提供了撤销操作，这使得你可以方便地撤销最近的数据库模式变更。每个迁移脚本都包含两部分：一部分用于执行数据库变更，另一部分用于撤销这些变更。
自动版本控制：每次你执行一个新的数据库迁移，MyBatis Migrations 都会在一个特殊的表（默认名为 changlog）中记录这次变更。这使得你可以很容易地查看历史变更，以及查看哪些迁移已经被应用，哪些还未被应用。
灵活性和可定制性：MyBatis Migrations 允许你定制迁移过程。例如，你可以选择在什么时间应用哪些迁移，你也可以选择是否执行撤销操作。
支持命令行和编程式 API：你可以通过命令行工具来使用 MyBatis Migrations，也可以在你的 Java 代码中调用 MyBatis Migrations 的 API。

MyBatis Migrations 是一款非常实用的数据库版本控制工具，尤其适合喜欢直接使用 SQL 管理数据库模式的团队。

注意❗️❗️❗️

MyBatis Migrations 是一个 Java 工具，因此您必须安装 Java 才能继续。用户至少需要 Java 运行时环境(JRE)，而安装 Java 开发工具包 (JDK) 则更好。MyBatis Migrations 需要 Java 版本 8 或更高版本。

安装

1. 下载项目压缩包

下载地址址：点击下载 mybatis-migrations-3.3.11

2. 解压到自定义目录

解压后目录文件结构：

mybatis-migrations-3.3.11

lib/mybatis-${project.version}.jar
lib/mybatis-migrations-${project.version}.jar
bin/migrate --------------------------------------（linux 执行命令）
bin/migrate.cmd ---------------------------------（windows 执行命令）
LICENSE
NOTICE
MIGRATIONS-README

3. 配置环境变量

Mac 系统
1. 编辑 .bash_profile 文件，文件最后追加如下内容：
```
export MIGRATIONS_HOME=/Users/superman/工具/mybatis-migrations-3.3.11
export PATH="$MIGRATIONS_HOME/bin:$PATH"
```
  MIGRATIONS_HOME 的值为项目包的目录路径
2. 执行命令 source .bash_profile 使环境变量配置生效
3. 验证是否配置成功，执行命令 migrate info 输出结果如下则表明配置成功

开始使用

新建一个空目录

mkdir test

进入 `test` 目录，执行初始化命令

migrate init

在 test 目录下会自动生成 3 个目录

drivers ------------ JDBC 驱动库，.jar 或 .zip 文件
environments ----- 数据库配置文件
scripts ------------ 迁移脚本

下载 JDBC 驱动文件

这里以 PostgreSQL 为例，下载地址：https://jdbc.postgresql.org/download/

将下载好的 jar 包，放到 drivers 目录下即可

配置文件

environments 目录有一个默认配置文件 development.properties
还可以创建 local.properties pro.properties文件
运行迁移时，可以使用 --env= 选项指定环境（不包含路径或 .properties部分）
如：migrate up --env=local

配置示例 - 数据库配置

## JDBC connection properties.
driver=org.postgresql.Driver
url=jdbc:postgresql://127.0.0.1:54320/test
username=homestead
password=secret

验证数据库是否连接成功
输出内容没有报错信息表明成功，没有成功根据报错信息进行排查

migrate status

使用

常用命令：
migrate new
migrate up
migrate down

初始化数据库配置（新库可以忽略此步骤）
脚本文件位于 ./script/bootstrap.sql，通常用来定义你在开始使用 MyBatis Migrations 管理数据库版本之前，数据库中已经存在的表和数据，bootstrap.sql 文件的具体内容将取决于你的数据库的现状。

文件应该包含你数据库中所有已经存在的表的创建语句，以及其他任何你需要记录的数据库状态（如索引、视图、存储过程等）

migrate bootstrap

新建迁移脚本

migrate new "create users table"

该命令将创建了一个 sql 文件，格式为：时间戳_自定义描述.sql

20230528075331_create_users_table.sql

默认前缀为时间戳，当然也可以在初始化 init 命令加上参数 --idpattern=0000 来设置前缀

migrate --idpattern=0000 init

migrate new "create users table"

这时候新创建的迁移脚本文件名前缀就发生变化了

0003_create_users_table.sql

脚本文件内容格式：

-- // create users table
-- Migration SQL that makes the change goes here. 更改脚本语句放在这里，如 CREATE TABLE xxx()



-- //@UNDO
-- SQL to undo the change goes here. 回滚脚本语句放在这里，如 DROP TABLE  xxx

开始迁移

先查看一下当前状态

mybatis-migrations/db/test$ migrate status
------------------------------------------------------------------------
-- MyBatis Migrations - status
------------------------------------------------------------------------
ID             Applied At          Description
================================================================================
1             ...pending...      create changelog
2             ...pending...      first migration
3             ...pending...      create users table

执行 migrate up
查看一下状态

mybatis-migrations/db/test$ migrate status
------------------------------------------------------------------------
-- MyBatis Migrations - status
------------------------------------------------------------------------
ID             Applied At          Description
================================================================================
1         2023-05-30 00:26:23     create changelog
2         2023-05-30 00:26:23     first migration
3         2023-05-30 00:26:23     create users table

执行 migrate down
查看一下状态

mybatis-migrations/db/test$ migrate status
------------------------------------------------------------------------
-- MyBatis Migrations - status
------------------------------------------------------------------------
ID             Applied At          Description
================================================================================
1         2023-05-30 00:26:23     create changelog
2         2023-05-30 00:26:23     first migration
3             ...pending...       create users table

命令列表

命令格式：migrate {命令}

命令	作用	示例	描述
info	显示构建版本信息	migrate info
init	创建并初始化迁移脚本的存储库	migrate init	--path 指定生存储库位置，默认当前目录(必须为空目录) ，--idpattern 设置生成脚本文件的前缀，默认为当前时间戳
bootstrap	执行数据库起始脚本，初始化数据库	migrate bootstrap	执行数据库起始脚本，创建迁移脚本基线（用于已存在的数据库）
new	创建迁移脚本	migrate new "create users table"	根据模板在 ./scripts 目录下创建前缀为 --idpattern (默认时间戳) 的脚本 "create blog table" 为生成的脚本描述生成的文件名为 "(前缀 + create_blog_table)"
up	提交并执行迁移脚本	migrate up	依次运行所有待处理迁移脚本的 do 部分
down	回滚迁移脚本	migrate down	执行迁移脚本的 undo 部分，并使状态变为 pending，默认回退一个版本，后面加上数字可指定回退 n 个版本
version	执行到指定版本的迁移脚本	migrate version 20230526032814	版本小于等于 20230526032814 并且状态为 pending 的所有迁移脚本都会执行 do 部分，版本大于 20230526032814 并且状态为已 up 的所有迁移脚本都会执行 undo 部分
pending	执行有冲突的迁移脚本	migrate pending	当你 new 一个 script 且没有 up 之前，有另外的人 new 了一个 script 且 up 了，此时你执行 up 将会不成功，你需要先确定你的 script 与之无冲突之后执行 pengding
status	显示当前迁移脚本状态	migrate status	查看当前工作空间状态 Applied At 为提交时间 pending 表示状态为待执行
script	合并迁移脚本	migrate script 版本1 版本2 > do.sql	合并“版本1”到“版本2”的 do 脚本，从小到大合并的是 do 脚本
		migrate script 版本2 版本1 > undo.sql	合并“版本2”到“版本1”的 undo 脚本，从大到小合并的是 undo 脚本
		migrate script pending > pending.sql	合并状态为 pending 的 do 脚本