database/sql Connection Pooling & Timeouts

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

Ajustar SetMaxOpenConns, configurações de idle e tempos de vida impede que seu serviço cause inanição no banco de dados ou trave goroutines esperando por uma conexão livre.

Combine limites de pool com deadlines de context.Context para que requisições HTTP abandonadas liberem slots do pool prontamente.

Resumo

SetMaxOpenConns limita conexões simultâneas por processo.

SetMaxIdleConns controla quantas conexões permanecem aquecidas entre picos.

SetConnMaxLifetime e SetConnMaxIdleTime rotacionam conexões para higiene de balanceador de carga e credenciais.

QueryContext e funções similares honram o cancelamento enquanto esperam por uma conexão ou executam uma consulta.

Receita

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

func ConfigurePool(db *sql.DB) {
    db.SetMaxOpenConns(25)
    db.SetMaxIdleConns(10)
    db.SetConnMaxLifetime(30 * time.Minute)
    db.SetConnMaxIdleTime(5 * time.Minute)
}
 
func GetOrder(ctx context.Context, db *sql.DB, id string) (string, error) {
    ctx, cancel := context.WithTimeout(ctx, 300*time.Millisecond)
    defer cancel()
    var status string
    err := db.QueryRowContext(ctx,
        `SELECT status FROM orders WHERE id = $1`, id,
    ).Scan(&status)
    return status, err
}

Quando usar isso:

• Qualquer serviço de produção usando database/sql por trás de HTTP ou gRPC.
• Quando métricas mostram WaitCount aumentando ou consultas excedendo o tempo limite do desconectado do cliente.
• Após escalar réplicas - divida max_connections do banco de dados pelo número de pods.

Exemplo de Trabalho

package main
 
import (
    "context"
    "database/sql"
    "fmt"
    "time"
 
    _ "github.com/mattn/go-sqlite3"
)
 
func main() {
    db, err := sql.Open("sqlite3", ":memory:")
    if err != nil {
        panic(err)
    }
    defer db.Close()
 
    db.SetMaxOpenConns(5)
    db.SetMaxIdleConns(2)
    db.SetConnMaxLifetime(time.Hour)
 
    ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
    defer cancel()
 
    var one int
    err = db.QueryRowContext(ctx, `SELECT 1`).Scan(&one)
    fmt.Println(one, err)
 
    s := db.Stats()
    fmt.Printf("waitCount=%d waitDuration=%s\n", s.WaitCount, s.WaitDuration)
}

O que isso demonstra:

• Limites de pool se aplicam antes da primeira consulta ser executada.
• QueryRowContext respeita o deadline pai.
• db.Stats() expõe WaitCount e WaitDuration para sinais de saturação.
• SQLite em memória ainda segue a mesma API que drivers de rede.

Mergulho Profundo

Como Funciona

• sql.Open cria um gerenciador de pool; conexões são criadas preguiçosamente até MaxOpenConns.
• Quando todas as conexões estão ocupadas, novas chamadas QueryContext bloqueiam até que uma conexão seja liberada ou ctx termine.
• Conexões retornadas vão para o pool ocioso se estiverem abaixo de MaxIdleConns; caso contrário, elas são fechadas.
• ConnMaxLifetime força a substituição mesmo que a conexão esteja saudável, o que ajuda por trás de credenciais rotativas ou PgBouncer.

Configurações de Pool em Resumo

Contexto vs Timeouts SQL

ctx, cancel := context.WithTimeout(parent, 200*time.Millisecond)
defer cancel()
_, err := db.ExecContext(ctx, `SET statement_timeout = 150`)

• O cancelamento do contexto interrompe a espera por slots do pool e viagens de ida e volta do driver quando suportado.
• O statement_timeout do Postgres protege quando os drivers terminam o pacote atual lentamente.
• Camada de ambos: contexto para orçamento de requisição, SQL para proteções agnósticas ao driver.

Notas do Go

• Um *sql.DB por DSN por processo é o típico; não abra um novo pool por requisição.
• Passe *sql.DB de main para repositórios; evite pools em init() sem testes.
• Registre os campos de db.Stats() (InUse, Idle, WaitCount) em um timer em produção.

Armadilhas

• MaxOpenConns padrão ilimitado - Um pico de tráfego pode abrir milhares de conexões e atingir too many connections do Postgres. Correção: defina um limite explícito com base no planejamento de capacidade.
• MaxIdleConns enorme igual a MaxOpenConns em DBs minúsculos - Sockets ociosos desperdiçam slots do DB. Correção: pool ocioso menor que o limite aberto, a menos que os dados de latência digam o contrário.
• Sem Ping na inicialização - Credenciais incorretas falham na primeira requisição do usuário. Correção: PingContext com timeout de boot em main.
• Timeout filho maior que o handler - A consulta é executada após o cliente ter saído. Correção: derive o timeout do DB do deadline restante de r.Context().
• Ignorando métricas WaitCount - A saturação parece consultas lentas. Correção: alerte sobre o crescimento da duração de espera antes que o tempo de consulta p99 dispare.
• Novo pool por teste de integração sem Close - CI esgota portas efêmeras. Correção: um pool por pacote de teste ou contêiner de teste compartilhado com teardown.

Alternativas

FAQs

Relacionado

• Noções Básicas de Bancos de Dados - Fundamentos de Open, Query, Scan
• Acesso a Dados em Go: database/sql como a Base - âncora arquitetural
• Transações, Prepared Statements & sql.Tx - transações curtas
• context em database/sql & gRPC - fiação de cancelamento
• Melhores Práticas de Bancos de Dados e Acesso a Dados - checklist de pool e timeout

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 versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).

WTI5a1pXZDFhV1JsY3k1cGIzeGpaMmx2TkRFMmZESXdNall3Tnc9PQ==