context em database/sql & gRPC

database/sql e google.golang.org/grpc foram projetados em torno de context.Context desde o início.

Passar ctx para métodos de query e RPC vincula o trabalho de banco de dados e rede à mesma árvore de cancelamento do seu handler HTTP.

Resumo

Use QueryContext, ExecContext e BeginTx com context para cada chamada de banco de dados com escopo de requisição.

Métodos de cliente e servidor gRPC aceitam ctx como o primeiro argumento; deadlines se propagam como timeouts de RPC.

RPCs de streaming devem verificar ctx.Done() entre chamadas Recv e Send.

Receita

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

func GetOrder(ctx context.Context, db *sql.DB, id string) (string, error) {
    var status string
    err := db.QueryRowContext(ctx, `SELECT status FROM orders WHERE id = ?`, id).Scan(&status)
    return status, err
}

Quando usar isso:

• Substitua Query/Exec sem Context em qualquer caminho de código alcançável a partir de handlers HTTP ou gRPC.
• Passe o context do handler ou interceptor para stubs gRPC inalterados, exceto por timeouts filhos mais curtos.
• Cancele loops de streaming quando ctx.Done() disparar para evitar vazamentos de goroutine.

Exemplo de Trabalho

package main
 
import (
    "context"
    "database/sql"
    "fmt"
    "time"
 
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
 
    _ "github.com/mattn/go-sqlite3"
)
 
func queryStatus(ctx context.Context, db *sql.DB) (string, error) {
    ctx, cancel := context.WithTimeout(ctx, 200*time.Millisecond)
    defer cancel()
    var s string
    err := db.QueryRowContext(ctx, `SELECT 'shipped'`).Scan(&s)
    return s, err
}
 
func dialGRPC(ctx context.Context) (*grpc.ClientConn, error) {
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()
    return grpc.DialContext(ctx, "localhost:50051",
        grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
}
 
func main() {
    db, _ := sql.Open("sqlite3", ":memory:")
    defer db.Close()
 
    parent, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
    defer cancel()
 
    status, err := queryStatus(parent, db)
    fmt.Println(status, err)
 
    _, err = dialGRPC(parent)
    fmt.Println("grpc dial:", err)
}

O que isso demonstra:

• QueryRowContext respeita o cancelamento pai e o timeout filho local.
• grpc.DialContext bloqueia apenas até o context terminar ou a conexão ser bem-sucedida.
• Timeouts filhos encolhem dentro do orçamento pai para cada subsistema.
• O driver SQLite aqui ilustra o padrão; pools de produção usam a mesma API com drivers Postgres/MySQL.

Mergulho Profundo

Como Funciona

• database/sql passa o context para interfaces QueryerContext do driver; o comportamento de cancelamento depende do suporte do driver.
• A aquisição do pool de conexões respeita o context - o esgotamento lento do pool retorna quando ctx termina em vez de bloquear para sempre.
• Objetos Tx usam BeginTx(ctx, opts); commit e rollback são rápidos, mas instruções em andamento já devem usar o context da tx.
• gRPC codifica deadlines em metadados; servidores devem falhar rapidamente com codes.DeadlineExceeded quando o tempo restante for insuficiente.

Superfície da API database/sql

Padrão de Streaming gRPC

func consume(stream pb.Service_StreamServer) error {
    ctx := stream.Context()
    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
        }
        msg, err := stream.Recv()
        if err != nil {
            return err
        }
        _ = msg
    }
}

Streams de servidor expõem Context(); streams de cliente aceitam o ctx do chamador na invocação inicial do RPC.

Nota sobre controller-runtime

Chamadas de cliente Kubernetes de reconciliadores devem passar o context de reconciliação para requisições de API para que os watches parem quando o manager for desligado.

Armadilhas

• Usar Query sem Context em handlers - Requisições HTTP abandonadas mantêm o trabalho do DB ativo. Correção: proibir métodos não-Context na revisão para caminhos de requisição.
• Transações longas sem deadline - Locks mantidos após o cliente sair. Correção: BeginTx com ctx; manter transações curtas.
• Ignorar ctx em loops Recv de stream - Streams de servidor vazam após o cliente desconectar. Correção: usar select em ctx.Done() ou lidar com erros de Recv prontamente.
• grpc.Dial em vez de DialContext - Sem cancelamento durante a descoberta de serviço ou handshake TLS. Correção: sempre DialContext com ctx limitado.
• Timeout filho maior que o deadline gRPC - Servidor pode abortar antes do que o cliente espera. Correção: ler ctx.Deadline() no lado do servidor e limitar o trabalho.
• Assumir que todos os drivers cancelam instantaneamente - Alguns drivers cancelam apenas entre viagens de ida e volta de rede. Correção: combinar context com timeouts de instrução em SQL quando necessário.

Alternativas

FAQs

Relacionados

• Propagação de Cancelamento em Handlers HTTP - onde o ctx de DB começa
• Deadlines & Timeouts Através de Limites de Serviço - orçamentos por salto
• Testando Código Que Aceita context.Context - fakes e timeouts
• Valores de context: Quando e Quando Não - metadados gRPC vs valores
• Melhores Práticas do Pacote context - convenções SQL e RPC

Versões de 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). 49454e4f4d5f434e4f5904434556494d43451e1b1256181a181c1a1d