Microsoft Python-drivrutin för SQL Server – mssql-python

mssql-pythonär Microsoft Python-drivrutin för SQL Server, Azure SQL Database, Azure SQL Managed Instance och SQL-databas i Microsoft Fabric. Den använder Direct Database Connectivity (DDBC), så du kan ansluta utan att installera en extern drivrutinshanterare. Drivrutinen stöder Python 3.10 eller senare och följer Python Database API Specification 2.0 samtidigt som den lägger till Python-vänliga förbättringar för daglig utveckling.

Välj startpunkt

• För att få ett lokalt SQL Server-exempel att fungera snabbt, börja med Quickstart: Anslut dig till mssql-python-drivrutinen.
• För att ansluta till Azure SQL med lösenordslös autentisering, börja med Microsoft Entra-autentisering och anslutningssträngar.
• För att utforska data interaktivt, börja med Connect from a Jupyter Notebook eller Rapid prototyping.
• För att effektivt flytta stora datamängder, gå till Bulk-kopieringsoperationer eller snabbstart för bulkkopiering.
• För att migrera från en annan drivrutin, gå till Migrera från pyodbc, Migrera från pymssql, Migrera från SQLite eller Migrera från PostgreSQL.

Produktionsbaslinje för Azure SQL

Använd detta exempel som utgångspunkt för en produktionsorienterad Azure SQL-anslutning. Den läser konfiguration från miljön, autentiserar med hanterad identitet och möjliggör Tabular Data Stream (TDS) 8.0-kryptering. Den anger också timeoutvärden för inloggning och för varje enskild fråga, försöker igen vid tillfälliga fel med exponentiellt ökande väntetider (en ny anslutning för anslutningsfel, samma anslutning för frågefel som deadlocker), loggar utfall och förlitar sig på kontexthanterare för att frigöra resurser.

Nyckelorden ConnectRetryCount och ConnectRetryInterval i reťazec pripojenia möjliggör SQL Server passiv anslutningsresiliens: drivrutinen återansluter transparent en tappad vilo-anslutning. Det skiljer sig från omförsöket på applikationsnivå i det här exemplet, där en fråga som misslyckas på grund av ett tillfälligt fel, till exempel en deadlock eller timeout för frågan, körs igen. De två kompletterar varandra, så behåll båda.

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

För djupare vägledning om varje fråga i detta exempel, se Microsoft Entra-autentisering, Anslutningspooling, Kryptering och certifikat, Retry-logik och Felhantering.

Viktiga funktioner

• Efterlevnad av PEP 249: Standardgränssnitten connect, cursor, execute och fetch*, samt Python-anpassade tillägg.
• Direkt databasanslutning (DDBC): Ingen extern drivrutinshanterare krävs. Installera mssql-python och du är redo att ansluta.
• Microsoft Entra ID-autentisering: Inbyggt stöd för autentiseringslägen, inklusive hanterade identiteter och tjänsteprinciper.
• SQL Server och Windows authentication: SQL-inloggningar, Kerberos och Windows single sign-on (SSO) på stödda plattformar.
• Masskopiering: Högpresterande massinfogning för stora datamängder med inbyggt stöd för TDS-protokollet.
• Stöd för inbyggda datatyper: JSON, XML, rumsligt, glesa kolumner, datetimeoffset och decimal/money med exakt hantering.
• Integrering med Apache Arrow: Resultatuppsättningar utan kopiering för snabbt datautbyte med pandas, Polars och DuckDB.
• Asynkrona mönster: Använd drivrutinen med asyncio-baserade applikationer och FastAPI via ThreadPoolExecutor-lösningar. Se Asynkrona mönster för integrationsmönster.
• TLS som standard: TLS-kryptering och certifikatvalidering är aktiverat som standard (via ODBC Driver 18). TDS 8.0-kryptering tillgänglig när du sätter Encrypt=strict.

Kom igång

Artikel	Beskrivning
Installation	Installera mssql-python och verifiera din Python-miljö.
Quickstart: Koppla upp dig mot mssql-python	Anslut dig till en lokal eller test-SQL Server-instans och kör din första fråga.
Quickstart: Koppla upp från en Jupyter Notebook	Använd mssql-python i en anteckningsbok för interaktiv datautforskning.
Snabbstart: Masskopiering	Flytta stora datamängder till SQL Server med bulkkopierings-API:et.
Snabbstart: Snabb prototypframställning	Bygg små skript och konceptbevis snabbt.
Snabbstart: Upprepningsbara utplaceringar	Paketera, konfigurera och leverera Python-applikationer som kommunicerar med SQL.
Apache Arrow snabbstart	Hämta frågeresultat som Apache Arrow-tabeller för analysarbetsflöden.

Konfigurera och autentisera

Artikel	Beskrivning
Anslutningssträngar	Syntax för anslutningssträngar, vanliga nyckelord och exempel.
Bygg anslutningssträngar programmatiskt	Skapa anslutningssträngar på ett säkert sätt utifrån konfiguration och hemligheter.
Anslutningshantering	Öppna, återanvänd och stäng anslutningar ordentligt.
Anslutningspoolning	Pooljustering, livslängder och återanvändningsmönster.
Kryptering och certifikat	TLS-krypteringsläge, certifikatvalidering och TDS 8.0.
Microsoft Entra-autentisering	Lösenordslös autentisering för Azure SQL med flöden av hanterad identitet, tjänsteprincip, interaktiv kod och enhetskod.
Metodtips för säkerhet	Parameterisering, hantering av hemligheter, minsta behörighet och kryptering.
Tillgänglighetsgrupper	Koppla upp dig till Always On-tillgänglighetsgrupper och skrivskyddade repliker.

Arbeta med data

Artikel	Beskrivning
Körning av frågor	execute, executemany, batcher med flera satser och resultatmängder.
Hämta data	fetchone, fetchmany, fetchall och strömningsmönster.
Parametriserade frågor	Bind parametrar säkert för att förhindra SQL-injektion.
Lagrade procedurer	Anropsprocedurer, läsutdataparametrar och processresultatuppsättningar.
Markörhantering	Cursorens livslängd, scrollning och justering av arraystorlek.
Radobjekt	Åtkomst till rader via index, namn eller som mappningar.
Transaktionshantering	Commit, rollback, sparpunkter och isoleringsnivåer.
Paginering	Mönster för keyset- och offset-paginering för stora resultatmängder.
Felhantering	mssql_python.Error, DatabaseError, och felstrukturen i SQL Server.
Logik för omprövning	Identifiera tillfälliga fel och försök igen med exponentiellt ökande väntetid.

SQL Server-datatyper och funktioner

Artikel	Beskrivning
Datatypsmappningar	SQL Server-Python-typtabell och konverteringsregler.
Datetime-hantering	datetime, datetime2, , datetimeoffsetoch tidszonsaspekter.
Decimal- och penningtyper	Exakta numeriska typer och decimal.Decimal precision.
Sträng- och Unicode-data	varchar, nvarchar, kollationer och kodsidor.
NULL-hantering	Trevärdeslogik, sentinelvärden och interoperabilitet med pandas.
Binära data	varbinary, image, och strömning av stora objekt.
Specialtypomvandlare	Registerin- och utgångsomvandlare för anpassade typer.
Masskopieringsoperationer	Infogningar med hög genomströmning med API för masskopiering.
JSON-data	Lagra, fråga och dela upp JSON med FOR JSON och OPENJSON.
XML-data	Arbeta med xml datatypen, XPath och XQuery.
Rumsliga data	geometryoch geography typer från Python.
Glesa kolumner	Glesa kolumner och kolumnuppsättningar för breda tabeller.
Schemalokalisering	Inspektera databaser, tabeller, kolumner och index.

Integrera med Python-verktyg och ramverk

Artikel	Beskrivning
Apache Arrow-integration	Hämta resultat som Arrow-tabeller för zero-copy-analys.
Pandas-integration	Ladda frågeresultat i DataFrames och skriv tillbaka dem.
Polärintegration	Använd Polars med mssql-python för kolumnarbetsbelastningar.
DuckDB-integration	Sök i SQL Server-data tillsammans med lokala DuckDB-tabeller.
FastAPI-integration	Koppla in mssql-python i FastAPI-tjänster.
Flaskintegration	Använd mssql-python i Flask-applikationer.
Asynkrona mönster	Kombinera mssql-python med asyncio och trådpooler.
Dataåtkomst och analysmönster	Välj rätt läsväg för marköråtkomst, Arrow-extraktion, pandas, Polars och DuckDB-analys istället för SQL-data.
Dataladdnings- och rörelsemönster	Välj rätt skrivväg för radinsättningar, bulkkopiering, MERGE upserts, DataFrame-laddning och CSV-inmatning.

Distribuera och driva

Artikel	Beskrivning
Containrar och lokal utveckling	Sätt upp Docker-containrar, devcontainers och CI-pipelines för Python-applikationer som ansluter till SQL.
Prestandaoptimering	Justering av anslutningspooler, förberedda instruktioner, batchstorlekar och masskopiering.
Felsökning	Vanliga fel, loggning och certifikatdiagnostik.
Modulkonfiguration	Inställningar på modulnivå, loggningskrokar och funktionsflaggor.

Migrera till mssql-python

Artikel	Beskrivning
Migrera från pyodbc	Mappa pyodbc-API:er och anslutningssträngar till mssql-python.
Migrera från pymssql	Byt ut pymssql mot mssql-python samtidigt som beteendet bevaras.
Migrera från SQLite	Flytta lokala SQLite-arbetsbelastningar till SQL Server eller Azure SQL.
Migrera från PostgreSQL	En enda guide för Python-utvecklare som går från PostgreSQL till SQL Server med mssql-python.

Relaterat innehåll

• Supportlivscykel för mssql-python
• Vad är nytt i mssql-python
• mssql-python på GitHub
• mssql-python på PyPI
• Viktig information
• Översikt
• Azure Python-utvecklarcenter
• Python Database API-specifikation 2.0