goose是一个用go语言编写的数据库版本管理的命令行工具。其github地址如下:https://github.com/pressly/goose
数据库版本管理,其实就是对数据表结构的演进的管理。比如,我们有一个用户表user,如下:
create table if not exists `user` (
id int auto_increcement comment '主键',
name varchar(255) NOT NULL DEFAULT '' COMMENT '用户姓名',
PRIMARY KEY (`id`)
) ENGINE=InnoDB charset='utf-8' COMMENT='用户表';
过了一段时间,需要在该表中增加一个字段address:
alter table `user` add column address varchar(255) NOT NULL DEFAULT '' COMMENT '用户地址';
又过了一段时间,又需要创建一个用户好友表user_friends:
CREATE TABLE if not exists `user_friends` (
id int auto_increcement comment '主键',
user_id int NOT NULL DEFAULT 0 COMMENT '用户ID',
friend_id int NOT NULL DEFAULT 0 COMMENT '好友用户ID',
PRIMARY KEY (`id`)
) ENGINE=InnoDB charset='utf-8' COMMENT='用户好友表'
你看,上面这些就是对数据库结构的演进。但在演化的过程中,就有可能造成许多问题。比如在多种环境下(生产、测试、预发布环境)数据结构没保持一致问题。数据库的变更没有统一的文档管理等一些列问题。
接下来我们来看看goose是如何管理数据库的演进的。
goose是一个使用golang语言编写的命令行工作。我们可以在go代码中引入,也可以通过安装在电脑上直接使用。
安装在$GOPATH/bin目录下:
$ go install github.com/pressly/goose/v3/cmd/goose@latest
在Mac下使用brew安装:
brew install goose
安装完成后,使用goose命令即可对数据库进行管理了。goose命令的使用格式如下:
goose [OPTIONS] DRIVER DBSTRING COMMAND
user:password@/dbname?parseTime=true
up Migrate the DB to the most recent version available
up-by-one Migrate the DB up by 1
up-to VERSION Migrate the DB to a specific VERSION
down Roll back the version by 1
down-to VERSION Roll back to a specific VERSION
redo Re-run the latest migration
reset Roll back all migrations
status Dump the migration status for the current DB
version Print the current version of the database
create NAME [sql|go] Creates new migration file with the current timestamp
fix Apply sequential ordering to migrations
validate Check migration files without running them
以下是对不同数据库的示例:
goose sqlite3 ./foo.db status
goose sqlite3 ./foo.db create init sql
goose sqlite3 ./foo.db create add_some_column sql
goose sqlite3 ./foo.db create fetch_user_data go
goose sqlite3 ./foo.db up goose postgres "user=postgres password=postgres dbname=postgres sslmode=disable" status
goose mysql "user:password@/dbname?parseTime=true" status
goose redshift "postgres://user:[email protected]:5439/db" status
goose tidb "user:password@/dbname?parseTime=true" status
goose mssql "sqlserver://user:password@dbname:1433?database=master" status
goose clickhouse "tcp://127.0.0.1:9000" status
goose vertica "vertica://user:password@localhost:5433/dbname?connection_load_balance=1" status
看到上述示例,我们知道了使用的数据库类型、数据库的连接地址以及对数据库要做的具体动作。但这个动作要执行什么呢,是不是还少了具体的数据库的定义语句呢?
其实,在上面的命令中还隐含着一个选项就是dir:指定数据库的DDL文件的目录。默认是在当前目录下读取sql文件。
所以,goose的作用即使将指定目录下的sql文件 按指定的子命令进行执行。
goose的工作原理实际上就是维护了一个有规则版本号的sql文件。在sql文件中通过标记sql语句是升级还是回退来来告知goose如何执行。goose本质上就是两个子命令:升级操作(goose Up)和回退操作(goose Down)。其他的reset子命令和redo子命令都是对升级和回退操作的组合。
下面是升级和回退操作的流程图:
通过goose的子命令就可以对sql文件进行管理。下面我们详细介绍下goose的各个子命令的含义以及执行的动作。
该命令是创建一个sql的迁移文件。如下:
goose mysql "user:password@/dbname?parseTime=true" create add_some_column sql
运行该命令后,就会在当前目录下生成一个sql文件:20231011222931_add_some_column.sql
。
create命令后的add_some_column就是文件名,sql就是要生成的文件类型。在生成的文件中我们看到文件名前缀中还有一个日期的前缀,这个是命令自动生成的,用来标识文件的版本。这个版本号在up和down命令的时候会非常有用,稍后详细介绍。
生成了sql文件后,就可以在该文件中添加数据表的定义内容了。首先我们看下该sql文件的格式:
-- +goose Up
-- +goose StatementBegin
SELECT 'up SQL query';
-- +goose StatementEnd-- +goose Down
-- +goose StatementBegin
SELECT 'down SQL query';
-- +goose StatementEnd
在该文件中,我们看到有两部分内容:
-- +goose Up
这样的指令:这个指令告诉goose工具,接下来的内容是要在up子命令下执行的。同理,-- +goose Down指令告诉goose工具,其接下来的内容是在down命令下执行的。基于上述sql模版文件,我们就可以编写自己的数据库的DDL语言了。示例如下:
-- +goose Up
CREATE TABLE users (
id int NOT NULL PRIMARY KEY,
username text,
name text,
surname text
);INSERT INTO users VALUES
(0, 'root', '', ''),
(1, 'vojtechvitek', 'Vojtech', 'Vitek');
-- +goose Down
DROP TABLE users;
up子命令是从--dir
指定的目录下(默认是当前目录)读取sql文件,然后执行sql文件中的 -- +goose Up
下的具体的sql语句。同时,goose
还会在数据库中生成一个goose_db_version
表,该表里记录了执行过的sql文件。如下:
CREATE TABLE `goose_db_version` (
`id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
`version_id` bigint(20) NOT NULL,
`is_applied` tinyint(1) NOT NULL,
`tstamp` timestamp NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
UNIQUE KEY `id` (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=7 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
该表里的version_id
字段,就是在sql文件的日期。is_applied
字段是指该文件是否已执行。
当重复运行up
命令时,首先会检查goose_db_version
表中最近成功运行的版本,然后再从dir目录下找到该版本的下一个版本的sql文件并执行。这样就避免了之前运行过的sql文件被重复执行。
up-to
子命令后面必须要跟一个VERSION
参数,即指定具体的sql的版本。该命令会根据指定的版本号,从--dir
指定的目录下查找对应的sql文件来执行。VERSION
指定的版本就是sql文件名前面的数字部分。
down
子命令是对up
子命令的回退操作。即从--dir指定的目录中读取sql文件,然后读取sql文件中的标识为-- +goose Down
指令的内容。
这里需要注意的是,在sql文件中,-- +goose Down
的内容必须是和文件中的 -- +goose Up
内容配对出现的,即有向前执行的内容,才会有对应的回退的内容。
down-to
子命令后面也必须跟一个VERSION
版本号,标识回退到对应的版本。即从--dir
指定的目录中读取特定版本的sql文件中的down
的部分。
redo
子命令是将最近执行的一个版本先回退,再重新执行该版本。即先从goose_db_version
表中查找中最近执行过的一个版本的sql文件,然后执行该文件的回退操作,再执行up
操作。
例如,我们刚执行过sql文件 00001_create_users_table.sql,其内容:
-- +goose Up
CREATE TABLE users (
id int NOT NULL PRIMARY KEY,
username text,
name text,
surname text
);INSERT INTO users VALUES
(0, 'root', '', ''),
(1, 'vojtechvitek', 'Vojtech', 'Vitek');
-- +goose Down
DROP TABLE users;
如果执行redo
操作,则是先执行该文件中的goose Down
部分,再执行该文件中的 goose Up
部分的内容。
reset
子命令是重置操作,即将所有sql文件中的goose Down
的部分重新执行一遍。
本文介绍了goose工具的工作流程及原理。同时介绍了使用的sql文件模版中的指令。最后还介绍了对应的子命令的作用及如何执行sql文件中的内容的。若想进一步了解,可读读源代码。
推荐阅读