Go Migrate Tutorial

1. Übersicht von Go Migrate

Go Migrate ist ein Tool zur Verwaltung von Datenbankmigrationen, das in der Go-Sprache geschrieben ist. Es kann als Befehlszeilenschnittstelle (CLI) oder als Bibliothek für Go-Projekte importiert werden. Go Migrate kann Migrationsdateien aus verschiedenen Quellen lesen und in richtiger Reihenfolge auf die Datenbank anwenden. Es unterstützt verschiedene Datenbanktreiber und Migrationsquellen.

2. Versionen

Go Migrate unterstützt mehrere Versionen, darunter:

  • Master: Die neueste Version, einschließlich neuer Funktionen und Fehlerbehebungen
  • v4: Stabile Version, geeignet für Produktionsumgebungen
  • v3: Nicht mehr unterstützt und sollte nicht verwendet werden

3. Installation

Um Go Migrate zu verwenden, müssen Sie das Go-Paket installieren. Führen Sie den folgenden Befehl zur Installation aus:

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

3. Verwendung von Go Migrate

Go Migrate kann über die CLI oder als Bibliothek im Go-Projekt verwendet werden.

3.0. Datenbankverbindungs-URLs

Unabhängig davon, ob die CLI oder Go-Code verwendet wird, müssen Datenbank-URLs für die Verbindung mit der Datenbank konfiguriert werden.

URL-Format:

dbtreiber://benutzername:passwort@host:port/dbname?param1=true&param2=false

Diese URL ist eine Datenbankverbindungs-URL, die zur Verbindung mit der Datenbank und zur Angabe von Verbindungsparametern verwendet wird. Hier ist eine Erklärung für jeden Teil:

  1. dbtreiber://: Dies ist der Protokollbezeichner des Datenbanktreibers, der verwendet wird, um den zu verwendenden Datenbanktreiber anzugeben, z. B. MySQL.
  2. benutzername:passwort: Dies ist der Benutzername und das Passwort, die zur Authentifizierung verwendet werden. In der Regel werden der Benutzername und das Passwort durch einen Doppelpunkt (:) getrennt.
  3. @: Dieses Symbol wird verwendet, um den Benutzernamen und das Passwort vom Hostnamen und der Portnummer zu trennen.
  4. host:port: Dies ist der Hostname und die Portnummer des Datenbankservers. Der Hostname ist die IP-Adresse oder der Domainname des Datenbankservers, und die Portnummer ist der Port, auf dem der Datenbankserver lauscht.
  5. /dbname: Dies ist der Name der Datenbank, mit der eine Verbindung hergestellt werden soll.
  6. ?param1=true&param2=false: Dieser Teil sind Abfrageparameter, die zur Angabe zusätzlicher Verbindungsparameter verwendet werden. In diesem Beispiel gibt es zwei Parameter.

Diese Abfrageparameter können entsprechend den spezifischen Anforderungen des Datenbanktreibers und des Datenbankservers eingestellt werden, um spezifische Attribute oder Verhaltensweisen der Verbindung zu konfigurieren.

Postgres-Verbindungsparameter

postgres://postgres:passwort@localhost:5432/beispiel?sslmode=disable

SQLite-Verbindungsparameter

sqlite3://pfad/zur/datenbank?abfrage

MongoDB-Verbindungsparameter

mongodb://benutzer:passwort@host:port/dbname?abfrage

3.1 CLI-Verwendung

3.1.1 Grundlegende Verwendung

Um die CLI zu verwenden, führen Sie den folgenden Befehl aus:

migrate -source file://pfad/zur/migration -database postgres://localhost:5432/datenbank up 2

Dieser Befehl wendet Migrationen aus der angegebenen Quelle auf die angegebene Datenbank an. Die Zahl "2" gibt die Anzahl der anzuwendenden Migrationen an.

3.1.2 Docker-Verwendung

Go Migrate kann auch mit Docker verwendet werden. Führen Sie den folgenden Befehl aus:

docker run -v {{ migratordir }}:/migrations --network host migrate/migrate -path=/migrations/ -database postgres://localhost:5432/datenbank up 2

Dieser Befehl führt Go Migrate in einem Docker-Container aus und wendet Migrationen aus der angegebenen Quelle auf die angegebene Datenbank an.

3.2 Verwendung in Ihrem Go-Projekt

Um Go Migrate in Ihrem Go-Projekt zu verwenden, müssen Sie die erforderlichen Pakete und Bibliotheken importieren. Hier ist ein Beispiel:

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

Dieser Code initialisiert Go Migrate mit der angegebenen Quelle und Datenbank und wendet dann 2 Migrationen mit der Steps-Methode an.

Wenn Sie einen vorhandenen Datenbankclient verwenden möchten, beziehen Sie sich bitte auf das folgende Beispiel:

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

Dieser Code importiert die erforderlichen Pakete und initialisiert den Datenbankclient mit dem sql-Paket. Anschließend wird eine neue Go Migrate-Instanz mit der Methode NewWithDatabaseInstance erstellt, wobei die Quelle und der Datenbanktreiber angegeben werden. Schließlich wird die Migration mit der Up-Methode durchgeführt.

4. Unterstützte Datenbanktreiber

Go Migrate unterstützt mehrere Datenbanktreiber, darunter:

  • 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. Unterstützte Migrationsquellen

Go Migrate unterstützt mehrere Migrationsquellen, darunter:

  • Dateisystem: Lesen Sie Migrationen aus dem lokalen Dateisystem.
  • io/fs: Lesen Sie Migrationen unter Verwendung des Go-Pakets io/fs.
  • Go-Bindata: Lesen Sie Migrationen aus eingebetteten Binärdaten mit dem Paket jteeuwen/go-bindata.
  • pkger: Lesen Sie Migrationen aus eingebetteten Binärdaten mit dem Paket markbates/pkger.
  • GitHub: Lesen Sie Migrationen aus einem entfernten GitHub-Repository.
  • GitHub Enterprise: Lesen Sie Migrationen aus einem entfernten GitHub Enterprise-Repository.
  • Bitbucket: Lesen Sie Migrationen aus einem entfernten Bitbucket-Repository.
  • Gitlab: Lesen Sie Migrationen aus einem entfernten Gitlab-Repository.
  • AWS S3: Lesen Sie Migrationen von Amazon Web Services S3.
  • Google Cloud Storage: Lesen Sie Migrationen von Google Cloud Platform Storage.

Je nach Anforderungen Ihres Projekts können Sie die Datenbankmigrationsdateien in den oben genannten unterstützten Dateispeicherquellen speichern.

6. Migrationsdateien

Migrationsdateien in Go Migrate haben bestimmte Dateinamen- und Inhaltsformate.

6.1 Format des Migrationsdateinamens

Jede Migration besteht aus einer "up"-Migrationsdatei und einer entsprechenden "down"-Migrationsdatei. Die Migrationsdateinamen sollten dem folgenden Format entsprechen:

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

version ist eine eindeutige Nummer, die die Reihenfolge angibt, in der die Migrationen angewendet werden sollen. title ist eine optionale Beschreibung der Migration. extension hängt vom verwendeten Datenbanksystem ab (z. B. für SQL-Varianten verwenden Sie .sql).

6.2 Format des Migrationsinhalts

Der Inhalt der Migrationsdateien variiert je nach Datenbanksystem, in der Regel beinhaltet er das direkte Schreiben von SQL-Anweisungen.

Beispielsweise sehen die folgenden zwei Migrationsdateien so aus:

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

Migrationsdatei 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
);

Migrationsdatei 000001_create_users_table.down.sql, die Down-Datei wird hauptsächlich verwendet, um die vorherigen Operationen rückgängig zu machen, normalerweise für Rollback-Zwecke.

DROP TABLE IF EXISTS users;

6.3 Umkehrbarkeit der Migration

Die Erstellung von umkehrbaren Migrationen gilt als bewährte Praxis. Dies bedeutet, dass die "aufwärts" und "abwärts" Migrationen auf jede Version angewendet werden können, um den Datenbankzustand effektiv neu zu erstellen und aufzuräumen.

Um die Umkehrbarkeit zu gewährleisten, sollte jede Migration eine entsprechende "aufwärts" und "abwärts" Migrationsdatei haben. Die "aufwärts" Migrationsdatei enthält die Operationen zur Anwendung der Migration, während die "abwärts" Migrationsdatei die Operationen zur Aufhebung der Migration enthält.

7. Verwendung von MySQL

Go Migrate bietet Unterstützung für MySQL-Datenbanken. Um eine Verbindung zu einer MySQL-Datenbank herzustellen, muss die Datenbank-URL im folgenden Format vorliegen:

mysql://benutzer:passwort@tcp(host:port)/dbname?abfrage

Die URL kann Abfrageparameter wie den Migrationsnamen oder TLS-Parameter enthalten. Für eine vollständige Liste der Abfrageparameter siehe die Go Migrate MySQL-Dokumentation.

7.1 URL-Abfrageparameter

  • x-migrations-table: Der Name der Migrations-Tabelle.
  • x-no-lock: Auf true setzen, um die GET_LOCK/RELEASE_LOCK-Anweisungen zu überspringen. Nützlich für Multi-Master-MySQL-Versionen.
  • x-statement-timeout: Bricht jede Anweisung ab, die die angegebene Anzahl von Millisekunden überschreitet.
  • dbname: Der Name der Datenbank, mit der verbunden werden soll.
  • user: Der Benutzer, als den man sich anmelden will.
  • password: Das Passwort des Benutzers.
  • host: Der Host, zu dem eine Verbindung hergestellt werden soll.
  • port: Der Port, an den gebunden werden soll.
  • tls: TLS/SSL-Verschlüsselungsverbindungseinstellungen.
  • x-tls-ca: Der Speicherort der CA (Certificate Authority)-Datei.
  • x-tls-cert: Der Speicherort der Clientzertifikatsdatei.
  • x-tls-key: Der Speicherort der Datei des privaten Schlüssels.
  • x-tls-insecure-skip-verify: Ob SSL verwendet werden soll.

7.2 Verwendung mit vorhandenen Clients

Wenn Sie Go Migrate mit einem vorhandenen MySQL-Client verwenden möchten, stellen Sie sicher, dass Sie den Parameter multiStatements=true bei der Erstellung des Clients verwenden. Hier ist ein Beispiel:

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

Dieser Code importiert die benötigten Pakete, erstellt einen MySQL-Datenbankclient und initialisiert Go Migrate mit der Datenbankinstanz. Anschließend werden zwei Migrationen mit der Methode Steps durchgeführt.