Golang轻量级框架无关数据库迁移工具插件dbmate的使用

概述

Dbmate是一个数据库迁移工具，可以帮助你在多个开发者和生产服务器之间保持数据库模式同步。它是一个独立的命令行工具，可以与Go、Node.js、Python、Ruby、PHP、Rust、C++或任何其他语言或框架一起使用。

主要特性

• 支持MySQL、PostgreSQL、SQLite和ClickHouse
• 使用纯SQL编写模式迁移
• 迁移文件使用时间戳版本，避免多开发者之间的版本号冲突
• 迁移在事务中原子性运行
• 支持创建和删除数据库（在开发/测试中很有用）
• 支持保存schema.sql文件，方便在git中比较模式变更
• 数据库连接URL通过环境变量定义（默认为DATABASE_URL），或通过命令行指定
• 内置支持从.env文件读取环境变量
• 易于分发，单个自包含二进制文件

安装

macOS

使用Homebrew安装：

brew install dbmate
dbmate --help

Linux

直接安装二进制文件：

sudo curl -fsSL -o /usr/local/bin/dbmate https://github.com/amacneil/dbmate/releases/latest/download/dbmate-linux-amd64
sudo chmod +x /usr/local/bin/dbmate
/usr/local/bin/dbmate --help

Windows

使用Scoop安装：

scoop install dbmate
dbmate --help

Docker

Docker镜像发布到GitHub Container Registry：

docker run --rm -it --network=host ghcr.io/amacneil/dbmate --help

基本命令

dbmate --help    # 打印帮助信息
dbmate new       # 生成新的迁移文件
dbmate up        # 创建数据库（如果不存在）并运行所有待处理的迁移
dbmate create    # 创建数据库
dbmate drop      # 删除数据库
dbmate migrate   # 运行所有待处理的迁移
dbmate rollback  # 回滚最近的迁移
dbmate down      # rollback的别名
dbmate status    # 显示所有迁移的状态
dbmate dump      # 导出数据库schema.sql文件
dbmate load      # 加载schema.sql文件到数据库
dbmate wait      # 等待数据库服务器可用

使用示例

1. 创建迁移文件

dbmate new create_users_table

这将创建一个迁移文件，如db/migrations/20230101000000_create_users_table.sql：

-- migrate:up
create table users (
  id integer,
  name varchar(255),
  email varchar(255) not null
);

-- migrate:down
drop table users;

2. 运行迁移

dbmate up

输出示例：

Creating: myapp_development
Applying: 20230101000000_create_users_table.sql
Applied: 20230101000000_create_users_table.sql in 123µs
Writing: ./db/schema.sql

3. 回滚迁移

dbmate rollback

输出示例：

Rolling back: 20230101000000_create_users_table.sql
Rolled back: 20230101000000_create_users_table.sql in 123µs
Writing: ./db/schema.sql

4. 查看迁移状态

dbmate status

数据库连接配置

默认情况下，dbmate使用DATABASE_URL环境变量来定位数据库。可以在.env文件中设置：

$ cat .env
DATABASE_URL="postgres://postgres@127.0.0.1:5432/myapp_development?sslmode=disable"

不同数据库的连接字符串格式

PostgreSQL

DATABASE_URL="postgres://username:password@127.0.0.1:5432/database_name?sslmode=disable"

MySQL

DATABASE_URL="mysql://username:password@127.0.0.1:3306/database_name"

SQLite

DATABASE_URL="sqlite:db/database.sqlite3"

ClickHouse

DATABASE_URL="clickhouse://username:password@127.0.0.1:9000/database_name"

在Go项目中使用dbmate作为库

package main

import (
	"net/url"

	"github.com/amacneil/dbmate/v2/pkg/dbmate"
	_ "github.com/amacneil/dbmate/v2/pkg/driver/postgres"
)

func main() {
	u, _ := url.Parse("postgres://postgres@127.0.0.1:5432/myapp_development?sslmode=disable")
	db := dbmate.New(u)

	err := db.CreateAndMigrate()
	if err != nil {
		panic(err)
	}
}

嵌入迁移文件

package main

import (
	"embed"
	"net/url"

	"github.com/amacneil/dbmate/v2/pkg/dbmate"
	_ "github.com/amacneil/dbmate/v2/pkg/driver/postgres"
)

//go:embed db/migrations/*.sql
var fs embed.FS

func main() {
	u, _ := url.Parse("postgres://postgres@127.0.0.1:5432/myapp_development?sslmode=disable")
	db := dbmate.New(u)
	db.FS = fs

	err := db.CreateAndMigrate()
	if err != nil {
		panic(err)
	}
}

高级用法

禁用事务

某些操作（如PostgreSQL中的ALTER TYPE）不能在事务中运行：

-- migrate:up transaction:false
ALTER TYPE colors ADD VALUE 'orange' AFTER 'red';

等待数据库可用

dbmate wait

或者与其他命令一起使用：

dbmate --wait up

自定义超时时间

dbmate --wait-timeout=5s wait

总结

Dbmate是一个简单易用的数据库迁移工具，具有以下优势：

1. 轻量级且独立，不依赖特定框架
2. 使用纯SQL编写迁移，易于理解和维护
3. 支持多种数据库
4. 提供创建/删除数据库、迁移、回滚等完整功能
5. 可以轻松集成到Go项目中作为库使用

通过合理使用dbmate，可以有效地管理数据库模式的变更，确保开发、测试和生产环境的一致性。