Logique de réessai et résilience de connexion avec mssql-python

Les pannes transitoires sont des erreurs temporaires qui peuvent survenir lors de la connexion à SQL Server et Azure SQL via le pilote mssql-python. Ces erreurs se résolvent souvent d’elles-mêmes :

• Brèves interruptions de la connectivité réseau.
• Contraintes de ressources serveur.
• Azure SQL throttling.
• Événements de basculement.

La mise en œuvre de la logique de réessayage améliore la fiabilité des applications, en particulier pour les bases de données hébergées dans le cloud.

N’utilisez pas de retentatives pour masquer des erreurs de configuration ou de codage. Une base de données manquante, de mauvaises identifiantes ou un pool de connexion épuisé nécessitent une correction, pas une nouvelle tentative.

Identifier les erreurs transitoires

MSSQL-Python n'expose pas le numéro d'erreur du moteur SQL Server comme un attribut sur les exceptions. À la place, le pilote associe les codes SQLSTATE à un ensemble fixe de sous-classes d’exception PEP 249 (OperationalError, ProgrammingError, etc.) et à un texte anglais standardisé dans l’attribut driver_error . Utilisez cette combinaison comme base pour la classification des transitoires.

Signaux transitoires fiables

Les valeurs SQLSTATE suivantes sont renvoyées sous la forme OperationalError et indiquent une condition qui mérite une nouvelle tentative. La colonne de droite montre le texte exact driver_error défini par le conducteur :

SQLSTATE	driver_error texte	Pathologie
HYT00	Timeout expired	Délai d’expiration au niveau de l’instruction.
HYT01	Connection timeout expired	Délai d’attente de connexion.
08001	Client unable to establish connection	Impossible d’ouvrir une connexion.
08S01	Communication link failure	Coupure réseau, réinitialisation du serveur, défaillance TCP.
08007	Connection failure during transaction	Connexion perdue en plein milieu de la transaction.
40001	Serialization failure	Victime d’interblocage.
40003	Statement completion unknown	État de transaction indéterminé.

import mssql_python


TRANSIENT_DRIVER_ERRORS = frozenset({
    "Timeout expired",
    "Connection timeout expired",
    "Client unable to establish connection",
    "Communication link failure",
    "Connection failure during transaction",
    "Serialization failure",
    "Statement completion unknown",
})


def is_transient_error(error: BaseException) -> bool:
    """Return True if the exception represents a retryable transient failure.

    Classification is based on the driver's PEP 249 exception subclass and
    on the standardized `driver_error` text that mssql-python sets from
    the SQLSTATE returned by the server.
    """
    if isinstance(error, mssql_python.OperationalError):
        return getattr(error, "driver_error", "") in TRANSIENT_DRIVER_ERRORS
    return False

Limitation du débit Azure SQL (au mieux)

Les erreurs de limitation du débit d’Azure SQL (40197, 40501, 40613, 49918, 49919, 49920 et les codes associés) sont généralement accompagnées du code SQLSTATE 42000, que mssql-python mappe sur ProgrammingError. Le numéro d’erreur moteur n’apparaît pas en tant qu’attribut, donc le seul signal est le texte du message serveur dans l’attribut ddbc_error .

Si votre charge de travail s’exécute sur Azure SQL et que vous devez réessayer après une limitation du débit, parcourez ddbc_error pour trouver le numéro connu. C’est le meilleur effort car le format du texte côté serveur n’est pas un contrat stable :

import re

# Azure SQL throttling and reconfiguration error numbers.
AZURE_THROTTLING_ERRORS = frozenset({
    40197, 40501, 40540, 40613, 40680, 49918, 49919, 49920, 10928, 10929,
})

_ERROR_NUMBER_RE = re.compile(r"\b(?:Error|Msg)\s+(\d+)\b")


def is_azure_throttling(error: BaseException) -> bool:
    """Best-effort detection of Azure SQL throttling in ProgrammingError text."""
    if not isinstance(error, mssql_python.ProgrammingError):
        return False
    ddbc_text = getattr(error, "ddbc_error", "") or ""
    return any(int(m) in AZURE_THROTTLING_ERRORS for m in _ERROR_NUMBER_RE.findall(ddbc_text))


def is_retryable(error: BaseException) -> bool:
    return is_transient_error(error) or is_azure_throttling(error)

Ce qu’il ne faut pas retenter

Des exemples d’erreurs qui devraient échouer rapidement au lieu de réessayer incluent des identifiants invalides (OperationalError avec texte Invalid authorization specificationdu pilote), une base de données manquante ou inaccessible, des erreurs de syntaxe (ProgrammingError), des objets manquants et l’épuisement du pool de connexion. La is_transient_error fonction ci-dessus exclut toutes ces catégories par construction.

Décorateur de base pour les essais

Une simple réessaie avec un délai fixe

Un décorateur qui réessaie d’exécuter la fonction encapsulée un nombre fixe de fois avec un délai constant :

import time
import functools
import mssql_python

def retry_on_failure(max_retries: int = 3, delay: float = 1.0):
    """Decorator to retry database operations on transient failures."""
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            last_exception = None
            for attempt in range(max_retries + 1):
                try:
                    return func(*args, **kwargs)
                except mssql_python.Error as e:
                    last_exception = e
                    if not is_transient_error(e) or attempt == max_retries:
                        raise
                    print(f"Attempt {attempt + 1} failed: {e}. Retrying in {delay}s...")
                    time.sleep(delay)
            raise last_exception
        return wrapper
    return decorator

# Usage
@retry_on_failure(max_retries=3, delay=2.0)
def get_user(cursor, user_id: int):
    cursor.execute("SELECT * FROM Person.Person WHERE BusinessEntityID = %(id)s", {"id": user_id})
    return cursor.fetchone()

Backoff exponentiel

Augmentez de façon exponentielle le délai entre les tentatives avec un jitter optionnel pour étaler les tentatives simultanées :

import time
import random

def retry_with_backoff(max_retries: int = 5, 
                       base_delay: float = 1.0,
                       max_delay: float = 30.0,
                       jitter: bool = True):
    """Retry with exponential backoff and optional jitter."""
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            last_exception = None
            for attempt in range(max_retries + 1):
                try:
                    return func(*args, **kwargs)
                except mssql_python.Error as e:
                    last_exception = e
                    if not is_transient_error(e) or attempt == max_retries:
                        raise
                    
                    # Calculate delay with exponential backoff
                    delay = min(base_delay * (2 ** attempt), max_delay)
                    if jitter:
                        delay = delay * (0.5 + random.random())
                    
                    print(f"Attempt {attempt + 1} failed. Retrying in {delay:.2f}s...")
                    time.sleep(delay)
            raise last_exception
        return wrapper
    return decorator

@retry_with_backoff(max_retries=5, base_delay=1.0, max_delay=30.0)
def execute_query(cursor, query: str, params: dict):
    cursor.execute(query, params)
    return cursor.fetchall()

Classe de tentative de connexion

Gestionnaire de connexion résilient

Un envelopper de connexion qui gère à la fois la reprise et la reconnexion automatique :

import mssql_python
import time
import logging

# This example uses is_transient_error from the "Identify transient errors"
# section earlier in this article. Include that helper in your module.

# Configure logging so the retry and reconnect messages are visible
logging.basicConfig(level=logging.INFO)

class ResilientConnection:
    """Connection wrapper with automatic retry and reconnection."""
    
    def __init__(self, connection_string: str, max_retries: int = 5,
                 base_delay: float = 1.0, max_delay: float = 60.0):
        self.connection_string = connection_string
        self.max_retries = max_retries
        self.base_delay = base_delay
        self.max_delay = max_delay
        self._conn = None
        self._logger = logging.getLogger(__name__)
    
    def _connect(self) -> mssql_python.Connection:
        """Establish connection with retry logic."""
        last_exception = None
        
        for attempt in range(self.max_retries + 1):
            try:
                self._logger.debug(f"Connection attempt {attempt + 1}")
                return mssql_python.connect(self.connection_string)
            except mssql_python.Error as e:
                last_exception = e
                if not is_transient_error(e) or attempt == self.max_retries:
                    self._logger.error(f"Connection failed: {e}")
                    raise
                
                delay = min(self.base_delay * (2 ** attempt), self.max_delay)
                self._logger.warning(f"Connection attempt {attempt + 1} failed. "
                                   f"Retrying in {delay:.1f}s...")
                time.sleep(delay)
        
        raise last_exception
    
    @property
    def connection(self) -> mssql_python.Connection:
        """Get or create connection."""
        if self._conn is None:
            self._conn = self._connect()
        return self._conn
    
    def execute(self, query: str, params: dict = None):
        """Execute query with automatic retry and reconnection."""
        return self._execute_with_retry(
            lambda c: self._do_execute(c, query, params)
        )
    
    def _do_execute(self, cursor, query: str, params: dict):
        cursor.execute(query, params or {})
        return cursor.fetchall()
    
    def _execute_with_retry(self, operation):
        """Execute an operation with retry logic."""
        last_exception = None
        
        for attempt in range(self.max_retries + 1):
            try:
                cursor = self.connection.cursor()
                return operation(cursor)
            except mssql_python.Error as e:
                last_exception = e
                
                if not is_transient_error(e):
                    raise
                
                if attempt == self.max_retries:
                    raise
                
                # Try to reconnect
                self._logger.warning(f"Operation failed. Reconnecting...")
                self._close()
                
                delay = min(self.base_delay * (2 ** attempt), self.max_delay)
                time.sleep(delay)
        
        raise last_exception
    
    def _close(self):
        """Close connection."""
        if self._conn:
            try:
                self._conn.close()
            except:
                pass
            self._conn = None
    
    def close(self):
        """Public close method."""
        self._close()
    
    def __enter__(self):
        return self
    
    def __exit__(self, exc_type, exc_val, exc_tb):
        self.close()
        return False

# Usage
with ResilientConnection(connection_string) as db:
    users = db.execute("SELECT * FROM Person.Person WHERE EmailPromotion = %(promo)s", 
                       {"promo": 1})
    print(f"Retrieved {len(users)} rows")

Traitement spécifique à Azure SQL

Gérer la limitation du débit dans Azure

Les erreurs de limitation du débit d’Azure SQL nécessitent des délais plus longs et davantage de nouvelles tentatives que les erreurs transitoires classiques. Réutilisez is_azure_throttling à partir de Détecter les erreurs temporaires :

def execute_with_throttle_handling(cursor, query: str, params: dict,
                                   max_retries: int = 10,
                                   base_delay: float = 5.0):
    """Execute with extended retry for Azure SQL throttling."""
    for attempt in range(max_retries + 1):
        try:
            cursor.execute(query, params)
            return cursor.fetchall()
        except mssql_python.Error as e:
            if is_azure_throttling(e):
                if attempt < max_retries:
                    # Longer delays for throttling
                    delay = base_delay * (2 ** min(attempt, 4))  # Cap at 80s
                    print(f"Throttled. Waiting {delay}s before retry...")
                    time.sleep(delay)
                    continue
            raise

Gérer le basculement

Reconnectez-vous et réessayez lorsqu’un basculement d’Azure SQL ou d’un groupe de disponibilité interrompt une connexion :

def execute_with_failover_retry(connect, query: str, params: dict,
                                max_retries: int = 3,
                                recovery_delay: float = 10.0):
    """Reconnect and retry during Azure SQL failover scenarios."""
    failover_numbers = frozenset({40613, 40197, 40540})
    last_exception = None

    for attempt in range(max_retries + 1):
        conn = None
        try:
            conn = connect()
            cursor = conn.cursor()
            cursor.execute(query, params)
            return cursor.fetchall()
        except mssql_python.Error as e:
            last_exception = e

            # Failover surfaces either as a transient OperationalError or as
            # a ProgrammingError whose ddbc_error text contains the engine
            # error number. Treat both as recoverable.
            ddbc_text = getattr(e, "ddbc_error", "") or ""
            is_failover = is_transient_error(e) or any(
                int(m) in failover_numbers for m in _ERROR_NUMBER_RE.findall(ddbc_text)
            )

            if is_failover and attempt < max_retries:
                print(f"Failover detected. Reconnecting in {recovery_delay}s...")
                if conn is not None:
                    try:
                        conn.close()
                    except mssql_python.Error:
                        pass
                time.sleep(recovery_delay)
                continue
            raise

    raise last_exception


# Usage
connection_string = (
    "Server=tcp:<server>.database.windows.net,1433;"
    "Database=AdventureWorks2022;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;TrustServerCertificate=no"
)

rows = execute_with_failover_retry(
    lambda: mssql_python.connect(connection_string),
    "SELECT TOP 10 ProductID, Name FROM Production.Product WHERE Color = %(color)s",
    {"color": "Silver"}
)

Gestion de l'interblocage

Nouvelle tentative en cas d’interblocage

Les blocages (erreur 1205) sont transitoires. Réessayez avec un court délai aléatoire pour briser le cycle d’impasse. Réessayer règle l’échec immédiat, mais des blocages récurrents indiquent un problème de conception que vous devriez examiner côté serveur. Pour des conseils sur l’analyse et la résolution de la cause profonde, voir Erreurs de blocage.

def execute_with_deadlock_retry(cursor, query: str, params: dict,
                                max_retries: int = 3):
    """Automatically retry deadlocked transactions.

    Deadlocks (SQL Server error 1205) surface as OperationalError with
    driver_error == "Serialization failure" (SQLSTATE 40001).
    """
    for attempt in range(max_retries + 1):
        try:
            cursor.execute(query, params)
            return cursor.fetchall()
        except mssql_python.OperationalError as e:
            if getattr(e, "driver_error", "") == "Serialization failure":
                if attempt < max_retries:
                    delay = random.uniform(0.1, 0.5) * (attempt + 1)
                    print(f"Deadlock detected. Retry {attempt + 1} in {delay:.2f}s")
                    time.sleep(delay)
                    continue
            raise

# Usage in transaction
conn.autocommit = False
try:
    cursor = conn.cursor()
    rows = execute_with_deadlock_retry(
        cursor,
        "SELECT TOP 5 Name, ListPrice FROM Production.Product WHERE ListPrice > %(price)s",
        {"price": 100}
    )
    conn.commit()
except Exception:
    conn.rollback()
    raise

Essai structuré avec configuration

Classe de stratégie de nouvelle tentative

Encapsulez la configuration de la réévaluation dans une dataclass pour la réutilisation à travers différentes opérations :

from dataclasses import dataclass, field
from typing import FrozenSet
import time
import random

# This example uses TRANSIENT_DRIVER_ERRORS from the "Identify transient errors"
# section earlier in this article. Include that allowlist in your module.

@dataclass
class RetryPolicy:
    """Configuration for retry behavior."""
    max_retries: int = 3
    base_delay: float = 1.0
    max_delay: float = 30.0
    exponential_base: float = 2.0
    jitter: bool = True
    transient_driver_errors: FrozenSet[str] = field(default_factory=lambda: TRANSIENT_DRIVER_ERRORS)

    def get_delay(self, attempt: int) -> float:
        """Calculate delay for given attempt number."""
        delay = min(
            self.base_delay * (self.exponential_base ** attempt),
            self.max_delay,
        )
        if self.jitter:
            delay *= (0.5 + random.random())
        return delay

    def should_retry(self, error: BaseException, attempt: int) -> bool:
        """Determine if operation should be retried."""
        if attempt >= self.max_retries:
            return False
        if isinstance(error, mssql_python.OperationalError):
            return getattr(error, "driver_error", "") in self.transient_driver_errors
        return False

def execute_with_policy(cursor, query: str, params: dict,
                        policy: RetryPolicy = None):
    """Execute query with configurable retry policy."""
    policy = policy or RetryPolicy()
    last_exception = None

    for attempt in range(policy.max_retries + 1):
        try:
            cursor.execute(query, params)
            return cursor.fetchall()
        except mssql_python.Error as e:
            last_exception = e
            if not policy.should_retry(e, attempt):
                raise

            delay = policy.get_delay(attempt)
            time.sleep(delay)

    raise last_exception

# Usage with custom policy
aggressive_retry = RetryPolicy(max_retries=10, base_delay=0.5, max_delay=60.0)
conservative_retry = RetryPolicy(max_retries=2, base_delay=5.0, max_delay=10.0)

results = execute_with_policy(cursor, query, params, aggressive_retry)

Modèle Disjoncteur

Prévenir les défaillances en cascade en suivant les erreurs consécutives et en bloquant temporairement les appels lorsqu’un seuil est atteint :

import time
from enum import Enum
from threading import Lock

class CircuitState(Enum):
    CLOSED = "closed"      # Normal operation
    OPEN = "open"          # Failing, reject all calls
    HALF_OPEN = "half_open"  # Testing if service recovered

class CircuitBreaker:
    """Circuit breaker to prevent cascading failures."""
    
    def __init__(self, failure_threshold: int = 5,
                 recovery_timeout: float = 30.0):
        self.failure_threshold = failure_threshold
        self.recovery_timeout = recovery_timeout
        self.state = CircuitState.CLOSED
        self.failure_count = 0
        self.last_failure_time = None
        self._lock = Lock()
    
    def can_execute(self) -> bool:
        """Check if circuit allows execution."""
        with self._lock:
            if self.state == CircuitState.CLOSED:
                return True
            
            if self.state == CircuitState.OPEN:
                # Check if recovery timeout has passed
                if time.time() - self.last_failure_time > self.recovery_timeout:
                    self.state = CircuitState.HALF_OPEN
                    return True
                return False
            
            # HALF_OPEN: allow one test request
            return True
    
    def record_success(self):
        """Record successful operation."""
        with self._lock:
            self.failure_count = 0
            self.state = CircuitState.CLOSED
    
    def record_failure(self):
        """Record failed operation."""
        with self._lock:
            self.failure_count += 1
            self.last_failure_time = time.time()
            
            if self.failure_count >= self.failure_threshold:
                self.state = CircuitState.OPEN

# Usage
circuit = CircuitBreaker(failure_threshold=5, recovery_timeout=30.0)

def execute_with_circuit_breaker(cursor, query: str, params: dict):
    if not circuit.can_execute():
        raise Exception("Circuit breaker is open")
    
    try:
        cursor.execute(query, params)
        result = cursor.fetchall()
        circuit.record_success()
        return result
    except mssql_python.Error as e:
        if is_transient_error(e):
            circuit.record_failure()
        raise

Contenu connexe

• Gestion des erreurs
• Regroupement de connexions
• Résolution des problèmes
• Résilience des connexions Azure SQL

Ne réessayez pas les erreurs de configuration

Toutes les erreurs ne sont pas transitoires. Réessayer une erreur de configuration ou de code fait perdre du temps et peut masquer le vrai problème. Réessayez uniquement les erreurs qui pourraient se résoudre d’elles-mêmes. Comme mssql-python n’expose pas le numéro d’erreur du moteur comme un attribut, classez par sous-classe d’exception plus le driver_error texte.

Ne jamais réessayer ces éléments (corrigez plutôt le code ou la configuration) :

Pathologie	Type d'exception	driver_error texte	Réparer
Nom d’objet invalide (moteur 208)	ProgrammingError	Base table or view not found	La table n’existe pas. Corrigez la requête ou créez la table.
Nom de colonne invalide (moteur 207)	ProgrammingError	Column not found	La colonne n’existe pas. Vérifie le schéma.
Syntaxe incorrecte (moteur 102)	ProgrammingError	Syntax error or access violation	Corrigez la question.
Échec de connexion (moteur 18456)	OperationalError	Invalid authorization specification	Mauvaises références. Corrigez la chaîne de connexion.
Impossible d’ouvrir la base de données (moteur 4060)	OperationalError	Server rejected the connection	La base de données n’existe pas ou n’est pas accessible avec cet identifiant de connexion. Fixez la cible ou les permissions.
Épuisement du pool de connexions	OperationalError	(varie)	Augmentez la capacité du pool, libérez rapidement les connexions ou réduisez la concurrence.
ConnectionStringParseError	Indépendant	n/a	Faute de frappe dans le mot-clé de chaîne de connexion. Répare la ficelle.
Fonctionnalité non prise en charge	NotSupportedError	Optional feature not implemented	Adoptez une approche alternative.

Réessayez toujours ces questions (elles se résolvent d’elles-mêmes) :

Pathologie	Type d'exception	driver_error texte
Délai d'expiration de l'instruction	OperationalError	Timeout expired
Délai d’expiration de connexion	OperationalError	Connection timeout expired
Impossible d’ouvrir la connexion	OperationalError	Client unable to establish connection
Coupure du réseau	OperationalError	Communication link failure
La connexion a été coupée en plein milieu de la transaction	OperationalError	Connection failure during transaction
Victime de blocage (moteur 1205)	OperationalError	Serialization failure
État indéterminé de la transaction	OperationalError	Statement completion unknown
Azure SQL throttling (40197, 40501, 40613, 49918–49920)	ProgrammingError	Syntax error or access violation (le numéro du moteur se trouve uniquement dans ddbc_error; utilisez is_azure_throttling)