Transações, Prepared Statements & sql.Tx

Transações agrupam múltiplas instruções em uma unidade atômica.

Prepared statements reutilizam SQL analisado para parâmetros repetidos.

sql.Tx une ambos: inicie com contexto, execute dentro do limite, então comite ou reverta.

Resumo

BeginTx(ctx, opts) inicia uma transação com nível de isolamento opcional.

Commit persiste alterações; Rollback as descarta - chame um caminho após erros.

PrepareContext cria um Stmt; Tx.Stmt o reutiliza dentro de uma transação.

Use defer Rollback após BeginTx para que os caminhos de erro não vazem transações abertas.

Receita

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

func Transfer(ctx context.Context, db *sql.DB, from, to int64, amount int) error {
    tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelReadCommitted})
    if err != nil {
        return err
    }
    defer tx.Rollback()
 
    if _, err := tx.ExecContext(ctx,
        `UPDATE accounts SET balance = balance - $1 WHERE id = $2`, amount, from,
    ); err != nil {
        return err
    }
    if _, err := tx.ExecContext(ctx,
        `UPDATE accounts SET balance = balance + $1 WHERE id = $2`, amount, to,
    ); err != nil {
        return err
    }
    return tx.Commit()
}

Quando usar isso:

• Escritas de múltiplos passos que devem ter sucesso ou falhar juntas.
• Inserções ou consultas repetidas com a mesma forma de SQL em um caminho crítico.
• Isolamento serializável quando condições de corrida não podem ser resolvidas apenas na lógica da aplicação.

Exemplo de Trabalho

package main
 
import (
    "context"
    "database/sql"
    "fmt"
 
    _ "github.com/mattn/go-sqlite3"
)
 
func main() {
    db, _ := sql.Open("sqlite3", ":memory:")
    defer db.Close()
    ctx := context.Background()
 
    _, _ = db.ExecContext(ctx, `CREATE TABLE ledger (
        id INTEGER PRIMARY KEY,
        balance INTEGER NOT NULL
    )`)
    _, _ = db.ExecContext(ctx, `INSERT INTO ledger (id, balance) VALUES (1, 100), (2, 0)`)
 
    stmt, err := db.PrepareContext(ctx, `UPDATE ledger SET balance = balance + ? WHERE id = ?`)
    if err != nil {
        panic(err)
    }
    defer stmt.Close()
 
    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        panic(err)
    }
    defer tx.Rollback()
 
    txStmt := tx.Stmt(stmt)
    if _, err := txStmt.ExecContext(ctx, -25, 1); err != nil {
        panic(err)
    }
    if _, err := txStmt.ExecContext(ctx, 25, 2); err != nil {
        panic(err)
    }
    fmt.Println(tx.Commit())
}

O que isso demonstra:

• PrepareContext uma vez, Tx.Stmt para vincular o stmt à transação ativa.
• defer tx.Rollback() cobre saídas por pânico e erro; Commit tem sucesso após o trabalho ser concluído.
• O mesmo ctx flui através do início, execução e commit para cancelamento.
• SQLite ilustra o padrão; Postgres e MySQL usam a mesma API database/sql.

Mergulho Profundo

Como Funciona

• BeginTx retira uma conexão dedicada até o commit ou rollback.
• Declarações em tx são executadas na mesma conexão, preservando as garantias de isolamento.
• Objetos Stmt podem cachear planos preparados no lado do servidor, dependendo das configurações do driver.
• Após Commit, o objeto de transação é inválido; inicie um novo BeginTx para mais trabalho.

Níveis de Isolamento

Disciplina de Rollback

tx, err := db.BeginTx(ctx, nil)
if err != nil {
    return err
}
defer func() {
    _ = tx.Rollback() // no-op após Commit bem-sucedido
}()

• Rollback após Commit retorna sql.ErrTxDone - seguro para ignorar em defer.
• Retorne erros de domínio antes do commit; mapeie sql.ErrTxDone apenas se você cometer duas vezes por engano.
• Transações longas mantêm locks de linha - mantenha a lógica de negócios fora da tx quando possível.

Savepoints (específico do driver)

Algumas equipes usam SQL SAVEPOINT bruto dentro de uma tx para rollback parcial.

Prefira transações menores e menos numerosas em vez de aninhamento profundo de savepoints, a menos que a equipe de banco de dados documente padrões.

Armadilhas

• Esqueceu Rollback no caminho de erro - A conexão permanece em estado abortado e vaza do pool. Correção: defer tx.Rollback() imediatamente após BeginTx.
• Usando db.Exec dentro de uma tx aberta para escritas relacionadas - Declarações são executadas em conexões diferentes e quebram a atomicidade. Correção: use apenas tx.ExecContext para trabalho transacional.
• Prepared stmt da tx errada - Executar stmt.Exec enquanto uma tx está aberta ignora a conexão da transação. Correção: tx.Stmt(stmt) ou prepare diretamente na tx.
• Grandes jobs em batch de transação - Uma tx bloqueia tabelas por minutos. Correção: divida commits com offsets idempotentes ou tabelas de staging.
• Serializable sem retry - Conflitos aparecem como erros sob carga. Correção: tente novamente em falha de serialização com backoff.
• Serializable sem retry - Conflitos aparecem como erros sob carga. Correção: tente novamente em falha de serialização com backoff.

Alternativas

FAQs

Relacionado

• Noções Básicas de Banco de Dados - Exemplo inicial de BeginTx
• Pool de Conexões e Timeouts do database/sql - txs mantêm conexões
• Migrações com golang-migrate & goose - transações de alteração de esquema
• GORM vs sqlx vs Raw database/sql - Helpers de transação ORM
• Melhores Práticas de Banco de Dados e Acesso a Dados - regras de comprimento de tx e rollback

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 (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).