Logica di ritentazione e resilienza delle connessioni con mssql-python

I guasti transitori sono errori temporanei che possono verificarsi quando si connette a SQL Server e Azure SQL tramite il driver mssql-python. Questi errori spesso si risolvono da soli:

• Interruzioni della connettività di rete.
• Vincoli di risorse del server.
• Limitazione di Azure SQL.
• Eventi di failover.

L'implementazione della logica di ritentazione migliora l'affidabilità delle applicazioni, specialmente per i database ospitati nel cloud.

Non usare i retenti per nascondere errori di configurazione o di codice. Un database mancante, credenziali scadenti o un pool di connessioni esaurito necessitano di una soluzione, non di un altro tentativo.

Con il pooling e il provider predefinito msodbcsql18 , il driver applica temporaneamente un timeout nativo per l'operazione di connessione durante la validazione di una connessione riutilizzata: il timeout positivo per il login, ovvero 15 secondi quando il timeout per il login è zero o non specificato. Questa non è una scadenza complessiva per la convalida o il checkout. Più operazioni native, pulizia e apertura di una connessione sostitutiva possono richiedere più tempo. Se la validazione fallisce, il driver tenta una sostituzione invece di attendere ciascuna delle restanti connessioni inattive. Questo recupero non ripercorre le tue istruzioni né ritenta in caso di esaurimento del pool. Per maggiori informazioni, vedere pool di connessioni.

Identificare gli errori transitori

MSSQL-Python non espone il numero di errore del motore SQL Server come attributo nelle eccezioni. Invece, il driver mappa i codici SQLSTATE a un insieme fisso di sottoclassi di eccezione PEP 249 (OperationalError, ProgrammingError, e così via) e a testo inglese standardizzato nell'attributo driver_error . Usa questa combinazione come base per la classificazione dei transitori.

Segnali transitori affidabili

I seguenti valori SQLSTATE compaiono come OperationalError e indicano una condizione che vale la pena riprovare. La colonna di destra mostra il testo esatto driver_error impostato dal pilota:

SQLSTATE	driver_error testo	Condition
HYT00	Timeout expired	Timeout a livello di istruzione.
HYT01	Connection timeout expired	Timeout per il momento di connessione.
08001	Client unable to establish connection	Non riuscivo ad aprire una connessione.
08S01	Communication link failure	Interruzione della rete, reset del server, guasto TCP.
08007	Connection failure during transaction	Connessione persa a metà transazione.
40001	Serialization failure	Vittima di un deadlock.
40003	Statement completion unknown	Stato indeterminato della transazione.

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

Limitazione di Azure SQL (al meglio possibile)

Gli errori di throttling di Azure SQL (40197, 40501, 40613, 49918, 49919, 49920 e i codici correlati) in genere si presentano con SQLSTATE 42000, che mssql-python associa a ProgrammingError. Il numero di errore del motore non appare come attributo, quindi l'unico segnale è il testo del messaggio server nell'attributo ddbc_error .

Controlla ddbc_error per i numeri noti quando presenti e per il messaggio standard di errore inglese 40501. Il numero può essere assente e il testo del messaggio non è un contratto stabile. Diagnostiche localizzate o formattate in modo diverso potrebbero non corrispondere:

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")
_AZURE_40501_MESSAGE = "The service is currently busy. Retry the request after 10 seconds."


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 (
        _AZURE_40501_MESSAGE in ddbc_text
        or 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)

Cosa non riprovare

Esempi di errori che dovrebbero fallire rapidamente invece di riprovare includono credenziali non valide (OperationalError con testo Invalid authorization specificationdel driver), un database mancante o permessi insufficienti, errori di sintassi (ProgrammingError), oggetti mancanti e esaurimento del pool di connessioni. La funzione is_transient_error precedente esclude tutti questi elementi per costruzione.

Decoratore di base per i tentativi

Ritentativo semplice con ritardo fisso

Un decoratore che riprova la funzione wrapped un numero fisso di volte con un ritardo costante:

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 esponenziale

Aumenta esponenzialmente il ritardo tra un tentativo e l'altro, con jitter opzionale, per dilazionare i tentativi simultanei:

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 di ritentazione di connessione

Gestore di connessione resiliente

Un involucro di connessione che gestisce sia il ritentativo che la riconnessione automatica:

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

Handling specifico di Azure SQL

Usa la mappatura delle eccezioni mssql-python in Identifica gli errori transitori per classificare gli errori dal seguente catalogo.

I seguenti errori possono essere transitori quando si verificano durante l'instaurazione della connessione o durante l'invio di una richiesta al server. Riprova dopo un breve backoff limitato. Gli errori che persistono oltre pochi tentativi di solito indicano un problema di configurazione, come un server sbagliato, permessi mancanti, impostazioni di crittografia incompatibili o quota esaurita, che un ritentativo non risolverà.

Error	Tipo di errore	Message	Troubleshooting
64	Trasporto durante l'accesso	A connection was successfully established with the server, but then an error occurred during the login process. (provider: TCP Provider, error: 0 - The specified network name is no longer available.)	La connessione TCP si interrompe durante l'handshake. Non si è verificato un errore di credenziale. Se il problema persiste, controlla la presenza di instabilità della rete lato client o di un dispositivo intermedio che interrompe le connessioni parzialmente stabilite.
233	Trasporto prima dell'accesso o TLS	The client was unable to establish a connection because of an error during connection initialization process before login.	Il server spesso restituisce questo errore quando non può accettare la connessione a causa dell'esaurimento delle risorse, di un limite di connessione o di un client non supportato. Non si è verificato un errore di credenziale. Verificare l'integrità del server, quindi controllare il timeout di accesso client, le impostazioni TLS e la compatibilità della versione TLS client/server.
4060	Disponibilità o accesso al database	Cannot open database "%.*ls" requested by the login. The login failed.	L'accesso viene autenticato, ma non può aprire il database richiesto. Le cause temporanee includono il database in fase di transizione (failover, ripristino, ridimensionamento) o sospeso automaticamente. Le cause persistenti (il database non esiste, il login non dispone delle autorizzazioni necessarie) non si risolvono riprovando; verificate il nome del database, il mapping del login e lo stato del database.
4221	Transizione secondaria leggibile	Login to read-secondary failed due to long wait on 'HADR_DATABASE_WAIT_FOR_TRANSITION_TO_VERSIONING'.	La replica non è disponibile per l'accesso perché mancano versioni delle righe per le transazioni ancora in corso quando la replica è stata reinizializzata. Eseguire il rollback o il commit delle transazioni attive nel database primario per risolvere il problema. Attenuare evitando transazioni di scrittura lunghe nel database primario.
10053	Interruzione del trasporto locale	A transport-level error has occurred when sending the request to the server. (provider: TCP Provider, error: 0 - An established connection was aborted by the software in your host machine.)	Il lato locale interrompe la connessione. Controllare lo stato della rete lato client e l'eventuale firewall locale o il client VPN.
10054	Ripristino del trasporto remoto	A transport-level error has occurred when sending the request to the server. (provider: TCP Provider, error: 0 - An existing connection was forcibly closed by the remote host.)	La parte remota invia un reset TCP. Cause comuni: il processo peer si è arrestato in modo anomalo, un firewall ha inserito una reimpostazione o il gateway Azure SQL ha chiuso una connessione inattiva. Per gli schemi di reset dovuti all'inattività, abilitare il keepalive TCP sul client o ridurre il timeout di inattività del pool di connessioni.
10060	Timeout della connessione	A connection attempt failed because the connected party did not properly respond after a period of time.	Il server o un dispositivo di rete intermedio non rispondevano prima del timeout della connessione TCP. Controlla la salute del server, il routing, le regole del firewall e se l'host configurato e la porta sono raggiungibili.
10928	Limite di risorse del database	Resource ID: %d. The %s limit for the database is %d and has been reached.	Il database supera un limite di governance delle risorse Azure SQL. L'ID risorsa 1 indica il limite di lavoro; L'ID risorsa 2 indica il limite di sessione. Identificare il tipo di limite dal messaggio, quindi ridurre la concorrenza, aumentare le prestazioni del database o abbreviare le operazioni a esecuzione prolungata che contengono la risorsa.
10929	Limitazione della velocità del database	Resource ID: %d. The %s minimum guarantee is %d, maximum limit is %d, and the current usage for the database is %d. However, the server is currently too busy to support requests greater than %d for this database.	Il database sta superando la soglia minima garantita e il server sottostante sta limitando le prestazioni. La ripetizione dei tentativi ha in genere esito positivo quando il carico adiacente scende. Le occorrenze sostenute indicano che è necessario un livello di servizio superiore o un ambiente meno rumoroso.
40020, 40143, 4016640540	Sottocodice di failover di Azure SQL	Segnalato nel slot Error code %d dell'errore 40197 durante il failover.	I sottocodici contenuti in un messaggio di failover 40197, che alcuni percorsi espongono come numero di errore di livello superiore. Trattarli come 40197.
40197	Azure SQL failover	The service has encountered an error processing your request. Please try again. Error code %d.	Un aggiornamento software, un errore hardware o un altro evento di failover in Azure SQL. La riconnessione ti indirizza a una replica integra. Il codice di errore incorporato identifica il tipo di failover. Se l'errore persiste, acquisire l'ID di traccia della sessione e contattare il supporto tecnico.
40501	Azure SQL throttling	The service is currently busy. Retry the request after 10 seconds. Incident ID: %ls. Code: %d.	Limitazione del motore di Azure SQL Il valore minimo consigliato per il backoff è di 10 secondi. Il throttling prolungato indica che il carico di lavoro ha superato le risorse allocate al database; aumenta il livello di servizio o riduci la concorrenza.
40613	Database non disponibile	Database '%.*ls' on server '%.*ls' is not currently available. Please retry the connection later. If the problem persists, contact customer support, and provide them with the session tracing ID of '%.*ls'.	Il database non è disponibile, in genere durante un failover o per breve tempo durante un'operazione di scalabilità. Riprovare dopo un intervallo di attesa; se il problema persiste per più di qualche minuto, annotare l'ID di tracciamento della sessione e aprire un caso di supporto.
42108	Pool SQL pausato	Can not connect to the SQL pool since it is paused. Please resume the SQL pool and try again.	Il pool SQL dedicato (Synapse) si trova in uno stato sospeso. Il nuovo tentativo ha esito positivo solo dopo la ripresa del pool. Riprendi esplicitamente il pool oppure pianifica il carico di lavoro affinché venga eseguito dopo che il pool è stato ripreso.
42109	Ripristino del pool SQL	The SQL pool is warming up. Please try again.	Il pool SQL dedicato riprende. Riprovare su un backoff fino a quando il pool non è online; il riscaldamento richiede in genere alcuni minuti.
49918	Carenza di risorse di servizio	Cannot process request. Not enough resources to process request. The service is currently busy. Please retry the request later.	Il server non è attualmente in grado di allocare risorse sufficienti per soddisfare la richiesta. Riprova dopo un intervallo di attesa. Se l'errore persiste, aumentare le prestazioni del database o del pool elastico.
49919	Limitazione delle operazioni di gestione	Cannot process create or update request. Too many create or update operations in progress for subscription "%ld".	Limite di concorrenza a livello di sottoscrizione per le operazioni di gestione. Ridurre le chiamate parallele di creazione o aggiornamento oppure scaglionarle.
49920	Limitazione delle operazioni di sottoscrizione	Cannot process request. Too many operations in progress for subscription "%ld".	Limite di concorrenza a livello di sottoscrizione per le operazioni in corso. Ridurre il parallelismo o attendere che le operazioni in corso vengano completate.

Gli errori a livello di istruzione non sono inclusi in questo elenco perché vengono attivati dopo la connessione e l'errore lascia utilizzabile la sessione. Gli errori ripetibili delle istruzioni più comuni sono 1205 (vittima di deadlock) e 1222 (timeout della richiesta di blocco). Ritentare l'intera transazione anziché la singola istruzione non riuscita.

Il testo del messaggio di errore proviene da Azure SQL errori di connessione temporanei. Questi errori possono essere ritentati su SQL Server, database SQL di Azure, Istanza gestita di SQL di Azure, database SQL in Microsoft Fabric e pool SQL dedicati in Azure Synapse Analytics.

Gestire la limitazione di Azure

Gli errori di throttling di Azure SQL richiedono ritardi più lunghi e un numero maggiore di tentativi rispetto ai normali errori transitori. Riutilizza is_azure_throttling da Identifica gli errori transitori:

def execute_with_throttle_handling(cursor, query: str, params: dict,
                                   max_retries: int = 10,
                                   base_delay: float = 10.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 16 times the base delay
                    print(f"Throttled. Waiting {delay}s before retry...")
                    time.sleep(delay)
                    continue
            raise

Gestione del failover

Riconnettiti e riprova quando Azure SQL o il failover del gruppo di disponibilità interrompono una connessione:

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=AdventureWorks2025;"
    "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"}
)

Gestione dello stallo

Ritenta in caso di deadlock

I deadlock (errore 1205) sono transitori. Riprova con un breve ritardo casuale per rompere il ciclo di stallo. Riprovare consente di gestire l'errore immediato, ma deadlock ricorrenti indicano un problema di progettazione che dovresti analizzare sul lato server. Per indicazioni sull'analisi e la risoluzione della causa principale, vedi Errori di bloccaggio.

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

Nuovo tentativo strutturato con configurazione

Classe dei criteri per i nuovi tentativi

Incapsula la configurazione dei tentativi in una dataclass per riutilizzarla in diverse operazioni:

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)

Modello di interruttore

Prevenire fallimenti a cascata tracciando errori consecutivi e bloccando temporaneamente le chiamate quando si raggiunge una soglia:

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

Non riprovare in caso di errori di configurazione

Non tutti gli errori sono transitori. Riprovare un errore di configurazione o di codice fa perdere tempo e può mascherare il vero problema. Solo errori di riprova che potrebbero risolversi da soli. Poiché mssql-python non espone il numero di errore del motore come attributo, classifica per sottoclasse eccezione più il driver_error testo.

Non riprovare mai queste (correggi il codice o la configurazione invece):

Condition	Tipo di eccezione	driver_error testo	Correzione
Nome oggetto non valido (engine 208)	ProgrammingError	Base table or view not found	La tabella non esiste. Correggi la query o crea la tabella.
Nome della colonna non valido (motore 207)	ProgrammingError	Column not found	La rubrica non esiste. Controlla lo schema.
Sintassi errata (engine 102)	ProgrammingError	Syntax error or access violation	Risolvi la domanda.
Accesso non riuscito (engine 18456)	OperationalError	Invalid authorization specification	Credenziali sbagliate. Correggi la stringa di connessione.
Database mancante o accesso negato (motore 4060)	OperationalError	Server rejected the connection	Il database non esiste o non è accessibile al login. Correggi la destinazione o i permessi.
Esaurimento del pool di connessioni	OperationalError	(varia)	Aumentare la capacità del pool, rilasciare rapidamente le connessioni o ridurre la concorrenza.
ConnectionStringParseError	Autonomo	N/D	Errore di battitura nella parola chiave della stringa di connessione. Aggiusta il filo.
Funzionalità non supportata	NotSupportedError	Optional feature not implemented	Usa un approccio alternativo.

Riprova sempre questi (si risolvono da soli):

Condition	Tipo di eccezione	driver_error testo
Timeout rendiconto	OperationalError	Timeout expired
Timeout connessione	OperationalError	Connection timeout expired
Non riuscivo ad aprire la connessione	OperationalError	Client unable to establish connection
Disconnessione di rete	OperationalError	Communication link failure
La connessione è caduta a metà transazione	OperationalError	Connection failure during transaction
Vittima di blocco (motore 1205)	OperationalError	Serialization failure
Stato indeterminato della transazione	OperationalError	Statement completion unknown
Azure SQL throttling (40197, 40501, 40613, 49918–49920)	ProgrammingError	Syntax error or access violation (da usare is_azure_throttling per abbinare ddbc_error il testo)

Contenuti correlati

• Gestione degli errori e codici SQLSTATE per mssql-python
• Pooling delle connessioni con mssql-python
• Risoluzione dei problemi mssql-python
• Risolvere gli errori di connessione temporanei