Руководство по использованию инструмента Go Migrate

1. Обзор Go Migrate

Go Migrate - это инструмент для управления миграциями базы данных, написанный на языке Go. Он может использоваться как интерфейс командной строки (CLI), так и импортироваться в качестве библиотеки для проектов Go. Go Migrate может считывать файлы миграции из различных источников и применять их к базе данных в правильном порядке. Он поддерживает различные драйверы баз данных и источники миграции.

2. Версии

Go Migrate поддерживает несколько версий, включая:

  • Master: Последняя версия, включающая в себя новые функции и исправления ошибок
  • v4: Стабильная версия, подходящая для промышленного использования
  • v3: Больше не поддерживается и не должна использоваться

3. Установка

Чтобы использовать Go Migrate, необходимо установить пакет Go. Запустите следующую команду для установки:

go get -u -d github.com/golang-migrate/migrate/v4
cd $GOPATH/src/github.com/golang-migrate/migrate/v4

3. Использование Go Migrate

Go Migrate можно использовать через CLI или как библиотеку в проекте Go.

3.0. URL подключения к базе данных

При использовании как CLI, так и кода Go, необходимо сконфигурировать URL-адреса базы данных для подключения к базе данных.

Формат URL:

dbdriver://username:password@host:port/dbname?param1=true&param2=false

Этот URL-адрес подключения к базе данных используется для подключения к базе данных и указания параметров подключения. Вот объяснение для каждой части:

  1. dbdriver://: Это идентификатор протокола для используемого драйвера базы данных, указывающий, какой драйвер базы данных использовать, например, mysql.
  2. username:password: Это имя пользователя и пароль, используемые для аутентификации. Обычно имя пользователя и пароль разделяются двоеточием (:).
  3. @: Этот символ используется для разделения имени пользователя и пароля от имени хоста и порта.
  4. host:port: Это имя хоста и номер порта сервера базы данных. Имя хоста - это IP-адрес или доменное имя сервера базы данных, а номер порта - это порт, на котором работает сервер базы данных.
  5. /dbname: Это имя базы данных для подключения.
  6. ?param1=true&param2=false: Эта часть - это параметры запроса, используемые для указания дополнительных параметров подключения. В этом примере есть два параметра.

Эти параметры запроса могут быть установлены в соответствии с конкретными требованиями драйвера базы данных и сервера базы данных для настройки конкретных атрибутов или поведения подключения.

Параметры подключения к Postgres

postgres://postgres:password@localhost:5432/example?sslmode=disable

Параметры подключения к SQLite

sqlite3://путь/к/базе?query

Параметры подключения к MongoDB

mongodb://user:password@host:port/dbname?query

3.1 Использование через CLI

3.1.1 Основное использование

Чтобы использовать CLI, выполните следующую команду:

migrate -source file://путь/к/миграциям -database postgres://localhost:5432/база up 2

Эта команда применяет миграции из указанного источника к указанной базе данных. Число "2" указывает количество применяемых миграций.

3.1.2 Использование с Docker

Go Migrate также может использоваться с Docker. Выполните следующую команду:

docker run -v {{ директория миграций }}:/миграции --network host migrate/migrate -path=/миграции/ -database postgres://localhost:5432/база up 2

Эта команда запускает Go Migrate в контейнере Docker и применяет миграции из указанного источника к указанной базе данных.

3.2 Использование в вашем проекте Go

Чтобы использовать Go Migrate в вашем проекте Go, вам нужно импортировать необходимые пакеты и библиотеки. Вот пример:

import (
    "github.com/golang-migrate/migrate/v4"
    _ "github.com/golang-migrate/migrate/v4/database/postgres"
    _ "github.com/golang-migrate/migrate/v4/source/github"
)

func main() {
    m, err := migrate.New(
        "github://mattes:personal-access-token@mattes/migrate_test",
        "postgres://localhost:5432/database?sslmode=enable")
    m.Steps(2)
}

Этот код инициализирует Go Migrate с указанным источником и базой данных, затем применяет 2 миграции, используя метод Steps.

Если вы хотите использовать существующий клиент базы данных, обратитесь к следующему примеру:

import (
    "database/sql"
    _ "github.com/lib/pq"
    "github.com/golang-migrate/migrate/v4"
    "github.com/golang-migrate/migrate/v4/database/postgres"
    _ "github.com/golang-migrate/migrate/v4/source/file"
)

func main() {
    db, err := sql.Open("postgres", "postgres://localhost:5432/database?sslmode=enable")
    driver, err := postgres.WithInstance(db, &postgres.Config{})
    m, err := migrate.NewWithDatabaseInstance(
        "file:///migrations",
        "postgres", driver)
    m.Up()
}

Этот код импортирует необходимые пакеты и инициализирует клиент базы данных с помощью пакета sql. Затем создается новый экземпляр Go Migrate с помощью метода NewWithDatabaseInstance, указывая источник и драйвер базы данных. Наконец, он применяет миграцию с помощью метода Up.

4. Поддерживаемые драйверы базы данных

Go Migrate поддерживает несколько драйверов базы данных, включая:

  • PostgreSQL
  • PGX v4
  • PGX v5
  • Redshift
  • Ql
  • Cassandra
  • SQLite
  • SQLite3
  • SQLCipher
  • MySQL/MariaDB
  • Neo4j
  • MongoDB
  • CrateDB
  • Shell
  • Google Cloud Spanner
  • CockroachDB
  • YugabyteDB
  • ClickHouse
  • Firebird
  • MS SQL Server

5. Поддерживаемые источники миграции

Go Migrate поддерживает несколько источников миграции, включая:

  • Файловая система: Чтение миграций из локальной файловой системы.
  • io/fs: Чтение миграций с использованием пакета Go io/fs.
  • Go-Bindata: Чтение миграций из встроенных двоичных данных с использованием пакета jteeuwen/go-bindata.
  • pkger: Чтение миграций из встроенных двоичных данных с использованием пакета markbates/pkger.
  • GitHub: Чтение миграций из удаленного репозитория GitHub.
  • GitHub Enterprise: Чтение миграций из удаленного репозитория GitHub Enterprise.
  • Bitbucket: Чтение миграций из удаленного репозитория Bitbucket.
  • Gitlab: Чтение миграций из удаленного репозитория Gitlab.
  • AWS S3: Чтение миграций из Amazon Web Services S3.
  • Google Cloud Storage: Чтение миграций из хранилища Google Cloud Platform.

В зависимости от требований вашего проекта, вы можете хранить файлы миграции базы данных в поддерживаемых источниках файлового хранения, упомянутых выше.

6. Файлы миграции

Файлы миграции в Go Migrate имеют определенный формат имени файла и содержания.

6.1 Формат имени файла миграции

Каждая миграция состоит из файла миграции "up" и соответствующего файла миграции "down". Имена файлов миграции должны соответствовать следующему формату:

{version}_{title}.up.{extension}
{version}_{title}.down.{extension}

version - уникальный номер, представляющий порядок применения миграций. title - необязательное описание миграции. extension зависит от используемой системы баз данных (например, для вариантов SQL используйте .sql).

6.2 Формат содержания миграции

Содержание файлов миграции зависит от системы баз данных, обычно включает прямую запись SQL.

Например, ниже приведены два файла миграции:

  • 000001_create_users_table.up.sql
  • 000001_create_users_table.down.sql

Файл миграции 000001_create_users_table.up.sql

CREATE TABLE IF NOT EXISTS users(
   user_id serial PRIMARY KEY,
   username VARCHAR (50) UNIQUE NOT NULL,
   password VARCHAR (50) NOT NULL,
   email VARCHAR (300) UNIQUE NOT NULL
);

Файл миграции 000001_create_users_table.down.sql, файл "down" в основном используется для отмены предыдущих операций, обычно для целей отката.

DROP TABLE IF EXISTS users;

6.3 Обратимость миграций

Написание обратимых миграций считается лучшей практикой. Это означает, что миграции вверх и вниз должны быть способны запускаться до любой версии, эффективно воссоздавая и убирая состояние базы данных.

Для обеспечения обратимости каждая миграция должна иметь соответствующие файлы "вверх" и "вниз". Файл "вверх" содержит операции для применения миграции, в то время как файл "вниз" содержит операции для отмены миграции.

7. Использование MySQL

Go Migrate предоставляет поддержку для баз данных MySQL. Для подключения к базе данных MySQL URL-адрес базы данных должен иметь следующий формат:

mysql://пользователь:пароль@tcp(хост:порт)/имя_базы_данных?запрос

URL-адрес может включать параметры запроса, такие как имя таблицы миграции, параметры TLS и т. д. Для полного списка параметров запроса, пожалуйста, обратитесь к документации Go Migrate для MySQL.

7.1 Параметры запроса URL

  • x-migrations-table: Имя таблицы миграции.
  • x-no-lock: Установите в true, чтобы пропустить операторы GET_LOCK/RELEASE_LOCK. Полезно для многомастерных версий MySQL.
  • x-statement-timeout: Прерывает любое заявление, которое превышает указанное количество миллисекунд.
  • dbname: Имя базы данных для подключения.
  • user: Имя пользователя для входа.
  • password: Пароль пользователя.
  • host: Хост для подключения.
  • port: Порт для привязки.
  • tls: Параметры соединения шифрования TLS/SSL.
  • x-tls-ca: Местоположение файла CA (Центр сертификации).
  • x-tls-cert: Местоположение файла клиентского сертификата.
  • x-tls-key: Местоположение файла закрытого ключа.
  • x-tls-insecure-skip-verify: Использовать или нет SSL.

7.2 Использование с существующими клиентами

Если вы планируете использовать Go Migrate с существующим клиентом MySQL, убедитесь, что при создании клиента используете параметр multiStatements=true. Вот пример:

package main

import (
    "database/sql"
    
    _ "github.com/go-sql-driver/mysql"
    "github.com/golang-migrate/migrate/v4"
    "github.com/golang-migrate/migrate/v4/database/mysql"
    _ "github.com/golang-migrate/migrate/v4/source/file"
)

func main() {
    db, _ := sql.Open("mysql", "пользователь:пароль@tcp(хост:порт)/имя_базы_данных?multiStatements=true")
    driver, _ := mysql.WithInstance(db, &mysql.Config{})
    m, _ := migrate.NewWithDatabaseInstance(
        "file:///migrations",
        "mysql", 
        driver,
    )
    
    m.Steps(2)
}

Этот код импортирует необходимые пакеты, создает клиент базы данных MySQL и инициализирует Go Migrate с экземпляром базы данных. Затем он применяет две миграции, используя метод Steps.