Wiederholungslogik und Verbindungsresilienz mit mssql-django

Verbindungen mit SQL Server und Azure SQL können vorübergehend aus Gründen fehlschlagen, die nichts mit Ihrem Code zu tun haben:

• Eine AlwaysOn-Verfügbarkeitsgruppe schlägt fehl.
• Das Netzwerk legt während der Verbindungseinrichtung ein Paket ab.
• Resource Governor drosselt die Datenbank.
• Ein Azure SQL Replikat wird während einer Skalierung oder eines Upgrades wiederverwendet.

Die meisten dieser Fehler werden innerhalb von Sekunden gelöscht. In diesem Artikel wird gezeigt, wie Sie vorübergehende Fehler in einer Django-Anwendung wiederholen, die das mssql-django Back-End verwendet, und wie Sie Django und den ODBC-Treiber so konfigurieren, dass die Wiederherstellung von Leerlaufverbindungsabbrüchen automatisch erfolgt.

Vorübergehende Fehler

Vorübergehende Fehler sind temporäre Fehler, die eigenständig aufgelöst werden. Ein erneuter Versuch des Vorgangs nach einer kurzen Verzögerung ist in der Regel erfolgreich.

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.

Resilienz von Leerlaufverbindungen des ODBC-Treibers

Der Microsoft ODBC-Treiber für SQL Server bietet integrierte Resilienz bei Leerlaufverbindungen durch die Schlüsselwörter ConnectRetryCount und ConnectRetryInterval der Verbindungszeichenfolge. Diese Einstellungen verwalten unterbrochene Leerlaufverbindungen auf Treiberebene, bevor Ihr Anwendungscode ins Spiel kommt.

Aktivieren sie die Ausfallsicherheit der Leerlaufverbindung in extra_params:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "ConnectRetryCount=3;ConnectRetryInterval=10",
        },
    },
}

Django-Datenbank-Middleware für Wiederholungsversuche

Erstellen Sie eine Django-Middleware, die vorübergehende Fehler abfangen und den Datenbankvorgang erneut überprüft. Dieser Ansatz funktioniert für die Verarbeitung von Anforderungen auf Ansichtsebene:

# myproject/middleware.py
import random
import re
import time
import logging
from django.db import OperationalError, connection

logger = logging.getLogger(__name__)

TRANSIENT_ERROR_CODES = {
    "64", "233", "4221",
    "10053", "10054", "10928", "10929",
    "40197", "40501", "40613",
    "49918", "49919", "49920",
    # Include "4060" only if targeting Azure SQL with geo-replication failover.
    # It is usually a permanent error (wrong database name or missing permissions).
}

# Microsoft ODBC driver formats native error codes as "(<number>)" in the
# message. Extracting parenthesized codes avoids false positives that a plain
# substring match would produce for short codes like "64".
_CODE_RE = re.compile(r"\((\d+)\)")


def is_transient(error):
    codes_in_message = set(_CODE_RE.findall(str(error)))
    return bool(codes_in_message & TRANSIENT_ERROR_CODES)


class DatabaseRetryMiddleware:
    """Retry database operations on transient errors."""

    def __init__(self, get_response):
        self.get_response = get_response
        self.max_retries = 3
        self.base_delay = 1   # seconds; doubled each attempt
        self.max_delay = 30   # cap on a single sleep, regardless of attempt

    def __call__(self, request):
        for attempt in range(self.max_retries + 1):
            try:
                return self.get_response(request)
            except OperationalError as e:
                if attempt < self.max_retries and is_transient(e):
                    # Exponential backoff with full jitter, capped at max_delay.
                    # Jitter spreads simultaneous retries so many clients
                    # don't hammer the server in lock-step during an outage.
                    capped = min(self.max_delay, self.base_delay * (2 ** attempt))
                    delay = random.uniform(0, capped)
                    logger.warning(
                        "Transient DB error (attempt %d/%d), retrying in %.2fs: %s",
                        attempt + 1, self.max_retries, delay, e
                    )
                    connection.close()
                    time.sleep(delay)
                    continue
                raise

Registrieren Sie die Middleware in settings.py:

MIDDLEWARE = [
    "myproject.middleware.DatabaseRetryMiddleware",
    "django.middleware.security.SecurityMiddleware",
    # ... other middleware
]

Retry-Decorator für bestimmte Vorgänge

Verwenden Sie für feinkörnige Steuerung einen Dekorateur für einzelne Funktionen:

import random
import re
import time
import functools
import logging
from django.db import OperationalError, connection

logger = logging.getLogger(__name__)

TRANSIENT_ERROR_CODES = {
    "64", "233", "4221",
    "10053", "10054", "10928", "10929",
    "40197", "40501", "40613",
    "49918", "49919", "49920",
    # Include "4060" only if targeting Azure SQL with geo-replication failover.
}

_CODE_RE = re.compile(r"\((\d+)\)")


def is_transient(error):
    codes_in_message = set(_CODE_RE.findall(str(error)))
    return bool(codes_in_message & TRANSIENT_ERROR_CODES)


def retry_on_transient(max_retries=3, base_delay=1, max_delay=30):
    """Retry on transient database errors with exponential backoff and full jitter."""

    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries + 1):
                try:
                    return func(*args, **kwargs)
                except OperationalError as e:
                    if attempt < max_retries and is_transient(e):
                        # Exponential cap doubled per attempt, then jittered
                        # within [0, cap] and limited by max_delay.
                        capped = min(max_delay, base_delay * (2 ** attempt))
                        delay = random.uniform(0, capped)
                        logger.warning(
                            "Transient error in %s (attempt %d/%d), retrying in %.2fs: %s",
                            func.__name__, attempt + 1, max_retries, delay, e
                        )
                        connection.close()
                        time.sleep(delay)
                        continue
                    raise
        return wrapper
    return decorator

Wenden Sie den Dekorierer auf datenbankintensive Funktionen an:

from myproject.retry import retry_on_transient

@retry_on_transient(max_retries=3, base_delay=2)
def process_order(order_id):
    """Process an order with automatic retry on transient failures."""
    order = Order.objects.select_for_update().get(id=order_id)
    order.status = "processing"
    order.save()
    return order

Wiederholen von Transaktionen

Wenn innerhalb einer Transaktion ein vorübergehender Fehler auftritt, wird die gesamte Transaktion vom Server zurückgesetzt. Wiederholen Sie die vollständige Transaktion, nicht nur die fehlgeschlagene Anweisung:

from django.db import transaction

@retry_on_transient(max_retries=3)
def transfer_funds(from_account_id, to_account_id, amount):
    """Transfer funds between accounts with retry."""
    with transaction.atomic():
        from_account = Account.objects.select_for_update().get(id=from_account_id)
        to_account = Account.objects.select_for_update().get(id=to_account_id)

        from_account.balance -= amount
        to_account.balance += amount

        from_account.save()
        to_account.save()

Fehler auf Aussageebene

Die Fehlerliste im vorherigen Abschnitt behandelt Fehler auf Verbindungsebene. Zwei weitere Fehler werden häufig auf Anweisungsebene wiederholt:

• 1205: Die Sitzung wurde als Deadlock-Opfer ausgewählt. Führen Sie die Transaktion erneut aus.
• 1222: Ein Timeout für Sperranforderungen wurde überschritten. Führen Sie die Transaktion erneut aus, oder erhöhen Sie LOCK_TIMEOUT für die Sitzung, wenn der Standardwert zu aggressiv ist.

ConnectRetryCount wiederholt Verbindungsversuche bei unterbrochenen Verbindungen und gilt daher nicht für diese Fehler auf Anweisungsebene. Behandeln Sie sie mit demselben Decorator-Muster, indem Sie "1205" und "1222" zu TRANSIENT_ERROR_CODES für Transaktionen hinzufügen, die sicher erneut ausgeführt werden können.

CONN_MAX_AGE und veraltete Verbindungen

Django verwendet Datenbankverbindungen über Anforderungen hinweg, wenn CONN_MAX_AGE festgelegt wird. Eine langlebige Verbindung kann veraltet werden, wenn der Server sie schließt (z. B. während eines Azure SQL Skalierungsvorgangs oder eines Firewalltimeouts).

Legen Sie CONN_MAX_AGE fest, dass die Wiederverwendung gegen Veraltetkeit ausgeglichen wird:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
        "CONN_MAX_AGE": 600,  # Close and reopen connections after 10 minutes
    },
}

• CONN_MAX_AGE=0 (Standard): Schließen Sie die Verbindung am Ende jeder Anforderung. Sicherste, aber langsamste.
• CONN_MAX_AGE=600: Verbindungen 10 Minuten lang wiederverwenden. Gute Balance für die meisten Webanwendungen.
• CONN_MAX_AGE=None: Lassen Sie Verbindungen unbegrenzt geöffnet. Wird nur mit einem Wiederholungsmechanismus für veraltete Verbindungen verwendet.

CONN_HEALTH_CHECKS (Django 4.1 und höher)

Django 4.1 führte CONN_HEALTH_CHECKS ein, das eine wiederverwendete Verbindung vor jeder Anfrage überprüft. Aktivieren Sie es zusammen mit CONN_MAX_AGE, um inaktive Verbindungen automatisch zu erkennen:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>.database.windows.net",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
        "CONN_MAX_AGE": 600,
        "CONN_HEALTH_CHECKS": True,
    },
}

Mit aktivierten Integritätsprüfungen gibt Django eine einfache Überprüfungsabfrage aus, bevor eine Verbindung erneut verwendet wird. Wenn die Verbindung unterbrochen wird, öffnet Django transparent eine neue, anstatt einen Fehler zu auslösen.

Bewährte Methoden

• Verwenden Sie exponentielles Backoff mit vollständigem Jitter. Verdoppeln Sie bei jedem Versuch die Obergrenze und warten Sie dann eine zufällige Zeitspanne innerhalb von [0, cap]. Jitter verhindert, dass viele Clients bei einem regionalen Ausfall gleichzeitig Wiederholungsversuche unternehmen, was andernfalls einen kurzzeitigen Ausfall in eine anhaltende Überlastung verwandeln kann. Begrenzen Sie die Wartezeit pro Versuch (z. B. 30 Sekunden), sodass die gesamte Wiederherstellungszeit begrenzt bleibt.
• Legen Sie eine Wiederholungsgrenze fest. Drei Wiederholungen mit exponentiellem Backoff sind ein vernünftiger Standardwert. Mehr als fünf Wiederholungsversuche deuten in der Regel auf ein nichttransientes Problem hin.
• Schließen Sie die Verbindung, bevor Sie den Vorgang wiederholen. Rufen Sie connection.close() auf, damit Django beim nächsten Versuch eine neue Verbindung öffnet.
• Protokollieren Sie jeden Wiederholungsversuch. Wiederholungsversuche, die stillschweigend erfolgreich sind, können Leistungsprobleme verschleiern. Protokollieren Sie auf WARNING-Ebene, damit Sie die Häufigkeit verfolgen können.
• Keine erneuten Versuche bei nicht vorübergehenden Fehlern. Authentifizierungsfehler, Berechtigungsfehler und Syntaxfehler profitieren nicht von Wiederholungen.
• Wiederholen Sie die gesamte Transaktion. Schließen Sie transaction.atomic() in die Wiederholungslogik ein, nicht andersherum.
• Aktivieren CONN_HEALTH_CHECKS (Django 4.1 und höher) für Webanwendungen, die CONN_MAX_AGE verwenden.

Verwandte Inhalte

• Verbindungsoptionen für mssql-django
• Verbindungs-Pooling in mssql-django
• Transaktionsverwaltung in mssql-django
• Leistungsoptimierung für mssql-django
• Problembehandlung bei mssql-django