Fehlerbehandlung und Wiederholungsmuster mit go-mssqldb

Production Go-Anwendungen benötigen strukturierte Fehlerbehandlung, um zwischen vorübergehenden Fehlern, die man erneut versuchen kann, und dauerhaften Fehlern, die menschliches Eingreifen erfordern, zu unterscheiden. Dieser Artikel behandelt Fehlerklassifikation, Wiederholungsmuster und Strategien zur Resilienz des Fahrers go-mssqldb .

SQL Server-Fehlerstruktur

Wenn SQL Server einen Fehler zurückgibt, umwickelt der Treiber go-mssqldb ihn in eine mssql.Error Struktur. Verwenden Sie eine Typ-Assertion, um auf die strukturierten Fehlerfelder zuzugreifen:

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)
    }
}

Fehlerfelder

Schweregrade

Fehler als vorübergehend oder dauerhaft klassifizieren

Transiente Fehler sind temporäre Zustände, die sich von selbst lösen, wie Netzwerkstörungen, Verbindungsdrosselung oder kurzfristige Ressourcenbeschränkungen. Dauerhafte Fehler erfordern Code- oder Konfigurationsänderungen.

Häufige Transientenfehlerzahlen

Verwenden Sie den folgenden gemeinsamen Katalog als kanonische Liste von transienten Verbindungs- und Anfragepfad-Transportfehlern:

Die folgenden Fehler sind vorübergehend, wenn sie während der Verbindungseinrichtung oder beim Senden einer Anforderung an den Server auftreten. Versuchen Sie es mit einem kurzen, begrenzten Backoff. Fehler, die über einige Wiederholungen bestehen, weisen in der Regel auf ein Konfigurationsproblem hin (falscher Server, fehlende Berechtigungen, erschöpftes Kontingent), das nicht behoben werden kann.

Fehler auf Anweisungsebene befinden sich nicht in dieser Liste, da sie ausgelöst werden, nachdem die Verbindung hergestellt wurde und der Fehler die Sitzung nutzbar lässt. Die häufigsten Fehler bei Anweisungen, die erneut ausgeführt werden können, sind 1205 (Deadlock-Opfer) und 1222 (Zeitüberschreitung bei der Sperranforderung). Wiederholen Sie die gesamte Transaktion statt der einzelnen fehlerhaften Anweisung.

Fehlermeldungstext stammt aus Azure SQL vorübergehenden Verbindungsfehlern. Einzelne Treiber verwalten ihre eigenen integrierten Wiederholungslisten; in diesem Katalog wird beschrieben, welche Fehler in SQL Server, Azure SQL-Datenbank, Azure SQL Managed Instance, SQL-Datenbank in Microsoft Fabric und dedizierten SQL-Pools in Azure Synapse Analytics für Wiederholungen geeignet sind.

Die folgende isTransient Funktion zeigt ein Implementierungsmuster in Go für die Klassifizierung von Wiederholungsversuchen. Behandle den oben stehenden gemeinsamen Katalog als maßgebliche Quelle und richte deinen Codeabgleich danach aus.

// 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
}

Wenn du Konfigurations- und Quotenfehler bemerkst, korrigiere die zugrunde liegende Kapazität, Datenbank oder Netzwerkkonfiguration, bevor du es erneut versuchst. Beispiele sind:

• 40544 (Datenbankgrößenquote)
• 4060 (Datenbank kann nicht geöffnet werden)
• 40615 (Firewall-Regel)

Netzwerkfehler erkennen

Fehler auf Netzwerkebene erzeugen keine mssql.Error Werte. Überprüfen Sie häufige Fehlertypen im Go-Netzwerk:

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
}

Retry mit exponentiellem Backoff implementieren

Versuchen Sie vorübergehende Fehler mit zunehmenden Verzögerungen zwischen den Versuchen erneut. Dieser Ansatz gibt dem Server Zeit zur Erholung und vermeidet eine Überforderung durch schnelle Rückversuche.

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)
}

Deadlocks beheben

Deadlocks (Fehler 1205) sind der häufigste vorübergehende Fehler in Mehrbenutzeranwendungen. SQL Server beendet automatisch eine der konkurrierenden Sitzungen und gibt dem Opfer Fehler 1205 zurück.

Einen Deadlock erkennen

Überprüfen Sie, ob ein SQL Server-Fehler ein Deadlock ist (Fehler 1205).

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

Transaktionen nach einem Deadlock wiederholen

Wenn innerhalb einer Transaktion ein Deadlock auftritt, rollt der Server die gesamte Transaktion zurück. Sie müssen die vollständige Transaktion erneut versuchen, nicht nur die fehlgeschlagene Aussage:

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

Ein erneuter Versuch ist die korrekte Antwort im Anwendungscode, aber wiederholte Deadlocks bei derselben Abfrage deuten auf ein Designproblem hin. Verwenden Sie das SQL Server-Deadlockdiagramm (erfasst über Extended Events oder die Sitzung „system_health“), um die konkurrierenden Anweisungen und Sperrtypen zu identifizieren. Eine vollständige Anleitung zur Analyse und Vermeidung von Deadlocks finden Sie im Deadlocks-Leitfaden. Für Deadlock-Handlingsstrategien, die spezifisch für Transaktionen sind, siehe Deadlock-Handling.

Erschöpfung des Verbindungspools behandeln

Wenn alle Verbindungen im Pool belegt sind und MaxOpenConns erreicht ist, blockieren neue Aufrufer, bis eine Verbindung verfügbar wird oder das Zeitlimit des Kontexts abläuft. Diese Situation zeigt sich in Form von langsamen Anfragen oder Context-Deadline-Fehlern, nicht als explizite Fehler wegen Erschöpfung des Pools.

Pooldruck erkennen

Überwachen Sie die Pool-Statistiken und benachrichtigen Sie, wenn die Wartezahlen steigen.

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)
            }
        }
    }
}

Häufige Ursachen und Lösungen

Handhabung spezifischer SQL Server-Fehler

Verstöße gegen Einschränkungen

Verstöße gegen eindeutige Schlüssel und Fremdschlüssel sind permanente Fehler, die auf ein logisches Problem in der Anwendung hinweisen:

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
}

Upsert-Muster mit Konflikterkennung

Verwenden Sie eine MERGE Anweisung, um eine Zeile atomar einzufügen oder zu aktualisieren:

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
}

Berechtigungsfehler

Erkennen Sie häufige Fehlernummern mit verweigerten Berechtigungen, um den Anrufern eine klare Nachricht zu geben:

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
}

Kümmere dich um SQL. ErrNoRows

sql.ErrNoRowsist kein SQL Server-Fehler. Die Methode QueryRowContext.Scan gibt sie zurück, wenn die Abfrage keine Zeilen zurückgibt. Behandle es explizit, um "nicht gefunden" von tatsächlichen Fehlern zu unterscheiden:

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
}

Fehler mit Kontext umwickeln

Fügen Sie den Fehlern Kontext hinzu, damit die Anrufer verstehen, wo der Fehler aufgetreten ist:

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
}

Die Verwendung von %w bewahrt die Fehlerkette, sodass Aufrufer weiterhin errors.As und errors.Is verwenden können, um den zugrunde liegenden Fehler zu untersuchen.

Fehlerbehandlungs-Checkliste

Verwandte Inhalte

• Transaktionen
• Verbindungspooling
• Problembehandlung
• Leistungsoptimierung