O que é e para que serve

A biblioteca goose (Go Object-Oriented SQL Environment) é uma ferramenta poderosa para gerenciar migrações de banco de dados no ecossistema Go. Diferente de soluções embutidas, o goose oferece uma abordagem declarativa para versionamento de esquemas de banco de dados, permitindo que desenvolvedores descrevam alterações em SQL ou código Go. O principal objetivo do goose é automatizar o processo de aplicar e reverter alterações na estrutura do banco de dados, algo essencial para desenvolvimento em equipe e pipelines de CI/CD.

Por que usar goose? Primeiro, ela resolve o problema de sincronização do esquema do banco entre desenvolvedores: cada membro da equipe pode aplicar as migrações mais recentes com um único comando. Segundo, o goose suporta versionamento — cada migração tem um número único, permitindo identificar exatamente quais alterações já foram aplicadas. Terceiro, a biblioteca funciona com diversos SGBDs (PostgreSQL, MySQL, SQLite, ClickHouse e outros) através de uma interface unificada, facilitando a troca entre ambientes.

A principal vantagem do goose sobre alternativas (como golang-migrate/migrate) é o suporte a migrações em Go, não apenas em SQL. Você pode escrever migrações complexas com lógica de negócios, usar transações e acessar APIs externas. Além disso, o goose oferece suporte nativo a embed (incorporação de migrações no binário), ideal para ambientes de produção.

Instalação

A instalação do goose é feita através do gerenciador de pacotes padrão do Go. Certifique-se de ter o Go versão 1.18 ou superior instalado.

go install github.com/pressly/goose/v3/cmd/goose@latest

Após a instalação, verifique a versão:

goose --version

Para usar o goose como biblioteca no seu projeto, adicione a dependência:

go get github.com/pressly/goose/v3

Você também precisará do driver para o seu SGBD. Por exemplo, para PostgreSQL:

go get github.com/lib/pq

Para MySQL:

go get github.com/go-sql-driver/mysql

Para SQLite:

go get github.com/mattn/go-sqlite3

Início rápido — exemplo mínimo funcional

Vamos criar um projeto simples para demonstrar as funcionalidades básicas do goose.

1. Crie o diretório do projeto e inicialize o módulo:

mkdir goose-demo && cd goose-demo
go mod init goose-demo

2. Crie um diretório para as migrações:

mkdir migrations

3. Crie a primeira migração em SQL. Arquivo migrations/001_create_users.sql:

-- +goose Up
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

-- +goose Down
DROP TABLE users;

4. Crie o arquivo main.go para executar as migrações programaticamente:

package main

import (
    "database/sql"
    "embed"
    "log"

    "github.com/pressly/goose/v3"
    _ "github.com/lib/pq"
)

//go:embed migrations/*.sql
var migrations embed.FS

func main() {
    // Conexão com o banco de dados
    db, err := sql.Open("postgres", "host=localhost port=5432 user=postgres password=postgres dbname=testdb sslmode=disable")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // Define a fonte das migrações a partir do embed.FS
    goose.SetBaseFS(migrations)

    // Executa as migrações até a versão mais recente
    if err := goose.Up(db, "migrations"); err != nil {
        log.Fa