Tutorial de Go Migrate

1. Descripción general de Go Migrate

Go Migrate es una herramienta para gestionar la migración de bases de datos escrita en el lenguaje Go. Se puede utilizar como una interfaz de línea de comandos (CLI) o importarse como una biblioteca para proyectos en Go. Go Migrate puede leer archivos de migración desde diferentes fuentes y aplicarlos a la base de datos en el orden correcto. Admite varios controladores de bases de datos y fuentes de migración.

2. Versiones

Go Migrate admite múltiples versiones, que incluyen:

Master: La última versión, que incluye nuevas funciones y correcciones de errores.
v4: Versión estable, adecuada para entornos de producción.
v3: Ya no tiene soporte y no debería utilizarse.

3. Instalación

Para utilizar Go Migrate, es necesario instalar el paquete de Go. Ejecute el siguiente comando para la instalación:

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

3. Uso de Go Migrate

Go Migrate se puede utilizar a través de la CLI o como una biblioteca en el proyecto en Go.

3.0. URLs de Conexión a la Base de Datos

Ya sea que se utilice la CLI o el código en Go, es necesario configurar las URLs de las bases de datos para conectarse a la base de datos.

Formato de la URL:

dbdriver://usuario:contraseña@host:puerto/nombredb?param1=true&param2=false

Esta URL es una URL de conexión a la base de datos utilizada para conectarse a la base de datos y especificar los parámetros de conexión. A continuación se explica cada parte:

dbdriver://: Este es el identificador del protocolo para el controlador de la base de datos que se utilizará para especificar qué controlador de base de datos se usará, por ejemplo, mysql.
usuario:contraseña: Estos son el nombre de usuario y la contraseña utilizados para la autenticación. Por lo general, el nombre de usuario y la contraseña están separados por dos puntos (:).
@: Este símbolo se utiliza para separar el nombre de usuario y la contraseña del nombre del host y el puerto.
host:puerto: Este es el nombre del host y el número de puerto del servidor de base de datos. El nombre del host es la dirección IP o el nombre de dominio del servidor de base de datos, y el número de puerto es el puerto en el que el servidor de base de datos está escuchando.
/nombredb: Este es el nombre de la base de datos a la que se va a conectar.
?param1=true&param2=false: Esta parte son los parámetros de la consulta que se utilizan para especificar parámetros de conexión adicionales. En este ejemplo, hay dos parámetros.

Estos parámetros de consulta se pueden configurar según los requisitos específicos del controlador de base de datos y el servidor de base de datos para configurar atributos o comportamientos específicos de la conexión.

Parámetros de Conexión de Postgres

postgres://postgres:contraseña@localhost:5432/ejemplo?sslmode=disable

Parámetros de Conexión de SQLite

sqlite3://ruta/a/base_de_datos?consulta

Parámetros de Conexión de MongoDB

mongodb://usuario:contraseña@host:puerto/nombredb?consulta

3.1 Uso de la CLI

3.1.1 Uso Básico

Para utilizar la CLI, ejecute el siguiente comando:

migrate -source file://ruta/a/migraciones -database postgres://localhost:5432/base_de_datos up 2

Este comando aplica migraciones desde la fuente especificada a la base de datos dada. El número "2" indica la cantidad de migraciones que se aplicarán.

3.1.2 Uso de Docker

Go Migrate también se puede utilizar con Docker. Ejecute el siguiente comando:

docker run -v {{ directorio_de_migraciones }}:/migraciones --network host migrate/migrate -path=/migraciones/ -database postgres://localhost:5432/base_de_datos up 2

Este comando ejecuta Go Migrate en un contenedor de Docker y aplica migraciones desde la fuente especificada a la base de datos dada.

3.2 Uso en tu Proyecto Go

Para usar Go Migrate en tu proyecto Go, es necesario importar los paquetes y bibliotecas requeridos. Aquí tienes un ejemplo:

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

Este código inicializa Go Migrate con la fuente y la base de datos especificadas, y luego aplica 2 migraciones usando el método Steps.

Si deseas utilizar un cliente de base de datos existente, por favor consulta el siguiente ejemplo:

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

Este código importa los paquetes necesarios e inicializa el cliente de la base de datos con el paquete sql. Luego crea una nueva instancia de Go Migrate utilizando el método NewWithDatabaseInstance, especificando la fuente y el controlador de la base de datos. Finalmente, aplica la migración usando el método Up.

4. Controladores de Base de Datos Compatibles

Go Migrate admite múltiples controladores de bases de datos, incluyendo:

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. Fuentes de Migración Compatibles

Go Migrate admite múltiples fuentes de migración, incluyendo:

Sistema de Archivos: Lee migraciones desde el sistema de archivos local.
io/fs: Lee migraciones usando el paquete io/fs de Go.
Go-Bindata: Lee migraciones desde datos binarios incrustados utilizando el paquete jteeuwen/go-bindata.
pkger: Lee migraciones desde datos binarios incrustados utilizando el paquete markbates/pkger.
GitHub: Lee migraciones desde un repositorio remoto de GitHub.
GitHub Enterprise: Lee migraciones desde un repositorio remoto de GitHub Enterprise.
Bitbucket: Lee migraciones desde un repositorio remoto de Bitbucket.
Gitlab: Lee migraciones desde un repositorio remoto de Gitlab.
AWS S3: Lee migraciones desde Amazon Web Services S3.
Almacenamiento de Google Cloud: Lee migraciones desde Google Cloud Platform Storage.

Dependiendo de los requisitos de tu proyecto, puedes almacenar los archivos de migración de la base de datos en las fuentes de almacenamiento de archivos admitidas mencionadas anteriormente.

6. Archivos de Migración

Los archivos de migración en Go Migrate tienen formatos específicos de nombre y contenido.

6.1 Formato del Nombre del Archivo de Migración

Cada migración consta de un archivo de migración "up" y un archivo de migración "down" correspondiente. Los nombres de los archivos de migración deben cumplir con el siguiente formato:

{versión}_{título}.up.{extensión}
{versión}_{título}.down.{extensión}

versión es un número único que representa el orden en el que se deben aplicar las migraciones. título es una descripción opcional de la migración. extensión depende del sistema de base de datos que se esté utilizando (por ejemplo, para variantes SQL, usa .sql).

6.2 Formato del Contenido del Archivo de Migración

El contenido de los archivos de migración varía según el sistema de base de datos, generalmente implica escribir SQL directamente.

Por ejemplo, los siguientes son dos archivos de migración:

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

Archivo de migración 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
);

Archivo de migración 000001_create_users_table.down.sql, el archivo "down" se utiliza principalmente para deshacer las operaciones anteriores, típicamente con propósitos de reversión.

DROP TABLE IF EXISTS users;

6.3 Reversibilidad de la migración

Escribir migraciones reversibles se considera una buena práctica. Esto significa que las migraciones hacia arriba (up) y hacia abajo (down) deben poder ejecutarse en cualquier versión, recreando y limpiando efectivamente el estado de la base de datos.

Para garantizar la reversibilidad, cada migración debe tener un archivo correspondiente de migración "up" y "down". El archivo de migración "up" contiene las operaciones para aplicar la migración, mientras que el archivo de migración "down" contiene las operaciones para deshacer la migración.

7. Uso de MySQL

Go Migrate ofrece soporte para bases de datos MySQL. Para conectarse a una base de datos MySQL, la URL de la base de datos debe tener el siguiente formato:

mysql://usuario:contraseña@tcp(host:puerto)/nombredb?consulta

La URL puede incluir parámetros de consulta, como el nombre de la tabla de migración, parámetros TLS, etc. Para ver una lista completa de parámetros de consulta, consulte la documentación de Go Migrate MySQL.

7.1 Parámetros de consulta de URL

x-migrations-table: El nombre de la tabla de migración.
x-no-lock: Establezca en true para omitir las declaraciones GET_LOCK/RELEASE_LOCK. Útil para versiones multi-master de MySQL.
x-statement-timeout: Aborta cualquier declaración que exceda el número especificado de milisegundos.
nombredb: El nombre de la base de datos a la que conectarse.
usuario: El usuario con el que iniciar sesión.
contraseña: La contraseña del usuario.
host: El host al que conectarse.
puerto: El puerto al que enlazar.
tls: Parámetros de conexión de cifrado TLS/SSL.
x-tls-ca: La ubicación del archivo de la autoridad de certificación (CA).
x-tls-cert: La ubicación del archivo de certificado del cliente.
x-tls-key: La ubicación del archivo de clave privada.
x-tls-insecure-skip-verify: Si se debe utilizar SSL.

7.2 Uso con clientes existentes

Si tiene la intención de utilizar Go Migrate con un cliente MySQL existente, asegúrese de utilizar el parámetro multiStatements=true al crear el cliente. Aquí hay un ejemplo:

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", "usuario:contraseña@tcp(host:puerto)/nombredb?multiStatements=true")
    driver, _ := mysql.WithInstance(db, &mysql.Config{})
    m, _ := migrate.NewWithDatabaseInstance(
        "file:///migrations",
        "mysql", 
        driver,
    )
    
    m.Steps(2)
}

Este código importa los paquetes necesarios, crea un cliente de base de datos MySQL e inicializa Go Migrate con la instancia de base de datos. Luego aplica dos migraciones utilizando el método Steps.

Gestión de Versiones de Bases de Datos con Go Migrate