Anslutningssträngar för mssql-python

mssql-python-drivrutinen stöder följande reťazec pripojenia-nyckelord vid anslutning till SQL Server, Azure SQL Database, Azure SQL Managed Instance och SQL database i Microsoft Fabric.

Syntax för anslutningssträng

Anslutningssträngar använder semikolonseparerade nyckel-värdepar:

keyword1=value1;keyword2=value2;...

Wrap-värden som innehåller specialtecken (semikolon, likvärdiga tecken eller lockiga klammer) i lockiga klamrar:

PWD={my;complex=password}

För att inkludera en bokstavlig slutande klamr i ett värde, använd två slutande klamrar (}}):

PWD={password}}with}}brace}

Grundläggande kopplingsexempel

Följande exempel visar hur man ansluter med olika autentiseringsmetoder. För produktionsapplikationer, använd Microsoft Entra-autentisering när det är möjligt. Det eliminerar lösenord från din kod och anslutningssträngar.

Detta exempel använder ActiveDirectoryDefault, som försöker flera legitimationskällor (Azure CLI, miljövariabler, hanterad identitet) i ordning. Inget lösenord lagras i koden:

import mssql_python

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

SQL Server med SQL-autentisering

Använd SQL-autentisering endast för lokal utveckling mot en SQL Server-instans som du kontrollerar. Inloggningsuppgifter är inbäddade i reťazec pripojenia, så håll dem i miljövariabler eller en .env fil istället för i källkoden:

conn = mssql_python.connect(
    "Server=<server>;"
    "Database=<database>;"
    "UID=<login>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Azure SQL med Microsoft Entra-autentisering

reťazec pripojenia för Azure SQL Database är densamma som för SQL Server. ActiveDirectoryDefaultfungerar över lokal utveckling, containrar och Azure-hostade miljöer utan kodändringar:

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

Använd nyckelordsargument

Du kan skicka anslutningsparametrar som nyckelordsargument istället för eller som tillägg till en reťazec pripojenia. Nyckelordsargument undviker de fallgropar som reťazec pripojenia-assembly innebär. Lösenord med specialtecken som @, ;, , {behöver } inte curly-brace wrapping när de skickas som nyckelordsargument:

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Jämför med reťazec pripojenia assembly, där ett lösenord som innehåller @ måste wrappas:

# Connection string requires escaping
conn = mssql_python.connect("Server=srv;UID=user;PWD={p@ss;word};")

# Keyword arguments - no escaping needed
conn = mssql_python.connect(server="srv", uid="user", pwd="p@ss;word")

Drivrutinen slår ihop nyckelordsargument i reťazec pripojenia efter normalisering. Om ett nyckelordsargument matchar en parameter som redan finns i reťazec pripojenia, får nyckelordsargumentet företräde och åsidosätter värdet på reťazec pripojenia:

# The keyword argument database="production" overrides Database=dev in the connection string
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Encrypt=yes;",
    database="production",
    authentication="ActiveDirectoryDefault"
)
# Connects to "production", not "dev"

Följande exempel kombinerar en reťazec pripojenia med nyckelordsargument:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Nyckelord för anslutningssträng

Server och databas

Ange målinstansen och databasen för SQL Server för anslutningen.

Nyckelord Aliasnamn Standardinställning Beskrivning
Server addr, address None SQL Server-värdnamn, IP-adress eller namngiven instans. För namngivna instanser, använd server\instance. För Azure SQL, använd server.database.windows.net. För att specificera en port, använd server,port.
Database None None Databasens namn att ansluta till.

Authentication

Ange inloggningsuppgifter för SQL-autentisering eller ange ett Microsoft Entra-autentiseringsläge. För lösenordslösa alternativ, se Microsoft Entra-autentiseringslägen.

Nyckelord Aliasnamn Standardinställning Beskrivning
UID uid None Användarnamn för SQL-autentisering.
PWD pwd None Lösenord för SQL-autentisering.
Trusted_Connection trusted_connection no Använd Windows integrerad autentisering. Ställ in på yes för att aktivera.
Authentication authentication None Microsoft Entra-autentiseringsläge. Se Microsoft Entra-autentisering.

Kryptering och säkerhet

Alla anslutningar används Encrypt=yes som standard. För de flesta tillämpningar är standarden tillräcklig. Använd strict endast när din SQL Server-instans stödjer TDS 8.0 och du behöver TLS 1.3. Använd TrustServerCertificate=yes endast i utvecklingsmiljöer med självsignerade certifikat.

Nyckelord Aliasnamn Standardinställning Beskrivning
Encrypt encrypt yes Aktivera TLS-kryptering. Värden: yes, no, strict. Använd strict för TDS 8.0 med obligatorisk TLS 1.3.
TrustServerCertificate trust_server_certificate, trustservercertificate no Lita på självsignerade servercertifikat utan validering. Ställt in på yes endast för utveckling.
HostnameInCertificate hostnameincertificate None Förväntat värdnamn i serverns TLS-certifikat.
ServerCertificate servercertificate None Väg till en PEM-fil som innehåller den betrodda certifikatutgivaren.
ServerSPN serverspn None Servertjänstprincipnamn för Kerberos-autentisering.

Hög tillgänglighet och redundans

Dessa nyckelord gäller för Always On-tillgänglighetsgruppdistributioner. Ställ ApplicationIntent=ReadOnly in för att routa lästunga arbetsbelastningar (rapporter, analys) till sekundära repliker, vilket minskar belastningen på primären. Ställ in MultiSubnetFailover=yes när din tillgänglighetsgrupp sträcker sig över flera subnät.

Nyckelord Aliasnamn Standardinställning Beskrivning
MultiSubnetFailover multisubnetfailover no Aktivera multi-subnet failover för Always On-tillgänglighetsgrupper.
ApplicationIntent applicationintent ReadWrite Deklarera applikationsarbetsbelastningstyp. Används ReadOnly för skrivskyddad routning till sekundära repliker.
ConnectRetryCount connectretrycount 1 Antal försök till automatisk återanslutning för viloaktiv anslutningsresiliens. Detta är en drivrutinsnivå för tappade inaktiva anslutningar, inte en ersättning för applikationsnivå-retry-logik.
ConnectRetryInterval connectretryinterval 10 Sekunder mellan försök till återanslutning för inaktiv anslutning.

Prestanda och nätverk

Standardinställningarna fungerar för de flesta applikationer. Öka PacketSize (upp till 32767) för bulkdataöverföringar. Konfigurera KeepAlive om anslutningar korsar brandväggar eller lastbalanserare som bryter lediga TCP-sessioner.

Nyckelord Aliasnamn Standardinställning Beskrivning
PacketSize packet size, packetsize 4096 Nätverkspaketstorlek i byte (512–32767).
KeepAlive keepalive None TCP keep-alive-intervall i sekunder.
KeepAliveInterval keepaliveinterval None TCP:s keep-alive-försöksintervall på sekunder.
IpAddressPreference ipaddresspreference None IP-adressfamiljepreferens: IPv4First, IPv6First, UsePlatformDefault.

Reserverade nyckelord

Nyckelord Beskrivning
Driver Reserverad för internt bruk. Drivrutinen hanterar detta värde automatiskt.
APP Reserverat. Alltid inställt på "MSSQL-Python" föraren.

Microsoft Entra-autentiseringslägen

Nyckelordet Authentication stöder följande värden. Välj det läge som matchar din utplacering:

Värde Beskrivning När det bör användas
ActiveDirectoryDefault Använder DefaultAzureCredential från Azure Identity SDK. Försöker flera autentiseringsmetoder i följd. Lokal utveckling över Azure CLI, Azure PowerShell och Azure Developer CLI. För produktion, använd ett specifikt läge (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal) för att undvika den långsamma kedjevandringen av inloggningsuppgifter.
ActiveDirectoryInteractive Webbläsarbaserad interaktiv inloggning. På Windows delegerar de till ODBC-drivrutinen nativt. Lokal utveckling och verktyg där en användare finns för att autentisera i en webbläsare.
ActiveDirectoryDeviceCode Enhetskodflöde för headless-miljöer. Visar en kod att ange vid https://microsoft.com/devicelogin. SSH-sessioner, Docker-containrar eller andra miljöer utan webbläsare.
ActiveDirectoryPassword Deprecated. Användarnamns- och lösenordsautentisering med Microsoft Entra ID. Kräver UID och PWD. Använder ROPC-flödet, som är inkompatibelt med MFA. Rekommenderas inte. Använd ActiveDirectoryMSI eller ActiveDirectoryServicePrincipal i stället.
ActiveDirectoryMSI Managed Service Identity för Azure-hostade applikationer. Azure VMs, App Service eller Azure Functions där hanterad identitet konfigureras. Inga autentiseringsuppgifter behövs.
ActiveDirectoryServicePrincipal Autentisering av tjänsteprincipen. Kräver UID (klient-ID) och PWD (klienthemlighet). CI/CD-pipelines och bakgrundstjänster som använder en registrerad applikationsidentitet.
ActiveDirectoryIntegrated Windows integrerad autentisering med Microsoft Entra ID (Kerberos). Domänanslutna Windows-maskiner i företagsmiljöer med konfigurerat Kerberos.

För reproducerbar Docker, devcontainer och CI-miljöuppsättning, se Container och lokal utveckling. Den artikeln centraliserar valet av Python-runtime och visar hur man använder digest-fastnålade bilder i delade miljöer.

Exempel: DefaultAzureCredential

ActiveDirectoryDefaultavbildar till Azure Identity-kedjanDefaultAzureCredential. Den testar Azure CLI-token först under lokal utveckling, sedan hanterad identitet när den distribueras till Azure:

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

Exempel: Enhetskodflöde

Använd enhetskodflöde när du körs i miljöer utan webbläsare, såsom SSH-sessioner eller Docker-containrar. Drivrutinen visar en URL och en kod att mata in på en separat enhet:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Follow the prompt to authenticate at https://microsoft.com/devicelogin

Exempel: Service principal

Autentisering av tjänstehuvudpersonen använder en registrerad applikationsidentitet med ett klient-ID och en hemlig identitet. Använd denna metod för CI/CD-pipelines och bakgrundstjänster som körs utan användarinteraktion:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes;"
)

För att registrera applikationen och ge den databasåtkomst, se Microsoft Entra service principals with Azure SQL. För fullständig uppsättning i mssql-python, se Service Principal authentication.

Tidsgräns för anslutning

Ställ in anslutningstimeout med parametern timeout . Använd en timeout för att förhindra att din applikation hänger på obestämd tid när servern är otillgänglig:

# 30-second connection timeout
conn = mssql_python.connect(connection_string, timeout=30)

Du kan också ändra timeouten på en befintlig anslutning:

conn.timeout = 60

Autocommit-läge

Som standard autocommit är False, vilket kräver explicita commit() anrop. Aktivera autocommit för DDL-satser eller skrivskyddade frågor som inte kräver transaktionskontroll:

# Via parameter
conn = mssql_python.connect(connection_string, autocommit=True)

# Or after connection
conn.setautocommit(True)

Anslutningsattribut

Sätt ODBC-anslutningsattribut innan anslutningen upprättas genom att använda:attrs_before

import mssql_python

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

Programmatisk reťazec pripojenia-byggnad

För att förhindra reťazec pripojenia injection, använd inte string-sammanfogning eller f-strängar med användarinmatning. Använd istället nyckelordsargument eller miljövariabler. För fler konstruktionsmönster inklusive JSON/YAML-konfigurationsfiler, Azure Key Vault och en builder-klass, se Bygg anslutningssträngar programmatiskt.

import os

conn = mssql_python.connect(
    server=os.environ["DB_SERVER"],
    database=os.environ["DB_NAME"],
    authentication=os.environ.get("DB_AUTH", "ActiveDirectoryDefault"),
    encrypt="yes"
)

Validering av anslutningssträngar

Drivrutinen validerar anslutningssträngar och höjer ConnectionStringParseError för okända eller felstavade nyckelord:

try:
    conn = mssql_python.connect("Servr=localhost;")  # Typo
except mssql_python.ConnectionStringParseError as e:
    print(f"Invalid connection string: {e}")
    # Output: Unknown keyword 'Servr'

Relaterat innehåll

  • Last updated on