Padrões de tratamento de erros e retentativas com go-mssqldb

Aplicações Production Go precisam de um tratamento estruturado de erros para distinguir entre falhas transitórias que você pode tentar novamente e erros permanentes que exigem intervenção humana. Este artigo aborda a classificação de erros, padrões de repetição e estratégias de resiliência para o driver go-mssqldb.

Estrutura de erro do SQL Server

Quando o SQL Server retorna um erro, o go-mssqldb driver o envolve em uma mssql.Error struct. Use uma asserção de tipo para acessar os campos de erro estruturados:

import (
    "database/sql"
    "errors"
    "fmt"

    mssql "github.com/microsoft/go-mssqldb"
)

func handleError(err error) {
    var mssqlErr mssql.Error
    if errors.As(err, &mssqlErr) {
        fmt.Printf("Number:  %d\n", mssqlErr.Number)
        fmt.Printf("State:   %d\n", mssqlErr.State)
        fmt.Printf("Class:   %d\n", mssqlErr.Class)
        fmt.Printf("Message: %s\n", mssqlErr.Message)
        fmt.Printf("Server:  %s\n", mssqlErr.ServerName)
        fmt.Printf("Proc:    %s\n", mssqlErr.ProcName)
        fmt.Printf("Line:    %d\n", mssqlErr.LineNo)
    }
}

Campos de erro

Níveis de severidade

Classificar erros como transitórios ou permanentes

Erros transitórios são condições temporárias que se resolvem sozinhas, como falhas de rede, limitação de conexão ou contenção breve de recursos. Erros permanentes exigem mudanças no código ou na configuração.

Números comuns de erro transitório

Use o seguinte catálogo compartilhado como a lista canônica de erros transitórios de estabelecimento de conexão e transporte de caminho de requisição:

Os seguintes erros podem ser transitórios quando ocorrem durante o estabelecimento da conexão ou ao enviar uma solicitação para o servidor. Tente novamente em uma retirada curta e limitada. Erros que persistem além de algumas tentativas geralmente indicam um problema de configuração, como servidor errado, permissões faltando, configurações de criptografia incompatíveis ou cota esgotada, que a tentativa não vai corrigir.

Os erros no nível da instrução não estão nessa lista porque são disparados depois que a conexão é estabelecida e a falha deixa a sessão utilizável. Os erros de instrução passíveis de repetição mais comuns são 1205 (vítima de deadlock) e 1222 (tempo limite da solicitação de bloqueio). Repita a transação inteira em vez da única instrução com falha.

O texto da mensagem de erro vem de erros transitórios de conexão do SQL do Azure. Esses erros podem ser repetidos no SQL Server, no Banco de Dados SQL do Azure, no Instância Gerenciada de SQL do Azure, no Banco de Dados SQL no Microsoft Fabric e em pools SQL dedicados no Azure Synapse Analytics.

A função a seguir isTransient mostra um padrão de implementação do Go para classificação de repetição. Trate o catálogo compartilhado acima como a fonte da verdade e mantenha sua busca de código alinhada com ele.

// isTransient returns true if the error is a transient SQL Server error
// that is likely to succeed on retry.
func isTransient(err error) bool {
    var mssqlErr mssql.Error
    if !errors.As(err, &mssqlErr) {
        // Network errors, context deadlines, and connection resets
        // are also transient.
        return isNetworkError(err)
    }

    if isTransientSQLNumber(mssqlErr.Number) {
        return true
    }

    // Severity 17-19 indicates resource issues that are typically transient.
    return mssqlErr.Class >= 17 && mssqlErr.Class <= 19
}

// Keep this lookup synchronized with the shared transient catalog above.
var transientSQLNumbers = map[int32]struct{}{
    64:    {}, // Transport/connection error.
    1205:  {}, // Deadlock victim.
    40197: {}, // Service error processing request.
    40501: {}, // Service is currently busy.
    40613: {}, // Database is currently unavailable.
    49918: {}, // Cannot process request: not enough resources.
    49919: {}, // Cannot process create/update request.
    49920: {}, // Cannot process request: too many operations.
}

func isTransientSQLNumber(number int32) bool {
    _, ok := transientSQLNumbers[number]
    return ok
}

Se você encontrar erros de configuração e cota, corrija a capacidade subjacente, banco de dados ou configuração da rede antes de tentar novamente. Os exemplos incluem:

• 40544 (cota de tamanho do banco de dados)
• 4060 (não é possível abrir o banco de dados)
• 40615 (regra do firewall)

Detectar erros de rede

Erros em nível de rede não produzem valores mssql.Error. Verifique os tipos comuns de erro de rede do Go:

import (
    "context"
    "errors"
    "net"
    "io"
)

func isNetworkError(err error) bool {
    if err == nil {
        return false
    }

    // Context deadline exceeded or canceled
    if errors.Is(err, context.DeadlineExceeded) {
        return true
    }

    // Connection reset or broken pipe
    var netErr *net.OpError
    if errors.As(err, &netErr) {
        return true
    }

    // Unexpected EOF (server dropped the connection)
    if errors.Is(err, io.ErrUnexpectedEOF) || errors.Is(err, io.EOF) {
        return true
    }

    return false
}

Implementar a tentativa HTTP com a replicação exponencial

Tente novamente em caso de erros transitórios, com intervalos cada vez maiores entre as tentativas. Essa abordagem dá tempo ao servidor para se recuperar e evita sobrecarregá-lo com tentativas rápidas.

import (
    "context"
    "database/sql"
    "errors"
    "fmt"
    "log"
    "math"
    "math/rand"
    "time"

    mssql "github.com/microsoft/go-mssqldb"
)

// RetryConfig controls retry behavior.
type RetryConfig struct {
    MaxAttempts int           // Maximum number of attempts (including the first).
    BaseDelay   time.Duration // Initial delay before the first retry.
    MaxDelay    time.Duration // Upper bound on delay between retries.
}

// DefaultRetryConfig provides sensible defaults for SQL Server workloads.
var DefaultRetryConfig = RetryConfig{
    MaxAttempts: 5,
    BaseDelay:   100 * time.Millisecond,
    MaxDelay:    10 * time.Second,
}

// RetryFunc executes fn with retries for transient errors.
func RetryFunc(ctx context.Context, cfg RetryConfig, fn func(ctx context.Context) error) error {
    var lastErr error
    for attempt := 0; attempt < cfg.MaxAttempts; attempt++ {
        lastErr = fn(ctx)
        if lastErr == nil {
            return nil
        }

        if !isTransient(lastErr) {
            return lastErr // Permanent error, don't retry.
        }

        if attempt == cfg.MaxAttempts-1 {
            break // Last attempt, don't sleep.
        }

        delay := calculateDelay(attempt, cfg.BaseDelay, cfg.MaxDelay)

        select {
        case <-ctx.Done():
            return ctx.Err()
        case <-time.After(delay):
        }
    }
    return lastErr
}

func calculateDelay(attempt int, baseDelay, maxDelay time.Duration) time.Duration {
    // Exponential backoff: base * 2^attempt
    delay := time.Duration(float64(baseDelay) * math.Pow(2, float64(attempt)))
    if delay > maxDelay {
        delay = maxDelay
    }
    // Add jitter: +/- 25% to avoid thundering herd
    jitter := time.Duration(rand.Int63n(int64(delay) / 2))
    return delay/2 + jitter
}

// isTransient classifies retryable SQL Server errors.
// For a fuller example, see "Classify errors as transient or permanent" earlier in this article.
func isTransient(err error) bool {
    var mssqlErr mssql.Error
    if !errors.As(err, &mssqlErr) {
        return errors.Is(err, context.DeadlineExceeded)
    }

    switch mssqlErr.Number {
    case 1205, 40197, 40501, 40613, 49918, 49919, 49920:
        return true
    }

    return mssqlErr.Class >= 17 && mssqlErr.Class <= 19
}

// getEmployeeCount wraps a query with automatic retry.
func getEmployeeCount(ctx context.Context, db *sql.DB) (int, error) {
    var count int
    err := RetryFunc(ctx, DefaultRetryConfig, func(ctx context.Context) error {
        // This query executes on every retry attempt until success or exhaustion.
        return db.QueryRowContext(ctx, "SELECT COUNT(*) FROM HumanResources.Employee").Scan(&count)
    })
    return count, err
}

// Example call site (assumes db is already initialized).
func example(ctx context.Context, db *sql.DB) {
    queryCtx, cancel := context.WithTimeout(ctx, 15*time.Second)
    defer cancel()

    count, err := getEmployeeCount(queryCtx, db)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Employee count: %d\n", count)
}

Lidar com deadlocks

Deadlocks (erro 1205) são o erro transitório mais comum em aplicações multiusuário. O SQL Server termina automaticamente uma das sessões concorrentes e retorna o erro 1205 à vítima.

Detectar um impasse

Verifique se um erro do SQL Server é um bloqueio (erro 1205).

func isDeadlock(err error) bool {
    var mssqlErr mssql.Error
    if errors.As(err, &mssqlErr) {
        return mssqlErr.Number == 1205
    }
    return false
}

Repetir as transações após deadlocks

Quando ocorre um bloqueio dentro de uma transação, o servidor reverte toda a transação. Você deve tentar novamente a transação completa, não apenas a declaração falhada:

func transferInventory(ctx context.Context, db *sql.DB, productID, fromLocationID, toLocationID int, qty int) error {
    return RetryFunc(ctx, DefaultRetryConfig, func(ctx context.Context) error {
        tx, err := db.BeginTx(ctx, &sql.TxOptions{
            Isolation: sql.LevelReadCommitted,
        })
        if err != nil {
            return err
        }
        defer tx.Rollback()

        _, err = tx.ExecContext(ctx,
            "UPDATE Production.ProductInventory SET Quantity = Quantity - @qty WHERE ProductID = @pid AND LocationID = @lid",
            sql.Named("qty", qty),
            sql.Named("pid", productID),
            sql.Named("lid", fromLocationID))
        if err != nil {
            return err
        }

        _, err = tx.ExecContext(ctx,
            "UPDATE Production.ProductInventory SET Quantity = Quantity + @qty WHERE ProductID = @pid AND LocationID = @lid",
            sql.Named("qty", qty),
            sql.Named("pid", productID),
            sql.Named("lid", toLocationID))
        if err != nil {
            return err
        }

        return tx.Commit()
    })
}

Tentar novamente é a resposta correta no código da aplicação, mas impasses repetidos na mesma consulta indicam um problema de design. Use o grafo de deadlock do SQL Server (capturado por meio de Eventos Estendidos ou da sessão de integridade do sistema) para identificar as instruções em conflito e os tipos de bloqueio. Para um guia completo de análise e prevenção de bloqueios, veja o guia Deadlocks. Para estratégias de tratamento de deadlocks específicas para transações, veja Tratamento de deadlocks.

Lidar com o esgotamento do pool de conexões

Quando todas as conexões no pool estiverem em uso e MaxOpenConns for atingido, novas chamadas ficarão bloqueadas até que uma conexão fique disponível ou o prazo do contexto se esgote. Essa situação se manifesta como requisições lentas ou erros de prazo de contexto, não como erros explícitos de esgotamento de pool.

Detectar pressão da piscina

Monitore as estatísticas do pool e alerte quando o número de espera aumentar.

func monitorPool(ctx context.Context, db *sql.DB) {
    ticker := time.NewTicker(10 * time.Second)
    defer ticker.Stop()

    var lastWaitCount int64
    for {
        select {
        case <-ctx.Done():
            return
        case <-ticker.C:
            stats := db.Stats()
            newWaits := stats.WaitCount - lastWaitCount
            lastWaitCount = stats.WaitCount

            if newWaits > 0 {
                log.Printf("Pool pressure: open=%d inUse=%d idle=%d newWaits=%d waitDuration=%v",
                    stats.OpenConnections, stats.InUse, stats.Idle,
                    newWaits, stats.WaitDuration)
            }
        }
    }
}

Causas e soluções comuns

Lidar com erros específicos do SQL Server

Violações de restrições

Violações de chave única e chave estrangeira são erros permanentes que indicam um problema lógico na aplicação:

func isUniqueViolation(err error) bool {
    var mssqlErr mssql.Error
    if errors.As(err, &mssqlErr) {
        return mssqlErr.Number == 2627 || // Unique constraint violation
            mssqlErr.Number == 2601       // Unique index violation
    }
    return false
}

func isForeignKeyViolation(err error) bool {
    var mssqlErr mssql.Error
    if errors.As(err, &mssqlErr) {
        return mssqlErr.Number == 547 // FK constraint violation
    }
    return false
}

Padrão upsert com detecção de conflito

Use a instrução MERGE para inserir ou atualizar uma linha atomicamente:

func upsertDepartment(ctx context.Context, db *sql.DB, id int, name, groupName string) error {
    _, err := db.ExecContext(ctx, `
        MERGE INTO HumanResources.Department AS target
        USING (SELECT @id AS DepartmentID, @name AS Name, @grp AS GroupName) AS source
        ON target.DepartmentID = source.DepartmentID
        WHEN MATCHED THEN
            UPDATE SET Name = source.Name, GroupName = source.GroupName
        WHEN NOT MATCHED THEN
            INSERT (Name, GroupName) VALUES (source.Name, source.GroupName);`,
        sql.Named("id", id),
        sql.Named("name", name),
        sql.Named("grp", groupName))
    return err
}

Erros de permissão

Detectar códigos de erro comuns de permissão negada para fornecer uma mensagem clara ao chamador:

func isPermissionError(err error) bool {
    var mssqlErr mssql.Error
    if errors.As(err, &mssqlErr) {
        return mssqlErr.Number == 229 ||   // SELECT permission denied
            mssqlErr.Number == 230 ||       // Column permission denied
            mssqlErr.Number == 262 ||       // CREATE permission denied
            mssqlErr.Number == 300 ||       // VIEW permission denied
            mssqlErr.Number == 15247        // User doesn't have permission
    }
    return false
}

Tratar sql.ErrNoRows

sql.ErrNoRowsnão é um erro do SQL Server. O método QueryRowContext.Scan o retorna quando a consulta não retorna nenhuma linha. Manuse-o explicitamente para distinguir "não encontrado" de erros reais:

func getEmployee(ctx context.Context, db *sql.DB, id int) (*Employee, error) {
    var emp Employee
    err := db.QueryRowContext(ctx,
        "SELECT TOP (1) BusinessEntityID, FirstName + ' ' + LastName AS Name, CountryRegionName AS Location FROM Sales.vSalesPerson WHERE BusinessEntityID = @p1",
        sql.Named("p1", id)).Scan(&emp.Id, &emp.Name, &emp.Location)

    if errors.Is(err, sql.ErrNoRows) {
        return nil, nil // Not found, not an error.
    }
    if err != nil {
        return nil, fmt.Errorf("query employee %d: %w", id, err)
    }
    return &emp, nil
}

Encapsule erros com contexto

Adicione contexto aos erros para que os chamadores possam entender onde ocorreu a falha:

func getEmployeesByLocation(ctx context.Context, db *sql.DB, location string) ([]Employee, error) {
    rows, err := db.QueryContext(ctx,
        "SELECT BusinessEntityID, FirstName + ' ' + LastName AS Name, CountryRegionName AS Location FROM Sales.vSalesPerson WHERE CountryRegionName = @p1",
        sql.Named("p1", location))
    if err != nil {
        return nil, fmt.Errorf("query employees by location %q: %w", location, err)
    }
    defer rows.Close()

    var employees []Employee
    for rows.Next() {
        var emp Employee
        if err := rows.Scan(&emp.Id, &emp.Name, &emp.Location); err != nil {
            return nil, fmt.Errorf("scan employee row: %w", err)
        }
        employees = append(employees, emp)
    }
    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("iterate employee rows: %w", err)
    }
    return employees, nil
}

Usar %w preserva a cadeia de erros para que os chamadores ainda possam usar errors.As e errors.Is inspecionar o erro subjacente.

Lista de verificação para o tratamento de erros

Conteúdo relacionado

• Transações
• Agrupamento de conexões
• Solução de problemas
• Otimização do desempenho