Driver do Microsoft Python para SQL Server - mssql-python

mssql-pythoné o driver Python da Microsoft para SQL Server, Base de Dados SQL do Azure, Azure SQL Managed Instance e base de dados SQL no Microsoft Fabric. Utiliza Direct Database Connectivity (DDBC), por isso pode ligar-se sem instalar um gestor de drivers externo. O driver suporta Python 3.10 ou posterior e cumpre a Especificação 2.0 da API de Bases de Dados de Python, adicionando melhorias amigáveis para Python no desenvolvimento diário.

Escolhe o teu ponto de partida

Linha de base de produção para o SQL do Azure

Use este exemplo como ponto de partida para uma ligação SQL do Azure orientada à produção. Lê a configuração do ambiente, autentica com identidade gerida e permite a encriptação Tabular Data Stream (TDS) 8.0. Também define tempos limite de início de sessão e de consulta por instrução, volta a tentar após falhas transitórias com recuo exponencial (uma nova ligação para erros de ligação, a mesma ligação para erros de consulta, como deadlocks), regista os resultados e recorre a gestores de contexto para libertar recursos.

As palavras-chave ConnectRetryCount e ConnectRetryInterval na cadeia de ligação permitem a resiliência de ligações inativas do SQL Server: o controlador volta a ligar de forma transparente uma ligação inativa interrompida. Isto é diferente da nova tentativa ao nível da aplicação neste exemplo, que repete uma consulta que falha com um erro transitório, como um deadlock ou o tempo limite da consulta. Os dois são complementares, por isso mantém ambos.

import logging
import os
import time

import mssql_python

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s %(message)s",
)
logger = logging.getLogger("app")

# Transient errors that require a fresh connection to recover.
CONNECT_RETRY_ERRORS = frozenset({
    "Timeout expired",
    "Connection timeout expired",
    "Client unable to establish connection",
    "Communication link failure",
    "Connection failure during transaction",
})

# Transient errors that leave the connection usable, such as a deadlock victim
# or a query timeout, so retry on the same connection.
QUERY_RETRY_ERRORS = frozenset({
    "Serialization failure",
    "Timeout expired",
})


def connect_with_retry(conn_str: str, max_attempts: int = 3, login_timeout_s: int = 5) -> mssql_python.Connection:
    """Open a connection, retrying transient failures with exponential backoff."""
    for attempt in range(1, max_attempts + 1):
        try:
            conn = mssql_python.connect(
                conn_str,
                attrs_before={mssql_python.SQL_ATTR_LOGIN_TIMEOUT: login_timeout_s},
            )
            logger.info("connected on attempt %d/%d", attempt, max_attempts)
            return conn
        except mssql_python.OperationalError as exc:
            if exc.driver_error not in CONNECT_RETRY_ERRORS or attempt == max_attempts:
                logger.error("connect failed on attempt %d/%d: %s", attempt, max_attempts, exc.driver_error)
                raise
            delay = 2 ** (attempt - 1)  # 1s, 2s, 4s
            logger.warning(
                "connect attempt %d/%d hit transient error %r; retrying in %ds",
                attempt, max_attempts, exc.driver_error, delay,
            )
            time.sleep(delay)


def execute_with_retry(
    conn: mssql_python.Connection,
    sql: str,
    *params,
    max_attempts: int = 3,
    query_timeout_s: int = 10,
) -> mssql_python.Cursor:
    """Run sql on an open connection and return the ready-to-fetch cursor.

    Retries errors that leave the connection usable so callers don't wrap each
    query in its own function. Pass query values as parameters. Retry only
    idempotent statements; wrap writes in an explicit transaction.
    """
    for attempt in range(1, max_attempts + 1):
        cursor = mssql_python.Cursor(conn, timeout=query_timeout_s)
        try:
            cursor.execute(sql, *params)
            if attempt > 1:
                logger.info("query succeeded on attempt %d/%d", attempt, max_attempts)
            return cursor
        except mssql_python.OperationalError as exc:
            cursor.close()
            if exc.driver_error not in QUERY_RETRY_ERRORS or attempt == max_attempts:
                logger.error("query failed on attempt %d/%d: %s", attempt, max_attempts, exc.driver_error)
                raise
            delay = 2 ** (attempt - 1)  # 1s, 2s, 4s
            logger.warning(
                "query attempt %d/%d hit transient error %r; retrying in %ds",
                attempt, max_attempts, exc.driver_error, delay,
            )
            time.sleep(delay)
    raise RuntimeError("unreachable: the retry loop exits by return or raise")


def main() -> None:
    # Read configuration from the environment; never hard-code secrets.
    server = os.environ["SQL_SERVER"]      # for example, myserver.database.windows.net
    database = os.environ["SQL_DATABASE"]  # for example, AdventureWorks
    client_id = os.getenv("AZURE_CLIENT_ID")  # set for a user-assigned managed identity

    # Authenticate with the workload's managed identity over TDS 8.0 encryption.
    # ConnectRetryCount/ConnectRetryInterval transparently reconnect a dropped
    # idle connection; they don't replay a failed query.
    conn_str = (
        f"Server={server};"
        f"Database={database};"
        "Authentication=ActiveDirectoryMsi;"
        "Encrypt=strict;"
        "ConnectRetryCount=3;"
        "ConnectRetryInterval=10;"
        # Parallel dials to all resolved IPs; safe on single-IP targets.
        "MultiSubnetFailover=Yes;"
    )
    if client_id:
        conn_str += f"UID={client_id};"

    query = """
        SELECT TOP 10
            p.BusinessEntityID,
            p.FirstName,
            p.LastName
        FROM Person.Person AS p
        ORDER BY p.BusinessEntityID;
    """

    try:
        # Context managers close the cursor and connection automatically.
        with connect_with_retry(conn_str) as conn:
            with execute_with_retry(conn, query) as cursor:
                for business_entity_id, first_name, last_name in cursor.fetchall():
                    print(f"{business_entity_id}\t{first_name}\t{last_name}")
    except mssql_python.Error:
        logger.exception("query failed")
        raise


if __name__ == "__main__":
    main()

Para orientações mais profundas sobre cada preocupação neste exemplo, consulte autenticação Microsoft Entra, Pool de ligações, Encriptação e certificados, Lógica de Retentativas e Tratamento de erros.

Principais características

  • Conformidade com a PEP 249: Interfaces connect, cursor, execute e fetch* padrão, bem como extensões pitónicas.
  • Conectividade Direta à Base de Dados (DDBC): Não é necessário gestor externo de drivers. Instala mssql-python e estás pronto para ligar.
  • Autenticação Microsoft Entra ID: Suporte integrado para modos de autenticação, incluindo identidades geridas e princípios de serviço.
  • SQL Server e autenticação do Windows: inícios de sessão SQL, Kerberos e single sign-on (SSO) do Windows em plataformas suportadas.
  • Cópia em massa: Inserção em massa de alto desempenho para grandes cargas de dados com suporte nativo do protocolo TDS.
  • Suporte nativo para tipos de dados: JSON, XML, espaciais, colunas esparsas, datetimeoffset e decimal/moeda com processamento preciso.
  • Integração com Apache Arrow: Conjuntos de resultados sem cópias para troca rápida de dados com pandas, Polars e DuckDB.
  • Padrões assíncronos: Utilize o driver com aplicações baseadas em asyncio e o FastAPI, recorrendo a soluções alternativas com o ThreadPoolExecutor. Veja padrões assíncronos para padrões de integração.
  • TLS por defeito: encriptação TLS e validação de certificados ativada por defeito (via ODBC Driver 18). A encriptação TDS 8.0 está disponível quando defines Encrypt=strict.

Introdução

Artigo Descrição
Installation Instala mssql-python e verifica o teu ambiente Python.
Início rápido: Ligue-se ao mssql-python Ligue-se a uma instância local ou teste do SQL Server e execute a sua primeira consulta.
Início Rápido: Liga-te a partir de um Jupyter Notebook Usa mssql-python dentro de um caderno para exploração interativa de dados.
Início rápido: Cópia em massa Mover grandes conjuntos de dados para o SQL Server com a API de cópia em massa.
Início rápido: Prototipagem rápida Cria scripts pequenos e provas de conceito rapidamente.
Início Rápido: Implementações repetíveis Empacote, configure e envie aplicações Python que comuniquem com SQL.
Arranque rápido do Apache Arrow Buscar resultados de consultas como tabelas Apache Arrow para fluxos de trabalho analíticos.

Configurar e autenticar

Artigo Descrição
Cadeias de ligação Sintaxe de cadeias de ligação, palavras-chave comuns e exemplos.
Construir cadeias de ligação programaticamente Componha cadeias de ligação com segurança a partir da configuração e dos segredos.
Gestão de ligações Abra, reutiliza e fecha as ligações de forma limpa.
Pool de conexões Otimização do pool, ciclos de vida e padrões de reutilização.
Encriptação e certificados Modos de encriptação TLS, validação de certificados e TDS 8.0.
Autenticação do Microsoft Entra Autenticação sem palavra-passe para SQL do Azure com identidade gerida, principal de serviço, fluxos interativos e código de dispositivo.
Práticas recomendadas de segurança Parametrização, gestão de segredos, privilégios mínimos e encriptação.
Grupos de disponibilidade Ligue-se a grupos de disponibilidade Always On e a réplicas só de leitura.

Trabalhar com dados

Artigo Descrição
Execução de consultas execute, executemany, lotes de múltiplas instruções e conjuntos de resultados.
Recuperação de dados fetchone, fetchmany, fetchall, e padrões de fluxo.
Consultas parametrizadas Associe parâmetros de forma segura para evitar a injeção de SQL.
Procedimentos armazenados Chamar procedimentos, ler parâmetros de saída e processar conjuntos de resultados.
Gestão do cursor Tempo de vida dos cursores, scroll e ajuste do tamanho do array.
Objetos de linha Aceder às linhas por índice, nome ou como mapeamentos.
Gestão de transações Confirmação, rollback, pontos de restauro e níveis de isolamento.
Paginação Padrões de paginação por keyset e por offset em grandes conjuntos de resultados.
Tratamento de erros mssql_python.Error, DatabaseError, e estrutura de erro do SQL Server.
Lógica de repetição Detetar erros transitórios e tentar novamente com recuo exponencial.

Tipos de dados e funcionalidades do SQL Server

Artigo Descrição
Mapeamentos de tipo de dados Tabelas e regras de conversão do tipo SQL Server para Python.
Gestão de data e hora datetime, datetime2, datetimeoffset, e considerações de fuso horário.
Tipos decimais e monetários Tipos numéricos exatos e precisão de decimal.Decimal
Cadeias de carateres e dados Unicode varchar, nvarchar, colações e páginas de código.
Tratamento de NULL Lógica de três valores, sentinelas e interoperabilidade com o pandas.
Dados binários varbinary, image e transmissão de objetos de grande dimensão.
Conversores de tipo personalizado Registe conversores de entrada e saída para tipos personalizados.
Operações de cópia em massa Inserções de alta taxa com a API de cópia em massa.
Dados JSON Armazenar, consultar e triturar JSON com FOR JSON e OPENJSON.
Dados XML Trabalhar com o tipo de dados xml, XPath e XQuery.
Dados espaciais geometry e geography tipos do Python.
Colunas esparsas Colunas esparsas e conjuntos de colunas para tabelas largas.
Descoberta de esquema Inspecionar bases de dados, tabelas, colunas e índices.

Integrar com ferramentas e frameworks de Python

Artigo Descrição
Integração com Apache Arrow Obtenha os resultados como tabelas Arrow para análises sem cópia.
Integração com o Pandas Carregue os resultados das consultas nos DataFrames e escreva-os de volta.
Integração com Polars Use Polars com mssql-python para cargas de trabalho em colunas.
Integração com DuckDB Consulta os dados do SQL Server juntamente com tabelas locais do DuckDB.
Integração com FastAPI Ligar mssql-python aos serviços FastAPI.
Integração com o Flask Usa mssql-python em aplicações Flask.
Padrões assíncronos Combine mssql-python com asyncio e agrupamentos de threads.
Padrões de acesso a dados e análise Escolha o caminho de leitura certo para acesso por cursor, extração com Arrow, pandas, Polars e análises com DuckDB sobre dados SQL.
Padrões de carregamento e movimento de dados Escolha o caminho de escrita correto para inserções de linhas, cópia em massa, MERGE upserts, carregamento de DataFrame e ingestão de CSV.

Implantar e operar

Artigo Descrição
Contentores e desenvolvimento local Configurar contentores Docker, devcontainers e pipelines de CI para aplicações Python que se ligam a bases de dados SQL.
Afinação de desempenho Ajuste de pool, declarações preparadas, tamanhos de lote e cópia em massa.
Troubleshooting Erros comuns, registo e diagnóstico de certificados.
Configuração do módulo Definições ao nível do módulo, hooks de registo e flags de funcionalidade.

Migrar para mssql-python

Artigo Descrição
Migrar de pyodbc Mapeie as APIs do pyodbc e as strings de ligação para o mssql-python.
Migrar de pymssql Substitua o pymssql por mssql-python preservando o comportamento.
Migrar a partir do SQLite Mover cargas de trabalho SQLite locais para SQL Server ou SQL do Azure.
Migrar a partir do PostgreSQL Guia único para programadores Python a migrar do PostgreSQL para o SQL Server com mssql-python.

Conteúdo relacionado

  • Last updated on