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
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;"
)
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
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. |
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
Referens
| Artikel |
Beskrivning |
|
Supportlivscykel |
Stödde Python- och SQL Server-versioner samt uppdateringsfrekvens. |
|
Nyheter |
Versionshistorik och versionshöjdpunkter. |
Relaterat innehåll