Microsoft Python Driver for SQL Server – mssql-python

mssql-python a Microsoft Python-illesztőprogramja az SQL Serverhez, az Azure SQL Database-hez, az Azure SQL Managed Instance-hez és a Microsoft Fabric SQL-adatbázisához. Közvetlen adatbázis-kapcsolatot (DDBC) használ, így csatlakozhatsz anélkül, hogy külső driver manager telepítenéd. A meghajtó támogatja a Python 3.10-et vagy újabb verziókat, és megfelel a Python Database API Specification 2.0-nak, miközben Python-barát fejlesztéseket ad a mindennapi fejlesztéshez.

Válassza ki a kiindulási pontot

Azure SQL üzemi alapkonfigurációja

Ezt a mintát használd kiindulópontként egy termelésorientált Azure SQL kapcsolathoz. A környezet konfigurációit olvassa fel, menedzselt identitással autentikál, és lehetővé teszi a Tabular Data Stream (TDS) 8.0 titkosítást. Emellett beállítja a bejelentkezési és kijelentésenkénti lekérdezési időkorlátokat, újrapróbálja az átmeneti hibákat exponenciális visszacsatolással (egy friss kapcsolat a kapcsolati hibák esetén, ugyanaz a kapcsolat lekérdezési hibáknál, mint a holtpont esetén), naplózi az eredményeket, és kontextuskezelőkre támaszkodik az erőforrások felszabadítására.

A kapcsolati karakterláncban szereplő ConnectRetryCount és ConnectRetryInterval kulcsszavak lehetővé teszik az SQL Server inaktív kapcsolatokkal szembeni rugalmasságát: az illesztőprogram automatikusan újracsatlakozik egy megszakadt inaktív kapcsolathoz. Ez eltér az alkalmazásszintű újrapróbálkozástól ebben a mintában, amely újrapróbálja a meghibásodott lekérdezést, például holtpont vagy lekérdezési időkérés esetén. A kettő kiegészítő jellegű, szóval mindkettőt tartsd meg.

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

A mintavételben található problémák részletesebb útmutatásáért lásd Microsoft Entra hitelesítést, kapcsolati poolinget, titkosítást és tanúsítványokat, újrapróbálkozási logikát és hibakezelést.

Legfontosabb funkciók

  • PEP 249-kompatibilitás: A szabványos connect, cursor, execute és fetch* interfészek, valamint Pythonos kiterjesztések.
  • Közvetlen adatbázis-kapcsolat (DDBC): Nem szükséges külső driver manager. Telepítsd mssql-python be, és készen állsz a csatlakozásra.
  • Microsoft Entra ID hitelesítés: Beépített támogatás az autentifikációs módokhoz, beleértve a menedzselt identitásokat és szolgáltatáselveket.
  • SQL Server és Windows authentication: SQL bejelentkezések, Kerberos és Windows single sign-on (SSO) támogatott platformokon.
  • Tömeges másolás: Nagy teljesítményű tömeges beszúrás nagy adatmennyiségek betöltéséhez, natív TDS-protokoll támogatásával.
  • Natív adattípusok támogatása: JSON, XML, térbeli oszlopok, datetimeoffset és tizedes/pénz pontosan kezelhető.
  • Apache Arrow integráció: Zero-copy eredményhalmazok gyors adatcseréhez pandas, Polars és DuckDB között.
  • Aszinkron működési minták: Az illesztőprogram használata asyncio-alapú alkalmazásokkal és FastAPI-val ThreadPoolExecutor-alapú kerülőmegoldásokkal. Lásd az aszinkron mintákat az integrációs mintákért.
  • TLS alapértelmezettben: TLS titkosítás és tanúsítvány ellenőrzése alapértelmezetten bekapcsolva (ODBC Driver 18-on keresztül). TDS 8.0 titkosítás elérhető, ha beállítod Encrypt=strict.

Első lépések

Cikk Leírás
Installation Telepítsd mssql-python és ellenőrizd a Python környezetedet.
Gyorsindítás: Kapcsolódj mssql-pythonhoz Csatlakozz egy helyi vagy tesztelő SQL Server példányhoz, és futtasd le az első lekérdezést.
Gyorsindítás: Csatlakozz egy Jupyter Notebook-ból Használd az mssql-pythont egy notebookon belül interaktív adatfeltáráshoz.
Gyorsindítás: Tömeges másolat Nagy adathalmazokat helyezz át az SQL Server-be a tömeges másolati API-val.
Gyorsindítás: Gyors prototípus Gyorsan építs kis szkripteket és koncepcióbizonyításokat.
Gyorsindítás: Ismételhető telepítések Csomagolj, konfigurálj és szállíts olyan Python alkalmazásokat, amelyek SQL-lel kommunikálnak.
Apache Arrow gyorsindítás A lekérdezési eredmények lekérése Apache Arrow-táblákként elemzési munkafolyamatokhoz.

Konfigurálás és hitelesítés

Cikk Leírás
Kapcsolati karakterláncok Kapcsolati lánc szintaxis, gyakori kulcsszavak és példák.
Kapcsolati stringek építése programozott módon Biztonságosan állítsa össze a kapcsolati karakterláncokat konfigurációból és titkos adatokból.
Kapcsolatkezelés Nyisd ki, használd újra és zárd le tisztán a csatlakozásokat.
Kapcsolatkészletezés Medencének hangolása, élettartama és újrahasználati minták.
Titkosítás és tanúsítványok TLS titkosítási módok, tanúsítvány ellenőrzése és TDS 8.0.
Microsoft Entra-hitelesítés Jelszó nélküli hitelesítés Azure SQL-hez, kezelt identitással, szolgáltatási alapokkal, interaktív és eszközkód flow-okkal.
biztonsági ajánlott eljárások Paraméterezés, titkos kódok kezelése, minimális jogosultság és titkosítás.
Rendelkezésre állási csoportok Csatlakozzon Always On rendelkezésre állási csoportokhoz és csak olvasható replikákhoz.

Adatkezelés

Cikk Leírás
Lekérdezések végrehajtása execute, executemany, több utasításból álló kötegek és eredményhalmazok.
Adatok visszakeresése fetchone, fetchmany, fetchall és streamelési minták.
Paraméteres lekérdezések Biztonságosan kötni a paramétereket, hogy elkerüld az SQL befecskendezését.
Tárolt eljárások Hívd meg az eljárásokat, olvasd el a kimeneti paramétereket és feldolgozza az eredményhalmazokat.
Kurzor kezelés Kurzorok élettartama, görgetés és a tömbméret finomhangolása.
Sorobjektumok A sorokhoz index, név vagy leképezések alapján lehet hozzáférni.
Tranzakciókezelés Kötelezés, visszagörgetés, mentési pontok és izolációs szintek.
Tördelés Kulcskészletes és eltolásos lapozási minták nagy eredményhalmazok esetén.
Hibakezelés mssql_python.Error, DatabaseError, és SQL Server hibaszerkezete.
Újrapróbálkozási logika Észleld az átmeneti hibákat, és próbáld újra exponenciális visszalépéssel.

SQL Server adattípusok és funkciók

Cikk Leírás
Adattípus-leképezések SQL Server-to-Python típusú tábla és átalakítási szabályok.
Dátumidőkezelés datetime, datetime2, datetimeoffset, , és időzóna szempontok.
Tizedes és pénztípusok Pontos numerikus típusok és decimal.Decimal pontosság.
String és Unicode adatok varchar, nvarchar, összeállítások és kódoldalak.
NULL kezelése Háromértékű logika, őrök és pandák egymás között működnek.
Bináris adatok varbinary, image, és nagyméretű objektumok streamelése.
Egyedi típusú átalakítók Regisztrálja az egyedi típusokhoz tartozó bemeneti és kimeneti konvertereket.
Tömeges másolási műveletek Nagy átviteli sebességű beszúrások a tömeges másolási API-val.
JSON adatok Tárolja, kérdezze le és darabolja fel a JSON-adatokat a FOR JSON és OPENJSON segítségével.
XML adatok Dolgozz az xml adattípussal, az XPath-tal és az XQuery-vel.
Térbeli adatok geometryés geography a Python-ból származó típusok.
Takarékos oszlopok Ritka oszlopok és oszlopkészletek széles asztalokhoz.
Sémafelderítés Adatbázisokat, táblákat, oszlopokat és indexeket vizsgálja.

Integrálás Python eszközökkel és keretrendszerekkel

Cikk Leírás
Apache Arrow integráció Az eredmények lekérése Arrow-táblák formájában másolás nélküli elemzéshez.
pandas-integráció Töltsd be a lekérdezési eredményeket a DataFrame-be, és írd vissza őket.
Polars-integráció Használd a Polars-t mssql-python-szal columnáris munkaterhelésekhez.
DuckDB integráció Kérdezze le az SQL Server adatait a helyi DuckDB-táblákkal együtt.
FastAPI integráció Integráld a mssql-pythont a FastAPI-szolgáltatásokba.
Flaskos integráció Használj mssql-pythont a Flask alkalmazásokban.
Aszinkron minták Kombináld az mssql-pythont a asyncio thread poolokkal.
Adathozzáférés és elemzési minták Válaszd ki a megfelelő beolvasási módot a kurzorhozzáféréshez, az Arrow-adatkinyeréshez, valamint a pandas-, Polars- és DuckDB-elemzéshez SQL-adatokon.
Adatbetöltés és mozgási minták Válassza ki a megfelelő írási módot sorbeszúrásokhoz, tömeges másoláshoz, MERGE upsert műveletekhez, DataFrame-ek betöltéséhez és CSV-fájlok beolvasásához.

Üzembe helyezés és üzemeltetés

Cikk Leírás
Konténeres és helyi fejlesztés Állíts be Docker konténereket, devcontainereket és CI pipeline-okat Python alkalmazásokhoz, amelyek SQL-hez csatlakoznak.
Teljesítmény finomhangolása Medencének hangolása, előkészített nyilatkozatok, adagméretek és tömeges másolat.
Troubleshooting Gyakori hibák, naplózás és tanúsítvány diagnosztika.
Modul konfiguráció Modul-szintű beállítások, naplózó hookok és funkciózászlók.

Migrálás erre: mssql-python

Cikk Leírás
Migrálás a pyodbc-ről Térképezd a pyodbc API-kat és a kapcsolati stringeket mssql-pythonra.
Migráció a pymssql-ből Cseréld le a pymssql-t mssql-pythonra, úgy, hogy közben megőrzöd a működést.
Migráció az SQLite-ről Helyezze át a helyi SQLite-munkaterheléseket az SQL Serverbe vagy az Azure SQL-be.
Migrálás a PostgreSQL-ből Átfogó útmutató az mssql-pythont használó, PostgreSQL-ről SQL Serverre váltó Python-fejlesztőknek.

Hivatkozás

Cikk Leírás
Támogatási életciklus Támogattam a Python és SQL Server verziókat, valamint frissítési ütemet.
Újdonságok Verzióelőzmények és kiadási kiemelések.

Kapcsolódó tartalom

  • Last updated on