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

Ez a minta az Azure SQL-hez csatlakozik menedzselt identitással és Tabular Data Stream (TDS) 8.0 titkosítással. A környezeti változókból olvas kapcsolati beállításokat, és külön bejelentkezési és lekérdezési időkorlátokat állít be. Minden újrapróbálkozás újra meghívja a connect() elemet a sikertelen kapcsolatobjektum újrafelhasználása helyett. A kontextusmenedzserek minden próbálkozás után elengedik a kapcsolatot és a kurzort.

Ezt a segítőt csak olyan idempotens olvasási lekérdezésekhez használd, amelyeket biztonságosan lehet ismételni. Ne használd egyedi írások vagy részben befejezett tranzakciók újrajátszá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.

Az Azure hibaellenőrzése egyezik a szabványos angol 40501-es hibaüzenettel, még akkor is, ha a diagnosztika kihagyja a hibaszámot. A ddbc_error elemet is ellenőrzi ismert számok szempontjából, ha jelen van. A párosítás nem garantált: a lokalizált vagy más formázott üzenetek nem biztos, hogy egyeznek. További információért lásd: Átmeneti kapcsolati hibák.

import logging
import os
import re
import time

import mssql_python

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

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

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 query_with_retry(
    conn_str: str,
    sql: str,
    *params,
    max_attempts: int = 3,
    login_timeout_s: int = 5,
    query_timeout_s: int = 10,
) -> list:
    """Fetch an idempotent read query, reconnecting before each retry."""
    for attempt in range(1, max_attempts + 1):
        try:
            with mssql_python.connect(conn_str, timeout=login_timeout_s) as conn:
                conn.timeout = query_timeout_s
                with conn.cursor() as cursor:
                    cursor.execute(sql, *params)
                    rows = cursor.fetchall()
            logger.info("query succeeded on attempt %d/%d", attempt, max_attempts)
            return rows
        except mssql_python.Error as exc:
            azure_throttling = is_azure_throttling(exc)
            transient = (
                isinstance(exc, mssql_python.OperationalError)
                and exc.driver_error in TRANSIENT_DRIVER_ERRORS
            )
            if not (transient or azure_throttling) or attempt == max_attempts:
                logger.error("query failed on attempt %d/%d: %s", attempt, max_attempts, exc.driver_error)
                raise
            delay = (10 if azure_throttling else 1) * (2 ** (attempt - 1))
            logger.warning(
                "query attempt %d/%d hit transient error %r; retrying in %ds",
                attempt, max_attempts, exc.driver_error, delay,
            )
            time.sleep(delay)
    raise ValueError("max_attempts must be at least 1")


def main() -> None:
    # Read configuration from the environment; never hard-code secrets.
    server = os.environ["SQL_SERVER"]      # for example, <server>.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:
        rows = query_with_retry(conn_str, query)
        for business_entity_id, first_name, last_name in rows:
            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.
  • Alapértelmezett TLS: TLS titkosítás és tanúsítvány ellenőrzése alapértelmezetten bekapcsolva mindkét natív ODBC szolgáltatóval. 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
mssql-odbc provider (Preview) Válaszd ki a preview natív szolgáltatót, és nézd át a támogatott funkciókat és ismert problémákat.
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.
FastAPI alkalmazások tesztelése és telepítése Konfigurálja a FastAPI szolgáltatások poolingjét, hibáit, hitelesítését, tesztjeit és telepítési beállításokat.
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 Találj útmutatást tünet vagy hibaüzenet alapján.
Telepítés és csatlakozási hibakeresés Oldd meg a telepítési, csatlakozási, konténer- és CI problémákat.
Lekérdezés, adat és működési hibakeresés Oldd meg a lekérdezési, adattípus, teljesítményi, tranzakciók és tömeges másolási problémákat.
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.

Szolgáltatás igénylése

Funkció kéréséhez nyiss meg egy problémát az mssql-python GitHub repozióriumban.

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: