Tutoriel Go Migrate

1. Aperçu de Go Migrate

Go Migrate est un outil de gestion de migration de base de données écrit en langage Go. Il peut être utilisé en tant qu'interface en ligne de commande (CLI) ou importé en tant que bibliothèque pour des projets Go. Go Migrate peut lire des fichiers de migration à partir de différentes sources et les appliquer à la base de données dans le bon ordre. Il prend en charge divers pilotes de base de données et sources de migration.

2. Versions

Go Migrate prend en charge plusieurs versions, notamment :

Master : La dernière version, comprenant de nouvelles fonctionnalités et des corrections de bogues
v4 : Version stable, adaptée aux environnements de production
v3 : Plus pris en charge et ne devrait pas être utilisé

3. Installation

Pour utiliser Go Migrate, vous devez installer le package Go. Exécutez la commande suivante pour l'installation :

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

3. Utilisation de Go Migrate

Go Migrate peut être utilisé via l'interface en ligne de commande ou en tant que bibliothèque dans le projet Go.

3.0. URL de connexion à la base de données

Que ce soit en utilisant l'interface en ligne de commande ou le code Go, les URL de base de données doivent être configurées pour se connecter à la base de données.

Format de l'URL :

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

Cette URL est une URL de connexion à la base de données utilisée pour se connecter à la base de données et spécifier les paramètres de connexion. Voici une explication pour chaque partie :

dbdriver:// : C'est l'identifiant de protocole du pilote de base de données utilisé pour spécifier quel pilote de base de données à utiliser, par exemple, mysql.
username:password : C'est le nom d'utilisateur et le mot de passe utilisés pour l'authentification. En général, le nom d'utilisateur et le mot de passe sont séparés par un deux-points (:).
@ : Ce symbole est utilisé pour séparer le nom d'utilisateur et le mot de passe du nom d'hôte et du port.
host:port : C'est le nom d'hôte et le numéro de port du serveur de base de données. Le nom d'hôte est l'adresse IP ou le nom de domaine du serveur de base de données, et le numéro de port est le port sur lequel le serveur de base de données écoute.
/dbname : C'est le nom de la base de données à laquelle se connecter.
?param1=true&param2=false : Cette partie sont les paramètres de requête utilisés pour spécifier des paramètres de connexion supplémentaires. Dans cet exemple, il y a deux paramètres.

Ces paramètres de requête peuvent être définis en fonction des exigences spécifiques du pilote de base de données et du serveur de base de données pour configurer des attributs ou comportements spécifiques de la connexion.

Paramètres de connexion Postgres

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

Paramètres de connexion SQLite

sqlite3://chemin/vers/base_de_données?query

Paramètres de connexion MongoDB

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

3.1 Utilisation de l'interface en ligne de commande (CLI)

3.1.1 Utilisation de base

Pour utiliser l'interface en ligne de commande, exécutez la commande suivante :

migrate -source file://chemin/vers/migrations -database postgres://localhost:5432/base_de_données up 2

Cette commande applique les migrations de la source spécifiée à la base de données donnée. Le nombre "2" indique le nombre de migrations à appliquer.

3.1.2 Utilisation de Docker

Go Migrate peut également être utilisé avec Docker. Exécutez la commande suivante :

docker run -v {{ répertoire_de_migration }}:/migrations --network host migrate/migrate -path=/migrations/ -database postgres://localhost:5432/base_de_données up 2

Cette commande exécute Go Migrate dans un conteneur Docker et applique les migrations de la source spécifiée à la base de données donnée.

3.2 Utilisation dans votre projet Go

Pour utiliser Go Migrate dans votre projet Go, vous devez importer les packages et bibliothèques nécessaires. Voici un exemple :

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

Ce code initialise Go Migrate avec la source et la base de données spécifiées, puis applique 2 migrations à l'aide de la méthode Steps.

Si vous souhaitez utiliser un client de base de données existant, veuillez vous référer à l'exemple suivant :

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

Ce code importe les packages nécessaires et initialise le client de base de données avec le package sql. Ensuite, il crée une nouvelle instance Go Migrate à l'aide de la méthode NewWithDatabaseInstance, en spécifiant la source et le pilote de la base de données. Enfin, il applique la migration à l'aide de la méthode Up.

4. Pilotes de base de données pris en charge

Go Migrate prend en charge plusieurs pilotes de base de données, notamment :

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. Sources de migration prises en charge

Go Migrate prend en charge plusieurs sources de migration, notamment :

Système de fichiers : Lire les migrations depuis le système de fichiers local.
io/fs : Lire les migrations en utilisant le package Go io/fs.
Go-Bindata : Lire les migrations à partir de données binaires intégrées en utilisant le package jteeuwen/go-bindata.
pkger : Lire les migrations à partir de données binaires intégrées en utilisant le package markbates/pkger.
GitHub : Lire les migrations depuis un dépôt distant GitHub.
GitHub Enterprise : Lire les migrations depuis un dépôt distant GitHub Enterprise.
Bitbucket : Lire les migrations depuis un dépôt distant Bitbucket.
Gitlab : Lire les migrations depuis un dépôt distant Gitlab.
AWS S3 : Lire les migrations depuis Amazon Web Services S3.
Google Cloud Storage : Lire les migrations depuis le stockage Google Cloud Platform.

Selon les besoins de votre projet, vous pouvez stocker les fichiers de migration de base de données dans les sources de stockage de fichiers prises en charge mentionnées ci-dessus.

6. Fichiers de migration

Les fichiers de migration dans Go Migrate ont des formats de nom de fichier et de contenu spécifiques.

6.1 Format du nom de fichier de migration

Chaque migration se compose d'un fichier de migration "up" et d'un fichier de migration "down" correspondant. Les noms de fichier de migration doivent respecter le format suivant :

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

version est un nombre unique représentant l'ordre dans lequel les migrations doivent être appliquées. titre est une description facultative de la migration. extension dépend du système de base de données utilisé (par exemple, pour les variantes SQL, utilisez .sql).

6.2 Format du contenu de la migration

Le contenu des fichiers de migration varie en fonction du système de base de données, il implique généralement l'écriture directe de SQL.

Par exemple, voici deux fichiers de migration :

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

Fichier de migration 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
);

Fichier de migration 000001_create_users_table.down.sql, le fichier "down" est principalement utilisé pour annuler les opérations précédentes, généralement à des fins de retour arrière.

DROP TABLE IF EXISTS users;

6.3 Réversibilité de la migration

Il est recommandé d'écrire des migrations réversibles. Cela signifie que les migrations "up" et "down" doivent être capables de s'exécuter pour n'importe quelle version, recréant ainsi et nettoyant efficacement l'état de la base de données.

Pour assurer la réversibilité, chaque migration doit avoir un fichier de migration "up" et "down" correspondant. Le fichier de migration "up" contient les opérations à appliquer lors de la migration, tandis que le fichier de migration "down" contient les opérations pour annuler la migration.

7. Utilisation de MySQL

Go Migrate prend en charge les bases de données MySQL. Pour se connecter à une base de données MySQL, l'URL de la base de données doit être dans le format suivant :

mysql://utilisateur:motdepasse@tcp(hôte:port)/nombase?query

L'URL peut inclure des paramètres de requête, tels que le nom de la table de migration, les paramètres TLS, etc. Pour une liste complète des paramètres de requête, veuillez vous référer à la documentation Go Migrate MySQL.

7.1 Paramètres de requête d'URL

x-migrations-table : Le nom de la table de migration.
x-no-lock : Définir sur true pour ignorer les instructions GET_LOCK/RELEASE_LOCK. Utile pour les versions MySQL multi-maîtres.
x-statement-timeout : Interrompt toute instruction qui dépasse le nombre de millisecondes spécifié.
dbname : Le nom de la base de données à laquelle se connecter.
user : L'utilisateur à utiliser pour se connecter.
password : Le mot de passe de l'utilisateur.
host : L'hôte auquel se connecter.
port : Le port auquel se connecter.
tls : Paramètres de connexion cryptée TLS/SSL.
x-tls-ca : L'emplacement du fichier d'autorité de certification (CA).
x-tls-cert : L'emplacement du fichier de certificat client.
x-tls-key : L'emplacement du fichier de clé privée.
x-tls-insecure-skip-verify : Indique si SSL doit être utilisé.

7.2 Utilisation avec des clients existants

Si vous prévoyez d'utiliser Go Migrate avec un client MySQL existant, assurez-vous d'utiliser le paramètre multiStatements=true lors de la création du client. Voici un exemple :

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", "utilisateur:motdepasse@tcp(hôte:port)/nombase?multiStatements=true")
    driver, _ := mysql.WithInstance(db, &mysql.Config{})
    m, _ := migrate.NewWithDatabaseInstance(
        "file:///migrations",
        "mysql", 
        driver,
    )
    
    m.Steps(2)
}

Ce code importe les packages requis, crée un client de base de données MySQL, et initialise Go Migrate avec l'instance de base de données. Il applique ensuite deux migrations à l'aide de la méthode Steps.

Gestion de version de base de données avec Go Migrate