Hantera anslutningar med mssql-python

De flesta applikationer följer ett enkelt mönster: öppna en anslutning, kör frågor, stäng anslutningen. Följande avsnitt täcker öppning och stängning av anslutningar, användning av kontexthanterare, konfiguration av autocommit och arbete med anslutningsattribut.

Öppna en anslutning

Använd connect() funktionen för att skapa en kontakt. Ange en anslutningssträng som innehåller information om server, databas och autentisering:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;"
    "Authentication=ActiveDirectoryDefault;Encrypt=yes"
)

Funktionen connect() tar emot:

  • En anslutningssträng som första positionsargument eller nyckelordet connection_str.
  • Individuella nyckelord som drivrutinen sammanfogar till anslutningssträngen.
  • Andra alternativ som autocommit, timeout, och attrs_before.

Du kan blanda båda metoderna. Nyckelord åsidosätter värden i anslutningssträngen, vilket är användbart när du lagrar en grundläggande anslutningssträng i konfigurationen och åsidosätter inställningar som timeout vid varje anrop:

# Base connection string from config, with per-call overrides
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;"
    "Authentication=ActiveDirectoryDefault;Encrypt=yes",
    timeout=30,
    autocommit=True
)

Stäng en förbindelse

Stäng alltid anslutningarna när du är klar för att återlämna dem till anslutningspoolen och frigöra serverresurser. Oslutna anslutningar håller serverminne och kan så småningom tömma anslutningspoolen, vilket gör att nya anslutningsförsök blockeras eller misslyckas.

conn = mssql_python.connect(connection_string)
try:
    # Use the connection
    cursor = conn.cursor()
    cursor.execute("SELECT 1")
finally:
    conn.close()

När anslutningen är stängd kan den inte användas:

conn.close()
print(conn.closed)  # True

# This raises an error
cursor = conn.cursor()  # InterfaceError: Cannot create cursor on closed connection

Att anropa close() flera gånger är säkert (idempotent):

conn.close()
conn.close()  # No error

Kontexthanterare

Använd satsen with för att hantera anslutningar i de flesta applikationer. Den garanterar att drivrutinen stänger anslutningen när blocket avslutas, även om ett undantag inträffar. Denna metod eliminerar risken för läckta anslutningar från bortglömda close() samtal:

with mssql_python.connect(connection_string) as conn:
    cursor = conn.cursor()
    cursor.execute("CREATE TABLE #Demo (Name NVARCHAR(50))")
    cursor.execute("INSERT INTO #Demo (Name) VALUES ('Widget')")
    conn.commit()  # Must commit explicitly when autocommit=False
# Connection automatically closed

Kontexthanteraren stänger anslutningen vid utgång. Den genomför eller återställer inte transaktioner automatiskt:

  • Alltid: Anropar close() vid avslut, oavsett om ett undantag inträffade eller inte.
  • close() beteende: Omautocommit=False , rullas alla obundna ändringar tillbaka när anslutningen stängs.
  • Du måste anropa conn.commit() explicit för att spara ändringarna.

Denna design följer PEP 249-beteende och förhindrar oavsiktliga partiella commits. Om din kod skapar ett undantag innan den når commit(), rullas den pågående transaktionen säkert tillbaka:

# Equivalent manual code:
conn = mssql_python.connect(connection_string)
try:
    cursor = conn.cursor()
    cursor.execute("CREATE TABLE #Demo (Name NVARCHAR(50))")
    cursor.execute("INSERT INTO #Demo (Name) VALUES ('Widget')")
    conn.commit()  # Must commit explicitly
finally:
    conn.close()  # Rolls back uncommitted changes if autocommit=False

Autocommit-läge

Som standard är autocommit=False, vilket innebär att varje instruktion körs i en implicit transaktion. Du måste ringa conn.commit() för att behålla ändringar eller conn.rollback() för att kassera dem. Implicita transaktioner är det säkraste valet för dataändringar eftersom det låter dig gruppera flera satser till en enda atomär operation.

Aktivera automatisk bekräftelse när du vill att varje sats ska bekräftas omedelbart. Autocommit är användbart för DDL-operationer (CREATE TABLE, ALTER INDEX), arbetsbelastningar med enbart läsning eller administrativa skript där gruppering av transaktioner inte behövs:

conn = mssql_python.connect(connection_string)
print(conn.autocommit)  # False

cursor = conn.cursor()
cursor.execute("CREATE TABLE #Demo (Name NVARCHAR(50))")
cursor.execute("INSERT INTO #Demo (Name) VALUES ('Widget')")
conn.commit()  # Required to persist changes

Aktivera autocommit för varje sats så att den bekräftas omedelbart. Använd autocommit=True vid anslutningstillfället, eller växla det efter anslutning med setautocommit() eller genom direkt tilldelning av egenskap:

# At connection time
conn = mssql_python.connect(connection_string, autocommit=True)

# Or after connection (both forms work)
conn.setautocommit(True)
conn.autocommit = True
print(conn.autocommit)  # True

# Now changes are committed automatically
cursor = conn.cursor()
cursor.execute("SELECT TOP 1 Name FROM Production.Product")
print(cursor.fetchone().Name)
# No commit() needed

Tidsgräns för anslutning

Ställ in anslutningstimeout för att styra hur länge drivrutinen väntar med att etablera en anslutning innan det ger ett felmeddelande. En rimlig timeout för anslutning är viktig för applikationer som driftsätts i miljöer med opålitliga nätverk eller för att snabbt misslyckas när en server inte går att nå:

# At connection time (in seconds)
conn = mssql_python.connect(connection_string, timeout=30)

# Or after connection
conn.timeout = 60
print(conn.timeout)  # 60

Ett timeout-värde på 0 innebär ingen timeout (vänta på obestämd tid). Definiera rimliga tidsgränser i produktion; ett anslutningsförsök som hänger sig utan tidsgräns blockerar den anropande tråden permanent.

Anslutningsattribut

Använd set_attr() för att ändra anslutningsbeteende vid körning. Anslutningsattribut styr lågnivådrivrutinsinställningar som åtkomstläge, transaktionsisolering och paketstorlek. De flesta applikationer behöver inte ändra dessa attribut, men de är användbara i specifika scenarier:

  • Skrivskyddat läge: Förhindrar oavsiktliga skrivningar i rapporteringsfrågor.
  • Transaktionsisolering: Kontrollerar hur samtidiga transaktioner interagerar (använd SERIALIZABLE för strikt konsistens, READ_COMMITTED för allmän användning).
  • Paketstorlek: Justera för nätverk med hög latens eller hög genomströmning.
import mssql_python

conn = mssql_python.connect(connection_string)

# Set read-only mode
conn.set_attr(mssql_python.SQL_ATTR_ACCESS_MODE, mssql_python.SQL_MODE_READ_ONLY)

# Set transaction isolation level
conn.set_attr(mssql_python.SQL_ATTR_TXN_ISOLATION, mssql_python.SQL_TXN_SERIALIZABLE)

Tillgängliga attribut:

Konstant Beskrivning
SQL_ATTR_CONNECTION_TIMEOUT Tidsgräns för anslutning i sekunder.
SQL_ATTR_LOGIN_TIMEOUT Tidsgräns för inloggning i sekunder.
SQL_ATTR_PACKET_SIZE Storlek på nätverkspaket.
SQL_ATTR_ACCESS_MODE Skrivskyddat eller läs-skriv-läge.
SQL_ATTR_TXN_ISOLATION Transaktionsisoleringsnivå.
SQL_ATTR_CURRENT_CATALOG Nuvarande databasnamn.

Prekonnektivitetsattribut

Vissa attribut måste anges innan drivrutinen upprättar en anslutning (till exempel tidsgräns för inloggning). Skicka dem igenom attrs_before:

conn = mssql_python.connect(
    connection_string,
    attrs_before={
        mssql_python.SQL_ATTR_LOGIN_TIMEOUT: 30,
        mssql_python.SQL_ATTR_CONNECTION_TIMEOUT: 60,
    }
)

Hämta anslutningsinformation

Används getinfo() för att hämta drivrutins- och servermetadata för loggning, diagnostik eller anpassning av beteende baserat på serverns kapacitet:

conn = mssql_python.connect(connection_string)

# Server information
print(f"Server name: {conn.getinfo(mssql_python.SQL_SERVER_NAME)}")
print(f"Database name: {conn.getinfo(mssql_python.SQL_DATABASE_NAME)}")

# Driver information
print(f"Driver name: {conn.getinfo(mssql_python.SQL_DRIVER_NAME)}")
print(f"Driver version: {conn.getinfo(mssql_python.SQL_DRIVER_VER)}")

Få en lista över tillgängliga informationskonstanter:

constants = mssql_python.get_info_constants()
for name, value in constants.items():
    print(f"{name}: {value}")

Sök escape-karaktären

Egenskapen searchescape returnerar karaktären som användes för att fly jokrar (% och _) i LIKE mönster. Använd den för att säkert söka efter bokstavliga jokertecken i användarinmatning:

escape = conn.searchescape

# Use in queries with wildcard characters
cursor.execute(
    f"SELECT Name FROM Production.Product WHERE Name LIKE '%{escape}%%' ESCAPE '{escape}'"
)
# Matches names containing literal '%' character

Kodning och avkodning

Konfigurera textkodning för SQL-satser och resultat. Standardinställningarna fungerar för de flesta applikationer. Byt dem endast om du ansluter till en server som använder en icke-UTF-8-kodning för char/varchar kolumner. Kodningen en server använder beror på kolumnsorteringen:

# Set encoding for outbound text
conn.setencoding(encoding='utf-8')

# Get current encoding settings
settings = conn.getencoding()
print(settings)  # {'encoding': 'utf-8', 'ctype': ...}

# Set decoding for inbound text from specific SQL types
conn.setdecoding(mssql_python.SQL_CHAR, encoding='utf-8')

# Get current decoding settings
settings = conn.getdecoding(mssql_python.SQL_CHAR)
print(settings)

Standardkodningar:

Direction SQL-typ Standardkodning
Utgående (str) SQL_WCHAR utf-16le
Inkommande SQL_CHAR utf-8
Inkommande SQL_WCHAR utf-16le
Inkommande SQL_WMETADATA utf-16le

Metodtips

  • Använd kontexthanterare (with block) för alla anslutningar i applikationskod. De garanterar städning även när undantag inträffar.
  • Använd anslutningspooling för bättre prestanda (aktiverat som standard). Se Anslutningspoolning.
  • Sätt in lämpliga timeouts för din nätverksmiljö. En 30-sekunders timeout passar de flesta molninstallationer; öka den för tvärregion- eller VPN-anslutningar.
  • Användning autocommit=False (standard) för datamodifieringsscenarier där du behöver transaktionell atomicitet.
  • Använd autocommit=True för DDL-operationer, skrivskyddade frågor och administrationsskript.
  • Dela inte kopplingar mellan trådar. Drivrutinens trådsäkerhetsnivå är 1 (trådar kan dela modulen men inte anslutningar).

Relaterat innehåll

  • Last updated on