Lógica de repetição e resiliência da conexão com mssql-python

Falhas transitórias são erros temporários que podem ocorrer ao conectar ao SQL Server e SQL do Azure pelo driver mssql-python. Esses erros frequentemente se resolvem sozinhos:

• Interrupções momentâneas na conectividade de rede.
• Restrições de recursos do servidor.
• Limitação de taxa do SQL do Azure.
• Eventos de failover.

Implementar lógica de retentativa melhora a confiabilidade das aplicações, especialmente para bancos de dados hospedados na nuvem.

Não use retentativas para esconder erros de configuração ou de programação. Um banco de dados ausente, credenciais ruins ou um pool de conexão esgotado precisam de uma solução, não de outra tentativa.

Com o pooling e o provedor padrão msodbcsql18 , o driver aplica temporariamente um timeout nativo da operação de conexão durante a validação de uma conexão reutilizada: o tempo limite positivo de login, ou 15 segundos quando o tempo de login é zero ou não especificado. Isso não é uma validação total nem um prazo para checkout. Múltiplas operações nativas, limpeza e abertura de uma conexão substituta podem aumentar o tempo. Se a validação falhar, o driver tenta fazer uma substituição em vez de esperar por cada conexão ociosa restante. Essa recuperação não repete suas instruções nem tenta novamente o esgotamento do pool de tentativas. Para mais informações, veja Agrupamento de conexões.

Identificar erros transitórios

O mssql-python não expõe o número de erro do motor do SQL Server como um atributo em exceções. Em vez disso, o driver mapeia códigos SQLSTATE para um conjunto fixo de subclasses de exceção PEP 249 (OperationalError, ProgrammingError, e assim por diante) e para texto padronizado em inglês no driver_error atributo. Use essa combinação como base da classificação de transitórios.

Sinais transitórios confiáveis

Os seguintes valores SQLSTATE aparecem como OperationalError e indicam uma condição que vale a pena ser retentada. A coluna da direita mostra o texto exato driver_error estabelecido pelo motorista:

SQLSTATE	driver_error Texto	Condition
HYT00	Timeout expired	Tempo limite no nível da instrução.
HYT01	Connection timeout expired	Tempo limite de conexão.
08001	Client unable to establish connection	Não consegui abrir uma conexão.
08S01	Communication link failure	Queda de rede, reset do servidor, falha no TCP.
08007	Connection failure during transaction	Conexão perdida no meio da transação.
40001	Serialization failure	Vítima do impasse.
40003	Statement completion unknown	Estado indeterminado da transação.

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

Limitação de desempenho do SQL do Azure (melhor esforço)

Erros de limitação de desempenho do SQL do Azure (40197, 40501, 40613, 49918, 49919, 49920 e códigos relacionados) normalmente aparecem com SQLSTATE 42000, que o mssql-python mapeia para ProgrammingError. O número de erro do motor não aparece como um atributo, então o único sinal é o texto da mensagem do servidor no ddbc_error atributo.

Verifique ddbc_error se há números conhecidos quando presentes e se há a mensagem padrão de erro em inglês 40501. O número pode estar ausente, e a mensagem de texto não é uma garantia estável. Diagnósticos localizados ou formatados de forma diferente podem não corresponder:

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)

O que não repetir

Exemplos de erros que deveriam falhar rapidamente em vez de tentar novamente incluem credenciais inválidas (OperationalError com texto Invalid authorization specificationdo driver), banco de dados ausente ou permissões insuficientes, erros de sintaxe (ProgrammingError), objetos ausentes e esgotamento do pool de conexão. A função is_transient_error acima exclui todos eles por construção.

Decorador básico de nova tentativa

Retentativa simples com atraso fixo

Um decorador que tenta executar novamente a função encapsulada um número fixo de vezes com um atraso constante:

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

Retirada exponencial

Aumente exponencialmente o atraso entre as tentativas, com uma tremulação opcional, para distribuir as tentativas simultâneas:

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 nova tentativa de conexão

Gerenciador de conexão resiliente

Um wrapper de conexão que lida tanto com tentativas quanto com reconexão automática:

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

Tratamento específico do SQL do Azure

Use o mapeamento de exceções do mssql-python em Identificar erros transitórios para classificar erros do catálogo a seguir.

Os seguintes erros podem ser transitórios quando ocorrem durante o estabelecimento da conexão ou ao enviar uma solicitação para o servidor. Tente novamente em uma retirada curta e limitada. Erros que persistem além de algumas tentativas geralmente indicam um problema de configuração, como servidor errado, permissões faltando, configurações de criptografia incompatíveis ou cota esgotada, que a tentativa não vai corrigir.

Erro	Tipo de falha	Message	Troubleshooting
64	Transporte durante o login	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.)	A conexão TCP é interrompida durante o handshake. Não é uma falha de credenciais. Se persistir, verifique se há instabilidade de rede do lado do cliente ou um dispositivo intermediário que descarta conexões semi-estabelecidas.
233	Transporte antes do login ou TLS	The client was unable to establish a connection because of an error during connection initialization process before login.	O servidor geralmente retorna esse erro quando não consegue aceitar a conexão devido ao esgotamento de recursos, limite de conexão ou um cliente não suportado. Não é uma falha de credenciais. Verifique a integridade do servidor e verifique o tempo limite de logon do cliente, as configurações do TLS e a compatibilidade de versão do TLS cliente/servidor.
4060	Disponibilidade ou acesso ao banco de dados	Cannot open database "%.*ls" requested by the login. The login failed.	O logon é autenticado, mas não pode abrir o banco de dados solicitado. As causas transitórias incluem o fato de o banco de dados estar em transição (failover, restauração, redimensionamento) ou em pausa automática. As causas persistentes (o banco de dados não existe, o logon não tem acesso) não serão corrigidas por repetição; verifique o nome do banco de dados, o mapeamento de logon e o estado do banco de dados.
4221	Transição secundária legível	Login to read-secondary failed due to long wait on 'HADR_DATABASE_WAIT_FOR_TRANSITION_TO_VERSIONING'.	A réplica não está disponível para login porque as versões das linhas estão ausentes para transações que ainda estavam em andamento quando a réplica foi reciclada. Reverta ou confirme as transações ativas no primário para resolver o problema. Mitigue evitando transações longas de gravação no servidor primário.
10053	Interrupção de transporte local	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.)	O lado local aborta a conexão. Verifique a integridade da rede do lado do cliente e qualquer firewall local ou cliente VPN.
10054	Reinício do transporte 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.)	O lado remoto envia uma redefinição de TCP. Causas comuns: o processo par falhou, um firewall injetou uma redefinição ou o gateway de SQL do Azure fechou uma conexão ociosa. Para padrões de redefinição por inatividade, habilite o keepalive TCP no cliente ou reduza o tempo limite de inatividade do pool de conexões.
10060	Tempo de espera da conexão esgotado	A connection attempt failed because the connected party did not properly respond after a period of time.	O servidor ou um dispositivo de rede intermediário não atendia antes do tempo limite da conexão TCP. Verifique a saúde do servidor, roteamento, regras do firewall e se o host e a porta configurados são acessíveis.
10928	Limite de recursos do banco de dados	Resource ID: %d. The %s limit for the database is %d and has been reached.	O banco de dados excede um limite de governança de recursos SQL do Azure. A ID do recurso 1 indica o limite de trabalho; A ID do recurso 2 indica o limite da sessão. Identifique o tipo de limite na mensagem e, em seguida, reduza a concorrência, aumente a capacidade do banco de dados ou encurte as operações de longa duração que mantêm o recurso ocupado.
10929	Limitação de banco de dados	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.	O banco de dados está acima de sua garantia mínima e o servidor subjacente está limitando. Normalmente, a repetição é bem-sucedida quando a carga do vizinho cai. Ocorrências sustentadas indicam que você precisa de uma camada de serviço mais alta ou um ambiente menos barulhento.
40020, 40143, 40166, 40540	Subcódigo de failover do SQL do Azure	Relatado no slot Error code %d do erro 40197 durante o failover.	Subcódigos incorporados em uma mensagem de failover 40197 que alguns caminhos exibem como o código de erro principal. Trate-os da mesma forma que 40197.
40197	Failover do SQL do Azure	The service has encountered an error processing your request. Please try again. Error code %d.	Uma atualização de software, uma falha de hardware ou outro evento de failover no SQL do Azure. Ao reconectar, você é redirecionado para uma réplica saudável. O código de erro inserido identifica o tipo de failover. Se o erro persistir, capture a ID de rastreamento da sessão e contate o suporte.
40501	Limitação de taxa do SQL do Azure	The service is currently busy. Retry the request after 10 seconds. Incident ID: %ls. Code: %d.	Limitação do mecanismo do SQL do Azure. O mínimo recomendado é um intervalo de espera de 10 segundos. A limitação contínua indica que a carga de trabalho excedeu a alocação de recursos do banco de dados; aumente a camada de serviço ou reduza a concorrência.
40613	Banco de dados indisponível	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'.	O banco de dados não está disponível, geralmente durante um failover ou por um breve período durante uma operação de escala. Tente novamente após um intervalo de espera; se o problema persistir por alguns minutos, capture o ID de rastreamento da sessão e abra um chamado de suporte.
42108	Pool SQL pausado	Can not connect to the SQL pool since it is paused. Please resume the SQL pool and try again.	O pool de SQL dedicado (Synapse) está em pausa. A nova tentativa só é bem-sucedida depois que o pool é retomado. Retome o pool explicitamente ou agende a carga de trabalho a ser executada após a retomada do pool.
42109	Pool SQL retomando	The SQL pool is warming up. Please try again.	O pool de SQL dedicado está sendo reiniciado. Tente novamente com backoff até que o pool fique online; a inicialização normalmente leva alguns minutos.
49918	Escassez de recursos de serviços	Cannot process request. Not enough resources to process request. The service is currently busy. Please retry the request later.	No momento, o servidor não pode alocar recursos suficientes para atender à solicitação. Tente novamente após um intervalo de espera. Se o erro persistir, aumente a capacidade do banco de dados ou do pool elástico.
49919	Limitação de taxa de operações de gerenciamento	Cannot process create or update request. Too many create or update operations in progress for subscription "%ld".	Limite de concorrência no nível da assinatura para operações de gerenciamento. Reduza chamadas paralelas de criação/atualização ou escalone-as.
49920	Limitação de operações por assinatura	Cannot process request. Too many operations in progress for subscription "%ld".	Limite de concorrência de operações em andamento no nível da assinatura. Reduza o paralelismo ou aguarde até que as operações em andamento sejam concluídas.

Os erros no nível da instrução não estão nessa lista porque são disparados depois que a conexão é estabelecida e a falha deixa a sessão utilizável. Os erros de instrução passíveis de repetição mais comuns são 1205 (vítima de deadlock) e 1222 (tempo limite da solicitação de bloqueio). Repita a transação inteira em vez da única instrução com falha.

O texto da mensagem de erro vem de erros transitórios de conexão do SQL do Azure. Esses erros podem ser repetidos no SQL Server, no Banco de Dados SQL do Azure, no Instância Gerenciada de SQL do Azure, no Banco de Dados SQL no Microsoft Fabric e em pools de SQL dedicados no Azure Synapse Analytics.

Lidar com a limitação de requisições do Azure

Erros de limite de desempenho no SQL do Azure exigem atrasos maiores e mais tentativas do que erros transitórios padrão. Reutilize is_azure_throttling de Identificar erros transitórios:

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

Failover de identificador

Reconecte e tente novamente quando o failover do SQL do Azure ou do grupo de disponibilidade interromper uma conexão:

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

Tratamento de deadlock

Tentar novamente em caso de deadlock

Deadlocks (erro 1205) são transitórios. Tente novamente após um curto intervalo aleatório para interromper o ciclo de deadlock. Retentar resolve a falha imediata, mas bloqueios recorrentes indicam um problema de design que você deve investigar no servidor. Para orientações sobre como analisar e resolver a causa raiz, veja Erros de bloqueio.

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

Retentativa estruturada com configuração

Classe de política de repetição

Encapsule a configuração de novas tentativas em uma classe de dados para reutilização em diferentes operações:

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)

Padrão de disjuntor

Evite falhas em cascata rastreando erros consecutivos e bloqueando temporariamente chamadas quando um limite é atingido:

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

Não tente novamente os erros de configuração

Nem todo erro é transitório. Tentar novamente após um erro de configuração ou de programação desperdiça tempo e pode mascarar o problema real. Tente novamente apenas em caso de erros que possam ser resolvidos por conta própria. Como o mssql-python não expõe o número de erro do mecanismo como um atributo, classifique pela subclasse da exceção e pelo texto driver_error.

Nunca tente novamente esses (corrija o código ou a configuração):

Condition	Tipo de exceção	driver_error Texto	Corrigir
Nome inválido do objeto (engine 208)	ProgrammingError	Base table or view not found	A tabela não existe. Corrija a consulta ou crie a tabela.
Nome da coluna inválido (engine 207)	ProgrammingError	Column not found	A coluna não existe. Confira o esquema.
Sintaxe incorreta (engine 102)	ProgrammingError	Syntax error or access violation	Corrija a dúvida.
Falha no login (mecanismo 18456)	OperationalError	Invalid authorization specification	Credenciais erradas. Corrija a string de conexão.
Banco de dados ausente ou acesso negado (engine 4060)	OperationalError	Server rejected the connection	O banco de dados não existe ou não é acessível para o login. Corrija o destino ou as permissões.
Esgotamento do pool de conexões	OperationalError	(varia)	Aumente a capacidade do pool, libere conexões rapidamente ou reduza a concorrência.
ConnectionStringParseError	Autônomo	n/a	Erro de digitação na palavra-chave da cadeia de conexão. Corrija a cadeia de caracteres.
Recurso não suportado	NotSupportedError	Optional feature not implemented	Use uma abordagem alternativa.

Sempre tente novamente esses (eles se resolvem sozinhos):

Condition	Tipo de exceção	driver_error Texto
Tempo limite da instrução	OperationalError	Timeout expired
Tempo limite de conexão	OperationalError	Connection timeout expired
Não consegui abrir a conexão	OperationalError	Client unable to establish connection
Queda de rede	OperationalError	Communication link failure
Conexão foi interrompida no meio da transação	OperationalError	Connection failure during transaction
Vítima do deadlock (motor 1205)	OperationalError	Serialization failure
Estado indeterminado da transação	OperationalError	Statement completion unknown
SQL do Azure throttling (40197, 40501, 40613, 49918–49920)	ProgrammingError	Syntax error or access violation (usar is_azure_throttling para combinar com o texto ddbc_error)

Conteúdo relacionado

• Tratamento de erros e códigos SQLSTATE para mssql-python
• Pooling de conexão com mssql-python
• Solucionar problemas no mssql-python
• Solução de problemas de erros de conexão transitória