embed para Migrações SQL e Dados de Seed

O embed do Go 1.16+ permite que você envie arquivos de migração SQL e scripts de seed dentro do binário compilado.

Os artefatos de implantação permanecem autocontidos: a mesma imagem de contêiner que executa a API pode aplicar versões de esquema sem montar um diretório de host.

Resumo

//go:embed anexa arquivos ou diretórios a variáveis do tipo embed.FS.

As bibliotecas de migração aceitam adaptadores io/fs ou http.FileSystem sobre o FS incorporado.

Dados de seed para desenvolvimento e teste podem ser enviados em uma árvore incorporada separada das migrações de produção.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

package migrations
 
import (
    "embed"
    "io/fs"
)
 
//go:embed sql/*.sql
var files embed.FS
 
func FS() fs.FS {
    sub, _ := fs.Sub(files, "sql")
    return sub
}

import (
    "github.com/golang-migrate/migrate/v4"
    _ "github.com/golang-migrate/migrate/v4/database/postgres"
    "github.com/golang-migrate/migrate/v4/source/iofs"
)
 
source, _ := iofs.New(migrations.FS(), ".")
m, _ := migrate.NewWithSourceInstance("iofs", source, dbURL)
_ = m.Up()

Quando usar isso:

• Implantações de binário único (Kubernetes, contêineres serverless) sem SQL montado via ConfigMap.
• Ferramentas CLI que precisam migrar laptops offline sem um checkout git.
• Testes de integração que precisam de um esquema conhecido incorporado ao lado do código de teste.

Exemplo de Trabalho

package main
 
import (
    "database/sql"
    "embed"
    "fmt"
    "io/fs"
 
    "github.com/pressly/goose/v3"
    _ "github.com/mattn/go-sqlite3"
)
 
//go:embed migrations/*.sql
var migrationFiles embed.FS
 
func main() {
    db, _ := sql.Open("sqlite3", ":memory:")
    defer db.Close()
 
    goose.SetBaseFS(migrationFiles)
    goose.SetDialect("sqlite3")
    if err := goose.Up(db, "migrations"); err != nil {
        panic(err)
    }
 
    var n int
    _ = db.QueryRow(`SELECT COUNT(*) FROM sqlite_master WHERE type='table'`).Scan(&n)
    fmt.Println("tabelas:", n)
}

migrations/00001_init.sql:

-- +goose Up
CREATE TABLE widgets (id INTEGER PRIMARY KEY, name TEXT);
 
-- +goose Down
DROP TABLE widgets;

O que isso demonstra:

• go:embed agrupa SQL ao lado do arquivo fonte Go.
• goose.SetBaseFS lê migrações da memória em vez do disco.
• O mesmo padrão funciona para o driver de origem iofs do golang-migrate.
• SQLite em memória prova o fluxo sem arquivos externos em tempo de execução.

Mergulho Profundo

Como Funciona

• O compilador registra os arquivos correspondentes no binário em tempo de compilação.
• embed.FS é somente leitura e seguro para compartilhar entre goroutines.
• fs.Sub limita a raiz quando o SQL está em um subdiretório.
• Alterar o SQL requer recompilação e reimplantação - o que é desejável para lançamentos reproduzíveis.

Convenções de Layout

golang-migrate com iofs

d, err := iofs.New(migrations.FS(), ".")
m, err := migrate.NewWithInstance("iofs", d, "postgres", dbURL)

• O nome da origem "iofs" combina com o nome do driver do banco de dados em NewWithInstance.
• O bloqueio ainda usa o banco de dados; o embed apenas substitui as leituras do sistema de arquivos.
• CI deve executar os mesmos testes de FS incorporados que a produção.

Padrões de Dados de Seed

• Seeds apenas de desenvolvimento: tag de compilação ou //go:embed seed/* separado importado apenas de main_dev.go.
• Seeds idempotentes: INSERT ... ON CONFLICT DO NOTHING ou migração Go do goose com loops.
• Nunca incorpore segredos de produção - seeds contêm apenas dados falsos.

Armadilhas

• Caminho de embed incorreto após refatoração - A compilação falha com "padrão não corresponde a nenhum arquivo". Correção: mantenha o diretório SQL adjacente ao arquivo Go que carrega go:embed.
• Editar migrações sem recompilação - Executar o binário antigo aplica o esquema desatualizado. Correção: vincule a tag da imagem ao SHA do git; a tabela de versão de migração detecta desvios.
• Arquivos de seed enormes incham o binário - O tamanho do contêiner e o tempo de link aumentam. Correção: comprima seeds de desenvolvimento ou carregue do armazenamento de objetos apenas em ambientes não produtivos.
• Suposição de embed.FS gravável - O embed é somente leitura; ferramentas que reescrevem arquivos precisam de disco ou cópias temporárias. Correção: use APIs de biblioteca que leem de fs.FS.
• Mistura de fontes de host e embed - Comportamento diferente em desenvolvimento vs. produção. Correção: uma única fonte de verdade; o desenvolvimento local usa o mesmo embed ou go run da raiz do módulo.
• Segredos em arquivos SQL - Credenciais confirmadas em scripts de seed. Correção: parametrize o DSN do ambiente; o SQL não contém senhas.

Alternativas

FAQs

Relacionado

• Migrações com golang-migrate & goose - comandos de ferramenta e CI
• Noções Básicas de Bancos de Dados - executando SQL
• Práticas Recomendadas de Bancos de Dados e Acesso a Dados - artefatos de migração imutáveis
• Acesso a Dados em Go: database/sql como a Base - fiação do pool após a migração

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos da placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).