Microsoft Python-stuurprogramma voor SQL Server - mssql-python

mssql-python is het Python-stuurprogramma van Microsoft voor SQL Server, Azure SQL Database, Azure SQL Managed Instance en de SQL-database in Microsoft Fabric. Het gebruikt Direct Database Connectivity (DDBC), zodat je kunt verbinden zonder een externe driver manager te installeren. De driver ondersteunt Python 3.10 of later en voldoet aan de Python Database API Specification 2.0, terwijl er Python-vriendelijke verbeteringen worden toegevoegd voor dagelijkse ontwikkeling.

Uw beginpunt kiezen

Productiebasislijn voor Azure SQL

Gebruik dit voorbeeld als uitgangspunt voor een productiegerichte Azure SQL-verbinding. Het leest configuraties uit de omgeving, authenticeert met beheerde identiteit en schakelt Tabular Data Stream (TDS) 8.0-encryptie in. Het stelt ook time-outs voor aanmelden en per statement/query in, probeert tijdelijke fouten opnieuw met exponentiële back-off (een nieuwe verbinding bij verbindingsfouten, dezelfde verbinding bij queryfouten zoals deadlocks), registreert de resultaten en vertrouwt op contextmanagers om resources vrij te geven.

De ConnectRetryCount en ConnectRetryInterval trefwoorden in de verbindingsreeks maken de veerkracht van de idle-verbinding van SQL Server mogelijk: de driver maakt transparant opnieuw verbinding met een verbroken idle-verbinding. Dat verschilt van de herhalingspoging op toepassingsniveau in dit voorbeeld, waarbij een query opnieuw wordt uitgevoerd als die mislukt door een tijdelijke fout, zoals een deadlock of een time-out van een query. De twee vullen elkaar aan, dus houd ze allebei.

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

Voor diepere richtlijnen over elk probleem in dit voorbeeld, zie Microsoft Entra authenticatie, Connection pooling, Encryption and certificates, Retry logic en Error handling.

Belangrijkste kenmerken

  • PEP 249-conformiteit: standaard connect, cursor, execute, en fetch* interfaces, plus Pythonic-extensies.
  • Direct Database Connectivity (DDBC): Geen externe drivermanager vereist. Installeer mssql-python het en je bent klaar om te verbinden.
  • Microsoft Entra ID-authenticatie: Ingebouwde ondersteuning voor authenticatiemodi, inclusief beheerde identiteiten en servicehoofden.
  • SQL Server en Windows authentication: SQL-logins, Kerberos en Windows single sign-on (SSO) op ondersteunde platforms.
  • Bulkkopiëren: Bulkinvoeging met hoge prestaties voor grote gegevensladingen met ondersteuning voor het native TDS-protocol.
  • Ondersteuning voor native datatypes: JSON, XML, ruimtelijk, spaarzame kolommen, datetimeoffset en decimaal/money met precieze afhandeling.
  • Apache Arrow-integratie: Zero-copy resultaatsets voor snelle gegevensuitwisseling met pandas, Polars en DuckDB.
  • Async-patronen: Gebruik de driver met asyncio-gebaseerde applicaties en FastAPI via ThreadPoolExecutor-workarounds. Zie Async-patronen voor integratiepatronen.
  • TLS standaard: TLS-encryptie en certificaatvalidatie standaard aan (via ODBC Driver 18). TDS 8.0-versleuteling is beschikbaar wanneer je Encrypt=strict instelt.

Aan de slag

Artikel Beschrijving
Installation Installeer mssql-python en verifieer je Python-omgeving.
Quickstart: Maak verbinding met mssql-python Maak verbinding met een lokale of test SQL Server-instantie en voer je eerste query uit.
Quickstart: Verbind vanaf een Jupyter Notebook Gebruik mssql-python in een notitieboek voor interactieve data-exploratie.
Snelstart: bulkkopiëren Verplaats grote datasets naar SQL Server met de bulk copy API.
Quickstart: Snel prototypen Bouw snel kleine scripts en proofs of concept.
Quickstart: Herhaalbare inzetten Pak, configureer en verzend Python-applicaties die met SQL communiceren.
Apache Arrow quickstart Haal queryresultaten op als Apache Arrow-tabellen voor analytics-workflows.

Configureren en authenticeren

Artikel Beschrijving
Verbindingsreeksen Verbindingsstringsyntaxis, veelvoorkomende trefwoorden en voorbeelden.
Bouw verbindingsstrings programmatisch Stel verbindingsstrings veilig samen uit configuratie en geheimen.
Verbindingsbeheer Open, hergebruik en sluit de verbindingen netjes.
Groepsgewijze verbindingen Zwembadafstemming, levensduur- en hergebruikpatronen.
Encryptie en certificaten TLS-encryptiemodi, certificaatvalidatie en TDS 8.0.
Microsoft Entra-authenticatie Wachtwoordloze authenticatie voor Azure SQL met beheerde identiteits-, serviceprincipal-, interactieve en apparaatcodeflows.
Aanbevolen procedures voor beveiliging Parameters, geheimenbeheer, minimale bevoegdheden en versleuteling.
Beschikbaarheidsgroepen Verbind met Always On-beschikbaarheidsgroepen en replica's voor alleen-lezen.

Werken met gegevens

Artikel Beschrijving
Uitvoeren van queries execute, executemany, batches met meerdere instructies, en resultaatsets.
Data ophalen fetchone, fetchmany, , fetchallen stroompatronen.
Geparameteriseerde query’s Koppel parameters veilig om SQL-injectie te voorkomen.
Opgeslagen procedures Roep procedures aan, lees uitvoerparameters en verwerk resultaatsets.
Cursorbeheer De levensduur van cursors, scrollen en het afstemmen van de arraygrootte.
Rijobjecten Toegang tot rijen via index, naam of als mappings.
Transactiebeheer Bevestigen, terugdraaien, opslagpunten en isolatieniveaus.
Paginering Keyset- en offset-pagineringspatronen voor grote resultaatsets.
Foutafhandeling mssql_python.Error, DatabaseError, en SQL Server-foutstructuur.
Logica voor opnieuw proberen Detecteer tijdelijke fouten en probeer opnieuw met exponentiële backoff.

SQL Server-gegevenstypen en -functies

Artikel Beschrijving
Gegevenstypetoewijzingen Typetabel en conversieregels van SQL Server naar Python.
Afhandeling van datum en tijd datetime, datetime2, , datetimeoffseten tijdzoneoverwegingen.
Decimale en geldtypen Exacte numerieke types en decimal.Decimal precisie.
String- en Unicode-gegevens varchar, nvarchar, collaties en codepagina's.
NULL-afhandeling Driewaardelogica, sentinels en interoperabiliteit met pandas.
Binaire gegevens varbinary, image, en het streamen van grote objecten.
Aangepaste typeconverters Registreer invoer- en uitgangsomzetters voor aangepaste types.
Bewerkingen voor bulkkopiëren Invoegingen met hoge verwerkingssnelheid via de bulk copy-API.
JSON-gegevens Opslaan, opvragen en versnipperen JSON met FOR JSON en OPENJSON.
XML-gegevens Werk met het xml datatype, XPath en XQuery.
Ruimtelijke gegevens geometry- en geography-typen uit Python.
Sparse kolommen Spaarzame kolommen en kolomsets voor brede tabellen.
Schemadetectie Inspecteer databases, tabellen, kolommen en indexen.

Integreer met Python-tools en frameworks

Artikel Beschrijving
Apache Arrow-integratie Haal resultaten op als Arrow-tabellen voor zero-copy analytics.
Pandas-integratie Laad queryresultaten in DataFrames en schrijf ze terug.
Polare integratie Gebruik Polars met mssql-python voor kolomwerklasten.
DuckDB-integratie Zoek SQL Server-gegevens samen met lokale DuckDB-tabellen.
FastAPI-integratie Verbind mssql-python met FastAPI-services.
Flask-integratie Gebruik mssql-python in Flask-applicaties.
Asynchroon patronen Combineer mssql-python met asyncio en threadpools.
Gegevenstoegangs- en analysepatronen Kies het juiste leespad voor cursor-toegang, Arrow-extractie, pandas, Polars en DuckDB-analyse over SQL-data.
Data-laad- en bewegingspatronen Kies de juiste schrijfmethode voor het invoegen van rijen, bulkgewijs kopiëren, MERGE upserts, het laden van DataFrames en het importeren van CSV-bestanden.

Implementeren en gebruiken

Artikel Beschrijving
Container en lokale ontwikkeling Zet Docker-containers, devcontainers en CI-pijplijnen op voor Python-applicaties die verbinding maken met SQL.
Performance-optimalisatie Pooltuning, voorbereide statements, batchgroottes en bulk copy.
Troubleshooting Veelvoorkomende fouten, logging en certificaatdiagnostiek.
Moduleconfiguratie Instellingen op moduleniveau, loghooks en featureflags.

Migreren naar mssql-python

Artikel Beschrijving
Migreren vanuit pyodbc Wijs pyodbc-API's en verbindingsreeksen toe aan mssql-python.
Migreren vanuit pymssql Vervang pymssql door mssql-python terwijl het gedrag behouden blijft.
Migreren vanuit SQLite Verplaats lokale SQLite-workloads naar SQL Server of Azure SQL.
Migreren vanuit PostgreSQL One-stop gids voor Python-ontwikkelaars die overstappen van PostgreSQL naar SQL Server met mssql-python.

Verwante onderwerpen

  • Last updated on