Migrações de banco de dados em Go (Golang): guia completo de ferramentas

Migrações de banco de dados em Go (Golang): como gerenciar o esquema de dados

Ao desenvolver aplicações em Go, mais cedo ou mais tarde surge a necessidade de alterar a estrutura do banco de dados: adicionar novas tabelas, modificar colunas existentes, criar índices. A execução manual de scripts SQL em diferentes ambientes (ambiente de desenvolvimento local, staging, produção) leva a erros e dessincronização. A solução são as migrações de banco de dados (database migrations).

No ecossistema Go, existem várias bibliotecas maduras para gerenciar migrações. Neste artigo, analisaremos detalhadamente as três ferramentas mais populares: golang-migrate/migrate, pressly/goose e rubenv/sql-migrate. Você aprenderá como instalar, configurar e usar cada uma delas, além de conhecer as melhores práticas.

O que são migrações e por que são necessárias?

Uma migração é um arquivo (ou conjunto de arquivos) que contém comandos SQL para alterar o esquema do banco de dados. Cada migração possui um identificador único (geralmente um timestamp ou número) e duas direções: up (aplicar alterações) e down (reverter alterações).

Principais vantagens de usar migrações:

• Versionamento de esquema — o histórico de alterações é armazenado no repositório junto com o código.
• Reprodutibilidade — as mesmas alterações em todos os ambientes.
• Reversão de alterações — possibilidade de retornar rapidamente à versão anterior do esquema.
• Trabalho em equipe — desenvolvedores não sobrescrevem as alterações uns dos outros.

1. golang-migrate/migrate

A biblioteca mais popular para migrações em Go. Suporta PostgreSQL, MySQL, SQLite, MongoDB e muitos outros bancos de dados.

Instalação

go get -u github.com/golang-migrate/migrate/v4go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

Estrutura das migrações

Crie uma pasta migrations e adicione arquivos com o prefixo no formato {timestamp}_{title}.{direction}.sql:

migrations/  000001_create_users_table.up.sql  000001_create_users_table.down.sql  000002_add_email_column.up.sql  000002_add_email_column.down.sql

Exemplo de migração (up)

-- 000001_create_users_table.up.sqlCREATE TABLE users (    id SERIAL PRIMARY KEY,    name VARCHAR(100) NOT NULL,    created_at TIMESTAMP DEFAULT NOW());

Exemplo de migração (down)

-- 000001_create_users_table.down.sqlDROP TABLE IF EXISTS users;

Aplicando migrações a partir do código Go

package main

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

func main() {    m, err := migrate.New(        "file://migrations",        "postgres://localhost:5432/mydb?sslmode=disable")    if err != nil {        panic(err)    }    if err := m.Up(); err != nil && err != migrate.ErrNoChange {        panic(err)    }}

2. pressly/goose

Goose é uma ferramenta leve e rápida que também suporta a escrita de migrações em Go (não apenas em SQL). Ideal para projetos que exigem lógica no lado do código.

Instalação

go get github.com/pressly/goose/v3/cmd/goose

Criando uma migração

goose create create_users_table sql

Será criado um arquivo como 20250101120000_create_users_table.sql. Conteúdo:

-- +goose UpCREATE TABLE users (    id SERIAL PRIMARY KEY,    name VARCHAR(100) NOT NULL);

-- +goose DownDROP TABLE IF EXISTS users;

Migrações em Go (opção avançada)

Goose permite escrever migra