Acesso a Dados em Go: database/sql como Base

Go mantém o acesso a banco de dados explícito.

O pacote database/sql da biblioteca padrão define como as aplicações se comunicam com bancos de dados SQL, e drivers separados (Postgres, MySQL, SQLite e outros) implementam o protocolo real.

ORMs como GORM e auxiliares como sqlx ficam sobre essa mesma base - eles não substituem o pool, as transações ou as APIs cientes de contexto.

Noções Básicas de Banco de Dados coleta snippets executáveis; artigos irmãos cobrem pooling, transações, migrações, cache e convenções de equipe.

Resumo

• database/sql é uma API pequena e agnóstica de driver para pooling de conexões, consultas, transações e prepared statements. Seu código importa um driver com um import em branco e chama sql.Open.
• Insight: Permanecer próximo a database/sql mantém você portátil entre drivers, testável com fakes e alinhado com como as pilhas HTTP e gRPC do Go propagam context.Context para chamadas de armazenamento.
• Conceitos Chave: driver, pool de DB, Rows, Scan, Tx, Stmt, QueryContext, padrão de repositório.
• Quando Usar: Padrão para serviços que falam SQL. Use um ORM quando migrações, associações e geração de código dominam; use SQL puro quando as consultas são ajustadas manualmente e a habilidade SQL da equipe é alta.
• Limitações/Trade-offs: Sem construtor de consultas na stdlib; tipos sql.Null* são verbosos; o comportamento do driver difere para cancelamento e cache de prepared statement; riscos N+1 se movem para camadas ORM se você não for cuidadoso.
• Tópicos Relacionados: deadlines de contexto, ajuste de pool de conexões, golang-migrate, embed para migrações, cache-aside com Redis, observabilidade para consultas lentas.

Fundamentos

Imagine seu serviço como camadas: manipulador HTTP, serviço de domínio, repositório de armazenamento, então *sql.DB.

O manipulador analisa a requisição e passa r.Context() para baixo.

O repositório é o dono das strings SQL (ou SQL gerado) e mapeia linhas para tipos de domínio.

*sql.DB é um pool de conexões, não um único socket.

sql.Open("postgres", dsn) registra o nome do driver e retorna um handle de pool.

A primeira conexão real frequentemente aparece em Ping, Query ou Exec.

Drivers vivem em módulos separados:

import (
    "database/sql"
    _ "github.com/jackc/pgx/v5/stdlib" // Postgres
)

O import em branco executa o init() do driver para que sql.Open possa resolver "pgx".

Trocar de bancos de dados significa trocar o import do driver e o DSN, não reescrever os tipos da aplicação se os repositórios ocultarem os detalhes do SQL.

Mecânicas e Interações

O caminho de leitura idiomático:

func GetUser(ctx context.Context, db *sql.DB, id int64) (User, error) {
    var u User
    err := db.QueryRowContext(ctx,
        `SELECT id, email FROM users WHERE id = $1`, id,
    ).Scan(&u.ID, &u.Email)
    if errors.Is(err, sql.ErrNoRows) {
        return User{}, ErrNotFound
    }
    return u, err
}

QueryRowContext espera no máximo uma linha.

Scan copia os valores das colunas para variáveis Go e reporta incompatibilidades de tipo imediatamente.

Leituras de múltiplas linhas usam QueryContext, iteram rows.Next(), e sempre rows.Close().

Escritas usam ExecContext; jobs em lote podem usar transações via BeginTx.

Frameworks (chi, gin, echo) não mudam o contrato de armazenamento: repositórios ainda aceitam ctx e *sql.DB (ou uma interface que os envolva).

Serviços google.golang.org/grpc passam o contexto RPC para métodos de repositório da mesma forma que manipuladores HTTP fazem.

Considerações Avançadas e Aplicações

Serviços de produção combinam configurações de pool com contexto por consulta:

• SetMaxOpenConns limita conexões simultâneas ao banco de dados.
• SetMaxIdleConns mantém conexões aquecidas para tráfego intermitente.
• SetConnMaxLifetime rotaciona conexões atrás de balanceadores de carga.
• QueryContext vincula o trabalho ao desconectamento do cliente e aos deadlines do serviço.

ORMs (GORM) geram SQL e gerenciam associações; sqlx adiciona helpers de scan de struct, mantendo-se próximo ao SQL bruto.

Equipes frequentemente escolhem:

Observabilidade pertence ao limite do repositório: registre o nome da consulta, latência e o deadline restante do ctx; exponha estatísticas do pool (db.Stats()) para métricas.

Reconciliadores do controller-runtime devem passar o contexto de reconciliação para chamadas de repositório para que o trabalho do banco de dados pare quando o gerenciador for desligado.

Equívocos Comuns

• "sql.Open conecta imediatamente" - Ele aloca um pool; erros frequentemente aparecem no primeiro uso. Sempre use PingContext na inicialização.
• "ORMs substituem database/sql" - Eles o envolvem. Você ainda precisa de ajuste de pool e atualizações de driver.
• "Um *sql.DB global é um anti-padrão" - Um único pool por processo é normal; o anti-padrão é a lógica de init() oculta sem testes.
• "Contexto é opcional para consultas rápidas" - O cancelamento do cliente deve parar o trabalho mesmo para consultas de milissegundos sob carga.
• "Repositórios devem retornar sql.Rows" - Retorne tipos de domínio ou slices; mantenha Rows dentro do repositório.
• "Prepared statements são sempre mais rápidos" - Depende do cache do driver e da forma da consulta; meça antes de usar Prepare genericamente.

FAQs

Relacionados

• Noções Básicas de Banco de Dados - exemplos executáveis de Open, Query, Scan
• Pooling de Conexões e Timeouts do database/sql - ajuste de pool e deadlines
• Transações, Prepared Statements e sql.Tx - limites de Tx
• GORM vs sqlx vs Raw database/sql - comparação de pilhas
• Contexto em database/sql e gRPC - integração de cancelamento
• Melhores Práticas de Banco de Dados e Acesso a Dados - convenções de equipe

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