Logica en verbindingstolerantie opnieuw proberen met mssql-django

Verbindingen met SQL Server en Azure SQL kunnen tijdelijk mislukken om redenen die niets te maken hebben met uw code:

• Een AlwaysOn-beschikbaarheidsgroep voert een failover uit.
• Het netwerk laat een pakket vallen tijdens het instellen van de verbinding.
• Resource Governor beperkt de databaseprestaties.
• Een Azure SQL-replica wordt opnieuw geïnitialiseerd tijdens het schalen of bij een upgrade.

De meeste van deze fouten zijn binnen enkele seconden duidelijk. In dit artikel wordt beschreven hoe u in een Django-toepassing die gebruikmaakt van de mssql-django-backend, opnieuw kunt proberen na tijdelijke fouten, en hoe u Django en het ODBC-stuurprogramma configureert om automatisch te herstellen na verbindingsverbrekingen door inactiviteit.

Tijdelijke fouten

Tijdelijke fouten zijn tijdelijke fouten die zelfstandig worden opgelost. Het opnieuw proberen van de bewerking na een korte vertraging slaagt meestal.

De volgende fouten zijn tijdelijk wanneer ze optreden tijdens het tot stand komen van de verbinding of tijdens het verzenden van een aanvraag naar de server. Probeer het na een korte, begrensde wachttijd opnieuw. Fouten die zich na enkele nieuwe pogingen voordoen, geven meestal een configuratieprobleem aan (verkeerde server, ontbrekende machtigingen, uitgeput quotum) die opnieuw proberen niet worden opgelost.

Fouten op instructieniveau staan niet in deze lijst, omdat ze optreden nadat de verbinding tot stand is gekomen en de sessie na de fout bruikbaar blijft. De meest voorkomende fouten in opnieuw uit te voeren instructies zijn 1205 (deadlockslachtoffer) en 1222 (time-out bij een vergrendelingsaanvraag). Voer de hele transactie opnieuw uit in plaats van de enkele mislukte instructie.

De tekst van het foutbericht is afkomstig van Azure SQL tijdelijke verbindingsfouten. Afzonderlijke stuurprogramma's onderhouden hun eigen ingebouwde lijsten voor nieuwe pogingen; in deze catalogus wordt beschreven welke fouten in aanmerking komen voor nieuwe pogingen in SQL Server, Azure SQL Database, Azure SQL Managed Instance, SQL-database in Microsoft Fabric en toegewezen SQL-pools in Azure Synapse Analytics.

Veerkracht van inactieve verbindingen van het ODBC-stuurprogramma

Het Microsoft ODBC-stuurprogramma voor SQL Server biedt ingebouwde niet-actieve verbindingstolerantie via de ConnectRetryCount trefwoorden en ConnectRetryInterval verbindingsreeks trefwoorden. Deze instellingen verwerken verbroken inactieve verbindingen op stuurprogrammaniveau voordat uw toepassingscode wordt betrokken.

Niet-actieve verbindingstolerantie inschakelen 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-database-middleware voor nieuwe pogingen

Maak een Django-middleware die tijdelijke fouten onderschept en de databasebewerking opnieuw probeert uit te voeren. Deze aanpak werkt voor het verwerken van aanvragen op weergaveniveau:

# 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

Registreer de middleware in settings.py:

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

Decorator opnieuw proberen voor specifieke bewerkingen

Gebruik voor fijnmazige controle een decorator voor afzonderlijke functies:

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

Pas de decorator toe op database-intensieve functies:

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

Opnieuw proberen met transacties

Wanneer er een tijdelijke fout optreedt in een transactie, wordt de hele transactie teruggedraaid door de server. Voer de volledige transactie opnieuw uit, niet alleen de mislukte instructie:

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

Fouten op instructieniveau

De foutenlijst in de vorige sectie bevat fouten op verbindingsniveau. Twee andere fouten worden vaak opnieuw uitgevoerd op statementniveau:

• 1205: De sessie werd aangewezen als het deadlock-slachtoffer. Voer de transactie opnieuw uit.
• 1222: Er is een time-out voor vergrendelingsaanvragen overschreden. Voer de transactie opnieuw uit of verhoog LOCK_TIMEOUT voor de sessie als de standaardwaarde te agressief is.

ConnectRetryCount probeert verbroken verbindingen opnieuw, dus dit is niet van toepassing op deze fouten op opdrachtniveau. Verwerk ze met hetzelfde decoratorpatroon door "1205" en "1222" toe te voegen aan TRANSIENT_ERROR_CODES voor transacties die veilig opnieuw kunnen worden uitgevoerd.

CONN_MAX_AGE en verouderde verbindingen

Django hergebruikt databaseverbindingen tussen aanvragen wanneer CONN_MAX_AGE deze is ingesteld. Een langlevende verbinding kan verouderen als de server deze sluit (bijvoorbeeld tijdens een Azure SQL-schaalactie of een firewalltime-out).

Ingesteld CONN_MAX_AGE op evenwicht tussen hergebruik en veroudering:

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 (standaard): Sluit de verbinding aan het einde van elke aanvraag. Veiligste maar langzaamste.
• CONN_MAX_AGE=600: Verbindingen gedurende 10 minuten opnieuw gebruiken. Goede balans voor de meeste webtoepassingen.
• CONN_MAX_AGE=None: Houd verbindingen voor onbepaalde tijd open. Alleen gebruiken met een mechanisme om verouderde verbindingen opnieuw te proberen.

CONN_HEALTH_CHECKS (Django 4.1 en hoger)

Django 4.1 geïntroduceerd CONN_HEALTH_CHECKS, waarmee een opnieuw gebruikte verbinding wordt gevalideerd voor elke aanvraag. Schakel dit samen met CONN_MAX_AGE in om verouderde verbindingen automatisch te detecteren:

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

Als statuscontroles zijn ingeschakeld, geeft Django een lichtgewicht validatiequery uit voordat een verbinding opnieuw wordt gebruikt. Als de verbinding verbroken is, opent Django transparant een nieuwe in plaats van een fout op te geven.

Beste praktijken

• Gebruik exponentiële back-off met volledige jitter. Verdubbel bij elke poging de limiet en wacht vervolgens een willekeurige tijd binnen [0, cap]. Jitter voorkomt dat veel clients tijdens een regionale storing gelijktijdig opnieuw proberen, wat anders een kortdurende storing kan doen uitgroeien tot aanhoudende overbelasting. Beperk de slaapstand per poging (bijvoorbeeld 30 seconden), zodat de totale hersteltijd gebonden blijft.
• Stel een plafond voor opnieuw proberen in. Drie herpogingen met exponentiële wachttijd is een redelijke standaardinstelling. Meer dan vijf nieuwe pogingen duiden meestal op een niet-tijdelijk probleem.
• Sluit de verbinding voordat u het opnieuw probeert. Bel connection.close() zodat Django een nieuwe verbinding opent bij de volgende poging.
• Registreer elke nieuwe poging. Herhaalde pogingen die ongemerkt slagen, kunnen prestatieproblemen verbergen. Meld u aan op WARNING niveau zodat u de frequentie kunt bijhouden.
• Probeer niet opnieuw niet-tijdelijke fouten. Verificatiefouten, machtigingsfouten en syntaxisfouten profiteren niet van nieuwe pogingen.
• Voer de hele transactie opnieuw uit. Plaats transaction.atomic() binnen de retrylogica, niet andersom.
• Inschakelen CONN_HEALTH_CHECKS (Django 4.1 en hoger) voor webtoepassingen die gebruikmaken van CONN_MAX_AGE.

Verwante inhoud

• Verbindingsopties voor mssql-django
• Groepsgewijze verbindingen in mssql-django
• Transactiebeheer in mssql-django
• Prestaties afstemmen voor mssql-django
• Problemen met mssql-django oplossen