Samouczek Go Migrate

1. Przegląd Go Migrate

Go Migrate to narzędzie do zarządzania migracjami bazy danych napisane w języku Go. Może być używane jako interfejs wiersza poleceń (CLI) lub importowane jako biblioteka do projektów w Go. Go Migrate może odczytywać pliki migracyjne z różnych źródeł i zastosowywać je do bazy danych we właściwej kolejności. Obsługuje różne sterowniki baz danych i źródła migracji.

2. Wersje

Go Migrate obsługuje kilka wersji, w tym:

  • Master: Najnowsza wersja, zawierająca nowe funkcje i poprawki błędów
  • v4: Stabilna wersja, odpowiednia do środowisk produkcyjnych
  • v3: Nie jest już obsługiwana i nie powinna być używana

3. Instalacja

Aby używać Go Migrate, musisz zainstalować pakiet Go. Uruchom poniższą komendę, aby zainstalować:

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

3. Korzystanie z Go Migrate

Go Migrate można używać za pomocą interfejsu wiersza poleceń lub jako bibliotekę w projekcie Go.

3.0. Adresy URL połączenia z bazą danych

Niezależnie od tego, czy używasz interfejsu wiersza poleceń czy kodu Go, adresy URL baz danych muszą być skonfigurowane, aby połączyć się z bazą danych.

Format URL:

dbdriver://nazwa_użytkownika:hasło@host:port/nazwa_bazy_danych?parametr1=true&parametr2=false

Ten URL jest używany do połączenia z bazą danych i określenia parametrów połączenia. Oto wyjaśnienie każdej części:

  1. dbdriver://: To identyfikator protokołu dla sterownika bazy danych, który określa, który sterownik bazy danych należy użyć, np. mysql.
  2. nazwa_użytkownika:hasło: To nazwa użytkownika i hasło używane do uwierzytelniania. Zazwyczaj nazwa użytkownika i hasło są oddzielone dwukropkiem (:).
  3. @: Ten symbol służy do oddzielenia nazwy użytkownika i hasła od nazwy hosta i portu.
  4. host:port: To nazwa hosta i numer portu serwera bazy danych. Nazwa hosta to adres IP lub nazwa domenowa serwera bazy danych, a numer portu to port, na którym serwer bazy danych nasłuchuje.
  5. /nazwa_bazy_danych: To nazwa bazy danych, do której należy się połączyć.
  6. ?parametr1=true&parametr2=false: Ta część to parametry zapytania używane do określenia dodatkowych parametrów połączenia. W tym przykładzie są dwa parametry.

Te parametry zapytania mogą być ustawiane zgodnie z konkretnymi wymaganiami sterownika bazy danych i serwera baz danych, aby skonfigurować określone atrybuty lub zachowania połączenia.

Parametry połączenia z Postgresem

postgres://postgres:hasło@localhost:5432/przykład?sslmode=disable

Parametry połączenia z SQLite

sqlite3://ścieżka/do/bazy/danych?zapytanie

Parametry połączenia z MongoDB

mongodb://użytkownik:hasło@host:port/nazwa_bazy_danych?zapytanie

3.1 Użycie interfejsu wiersza poleceń

3.1.1 Podstawowe użycie

Aby użyć interfejsu wiersza poleceń, wykonaj poniższą komendę:

migrate -source file://ścieżka/do/migracji -database postgres://localhost:5432/baza_danych up 2

Ta komenda stosuje migracje z określonego źródła do podanej bazy danych. Liczba "2" oznacza liczbę migracji do zastosowania.

3.1.2 Użycie Dockera

Go Migrate można także używać z pomocą Dockera. Uruchom poniższą komendę:

docker run -v {{ katalog_migracji }}:/migracje --network host migrate/migrate -ścieżka=/migracje/ -database postgres://localhost:5432/baza_danych up 2

Ta komenda uruchamia Go Migrate w kontenerze Dockera i stosuje migracje z określonego źródła do podanej bazy danych.

3.2 Korzystanie w projekcie Go

Aby użyć Go Migrate w swoim projekcie Go, musisz zaimportować wymagane pakiety i biblioteki. Oto przykład:

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)
}

Ten kod inicjuje Go Migrate z określonym źródłem i bazą danych, a następnie stosuje 2 migracje, korzystając z metody Steps.

Jeśli chcesz korzystać z istniejącego klienta bazy danych, proszę odnieść się do poniższego przykładu:

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()
}

Ten kod importuje wymagane pakiety, inicjuje klienta bazy danych za pomocą pakietu sql. Następnie tworzy nową instancję Go Migrate, używając metody NewWithDatabaseInstance, określając źródło i sterownik bazy danych. Na koniec stosuje migrację za pomocą metody Up.

4. Obsługiwane sterowniki bazy danych

Go Migrate obsługuje wiele sterowników baz danych, w tym:

  • 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. Obsługiwane źródła migracji

Go Migrate obsługuje wiele źródeł migracji, w tym:

  • System plików: Odczytuje migracje z lokalnego systemu plików.
  • io/fs: Odczytuje migracje za pomocą pakietu Go io/fs.
  • Go-Bindata: Odczytuje migracje z osadzonych danych binarnych za pomocą pakietu jteeuwen/go-bindata.
  • pkger: Odczytuje migracje z osadzonych danych binarnych za pomocą pakietu markbates/pkger.
  • GitHub: Odczytuje migracje z zdalnego repozytorium GitHub.
  • GitHub Enterprise: Odczytuje migracje z repozytorium GitHub Enterprise.
  • Bitbucket: Odczytuje migracje z zdalnego repozytorium Bitbucket.
  • Gitlab: Odczytuje migracje z zdalnego repozytorium Gitlab.
  • AWS S3: Odczytuje migracje z usługi Amazon Web Services S3.
  • Google Cloud Storage: Odczytuje migracje z usługi Google Cloud Platform Storage.

W zależności od wymagań projektu, możesz przechowywać pliki migracji bazy danych w wspieranych źródłach przechowywania plików wymienionych powyżej.

6. Pliki migracji

Pliki migracji w Go Migrate mają określony format nazwy pliku i treść.

6.1 Format nazwy pliku migracji

Każda migracja składa się z pliku migracji "up" oraz odpowiadającego mu pliku migracji "down". Nazwy plików migracji powinny być zgodne z następującym formatem:

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

version to unikalny numer reprezentujący kolejność, w jakiej migracje powinny być stosowane. title to opcjonalny opis migracji. extension zależy od używanego systemu baz danych (np. dla wariantów SQL, użyj .sql).

6.2 Format treści migracji

Zawartość plików migracji różni się w zależności od systemu baz danych, zazwyczaj polega na bezpośrednim pisaniu SQL.

Na przykład, poniżej znajdują się dwa pliki migracji:

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

Plik migracji 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
);

Plik migracji 000001_create_users_table.down.sql, plik „down” służy głównie do cofania poprzednich operacji, zazwyczaj w celu cofnięcia zmian.

DROP TABLE IF EXISTS users;

6.3 Odwracalność migracji

Pisanie odwracalnych migracji uważane jest za najlepsze praktyki. Oznacza to, że migracje "do góry" i "do dołu" powinny być w stanie uruchomić się do dowolnej wersji, skutecznie odtwarzając i sprzątając stan bazy danych.

Aby zapewnić odwracalność, każda migracja powinna mieć odpowiadający plik migracji "do góry" i "do dołu". Plik migracji "do góry" zawiera operacje do zastosowania migracji, podczas gdy plik migracji "do dołu" zawiera operacje do cofnięcia migracji.

7. Użycie MySQL

Go Migrate zapewnia obsługę baz danych MySQL. Aby połączyć się z bazą danych MySQL, adres URL bazy danych musi mieć następujący format:

mysql://user:password@tcp(host:port)/dbname?query

Adres URL może zawierać parametry zapytania, takie jak nazwa tabeli migracji, parametry TLS, itp. Aby uzyskać pełną listę parametrów zapytania, prosimy odwołać się do dokumentacji Go Migrate MySQL.

7.1 Parametry zapytania URL

  • x-migrations-table: Nazwa tabeli migracji.
  • x-no-lock: Ustawienie na true, aby pominąć instrukcje GET_LOCK/RELEASE_LOCK. Przydatne dla wersji multi-master MySQL.
  • x-statement-timeout: Przerwać każdą instrukcję, która przekracza określoną liczbę milisekund.
  • dbname: Nazwa bazy danych do połączenia.
  • user: Użytkownik do zalogowania się.
  • password: Hasło użytkownika.
  • host: Host do połączenia.
  • port: Port do połączenia.
  • tls: Parametry połączenia szyfrowania TLS/SSL.
  • x-tls-ca: Lokalizacja pliku CA (Certificate Authority).
  • x-tls-cert: Lokalizacja pliku certyfikatu klienta.
  • x-tls-key: Lokalizacja pliku klucza prywatnego.
  • x-tls-insecure-skip-verify: Czy używać SSL.

7.2 Użycie z istniejącymi klientami

Jeśli zamierzasz użyć Go Migrate z istniejącym klientem MySQL, upewnij się, że używasz parametru multiStatements=true podczas tworzenia klienta. Oto przykład:

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", "user:password@tcp(host:port)/dbname?multiStatements=true")
    driver, _ := mysql.WithInstance(db, &mysql.Config{})
    m, _ := migrate.NewWithDatabaseInstance(
        "file:///migrations",
        "mysql", 
        driver,
    )
    
    m.Steps(2)
}

Ten kod importuje wymagane pakiety, tworzy klienta bazy danych MySQL, inicjalizuje Go Migrate z instancją bazy danych, a następnie stosuje dwie migracje za pomocą metody Steps.