Connection strings for mssql-python

Az mssql-python illesztőprogram támogatja a következő kapcsolati karakterlánc kulcsszavakat, amikor SQL Server, Azure SQL Database, Azure SQL Managed Instance és SQL database a Microsoft Fabric-ben csatlakozik.

Kapcsolati karakterlánc szintaxisa

A kapcsolati láncok félbasszontal elválasztott kulcs-érték párokat használnak:

keyword1=value1;keyword2=value2;...

Olyan értékek tekerése, amelyek speciális karaktereket (pontosbasszula, egyenérték jelek vagy göndör fogszabályzók) tartalmaznak a göndör fogszabályzókban:

PWD={my;complex=password}

Egy szó szerinti záró merevítő beépítéséhez két záró}} merevítőt ():

PWD={password}}with}}brace}

Alapvető kapcsolódási példák

Az alábbi példák bemutatják, hogyan lehet különböző hitelesítési módszerekkel csatlakozni. Termelési alkalmazásokhoz használd a Microsoft Entra hitelesítést, amikor csak lehet. Eltávolítja a jelszavakat a kódodból és a kapcsolati láncsorokból.

SQL Server Microsoft Entra hitelesítéssel (ajánlott)

Ez a példa , ActiveDirectoryDefaultamely több hitelesítő forrást (Azure CLI, környezeti változók, kezelt identitás) sorrendben próbál ki. Kódban nincs jelszó tárolva:

import mssql_python

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

SQL Server SQL hitelesítéssel

Az SQL hitelesítést csak helyi fejlesztéshez használd egy SQL Server instance ellen, amit te irányítasz. Az igazolványok a kapcsolati karakterlánc része vannak beágyazva, ezért tartsd őket környezeti változókban vagy fájlban.env, ne pedig forráskódban:

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

Azure SQL with Microsoft Entra authentication

Az Azure SQL Database kapcsolati karakterlánc ugyanaz, mint az SQL Server. ActiveDirectoryDefaultműködik helyi fejlesztésen, konténereken és Azure-alapú környezeteken kódváltoztatás nélkül:

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

Használj kulcsszavas argumentumokat

A kapcsolati paramétereket kulcsszavaként is átadhatod a kapcsolati karakterlánc helyett vagy annak kiegészítéseként. A kulcsszó argumentumok elkerülik a kapcsolati karakterlánc assembly kiszabaduló buktatóit. Speciális karakterekkel, mint @, ;, {, vagy } olyan jelszavak, amelyek kulcsszavaként adják át őket, nem igényelnek göndör merevítő csomagolást, ha kulcsszavaként adják át őket:

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

Hasonlítsuk össze a kapcsolati karakterlánc assembly-vel, ahol egy jelszót tartalmazó @ jelszót be kell csomagolni:

# 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")

Az illezser a kulcsszava-argumentumokat a kapcsolati karakterlánc-be egyesíti a normalizáció után. Ha egy kulcsszó argumentum megfelel a már meglévő paraméternek a kapcsolati karakterlánc-ben, akkor a kulcsszó érve elsőbbséget vesz fel, és felülírja a kapcsolati karakterlánc értékét:

# 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"

Az alábbi példa egy kapcsolati karakterlánc és kulcsszava-argumentumok kombinációját tartalmazza:

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

Kapcsolati karakterlánc kulcsszavak

Szerver és adatbázis

Határozd meg a célpont SQL Server példányt és adatbázist a kapcsolathoz.

Keyword	Aliasok	Default	Leírás
`Server`	`addr`, `address`	None	SQL Server hosztnév, IP-cím vagy nevelt példány. Nevelt példányokhoz használjuk `server\instance`. Azure SQL esetén használd `server.database.windows.net`. Port megadásához használd `server,port`.
`Database`	None	None	Adatbázis név, amihez csatlakozni lehet.

Authentication

Biztosíts jogosultságot SQL hitelesítéshez, vagy megadj egy Microsoft Entra hitelesítési módot. A jelszó nélküli opciókért lásd: Microsoft Entra hitelesítési módok.

Keyword	Aliasok	Default	Leírás
`UID`	`uid`	None	SQL hitelesítéshez használt felhasználónév.
`PWD`	`pwd`	None	SQL hitelesítéshez jelszó.
`Trusted_Connection`	`trusted_connection`	`no`	Használd a Windows integrált hitelesítést. Az engedélyezéshez állítsa erre: `yes`.
`Authentication`	`authentication`	None	Microsoft Entra hitelesítési mód. Lásd: Microsoft Entra-hitelesítés.

Titkosítás és biztonság

Minden kapcsolat alapértelmezettben használ.Encrypt=yes A legtöbb alkalmazásnál az alapértelmezett megoldás elegendő. Csak akkor használdstrict, ha az SQL Server példányod támogatja a TDS 8.0-t, és TLS 1.3-ra van szükséged. Csak önaláíró tanúsítványokkal rendelkező fejlesztő környezetekben használják TrustServerCertificate=yes .

Keyword	Aliasok	Default	Leírás
`Encrypt`	`encrypt`	`yes`	TLS-titkosítás engedélyezése. Értékek: `yes`, `no`. `strict` Használat `strict`TDS 8.0-hoz kötelező TLS 1.3-mal.
`TrustServerCertificate`	`trust_server_certificate`, `trustservercertificate`	`no`	Megbízható önaláírt szerver tanúsítványokban ellenőrzés nélkül. Csak fejlesztésre állítva `yes` .
`HostnameInCertificate`	`hostnameincertificate`	None	Várható hosztnév a szerver TLS tanúsítványában.
`ServerCertificate`	`servercertificate`	None	Út egy PEM fájlhoz, amely tartalmazza a megbízható tanúsítvány hatóságot.
`ServerSPN`	`serverspn`	None	Szerver szolgáltatás fő név a Kerberos hitelesítéshez.

Magas rendelkezésre állás és automatikus átkapcsolás

Ezek a kulcsszavak lefedik a Always On elérhetőségi csoportokat, Azure SQL célpontokat és az idle connection resiliency-t. Úgy állítva, ApplicationIntent=ReadOnly hogy az olvasást igénylő munkaterheléseket (jelentések, elemzések) másodlagos replikákra irányítsa, csökkentve az elsődleges terhelést. Állítsd MultiSubnetFailover=yes be, amikor a célpont Azure SQL Database, Azure SQL Managed Instance, SQL database Microsoft Fabric-ben, elérhetőségi csoporthallgató vagy failover klaszter instance. Ha a kiszolgáló neve egynél több IP-címre oldódik fel, az illesztőprogram egyszerre csatlakozik az összes ilyen címhez, és azt használja, amelyik elsőként válaszol. Enélkül a sofőr egyenként próbálja meg a címeket. Az a cím, amely nem válaszol, leáll, amíg le nem jár az operációs rendszer TCP csatlakozási időkitartása, ami kimerülhet a bejelentkezési időkérés, mielőtt az illesztővezető eléri a választ adó címet. Amikor a DNS egyetlen címre oldódik, az illesztőprogram egyetlen kapcsolati kísérletet indít, így a beállítás biztonságosan bekapcsolva maradhat.

MultiSubnetFailover=yes a következő korlátokat alkalmazzák. Nem használhatod más protokollon kívül, mint TCP-n, egy SQL Server példányhoz való csatlakozás, amely több mint 64 IP-címmel konfigurált, meghibásodik, és adatbázis-tükrözéssel nem lehet használni. Az adatbázis tükrözése minden támogatott SQL Server verzióban elavult. Használja inkább az Always On rendelkezésre állási csoportokat.

Keyword	Aliasok	Default	Leírás
`MultiSubnetFailover`	`multisubnetfailover`	`no`	Csatlakozz egyszerre az összes megoldott címhez, és használd az első, sikeres kapcsolatot.
`ApplicationIntent`	`applicationintent`	`ReadWrite`	Alkalmazás munkaterhelés típusának bejelentése. Használat `ReadOnly` csak olvasható útválasztáshoz másodlagos replikákhoz.
`ConnectRetryCount`	`connectretrycount`	`1`	Az automatikus újrakapcsolási kísérletek száma az alapjárati kapcsolódás ellenállósága érdekében. Ez egy driver-szintű funkció az elhagyott üres kapcsolatok esetén, nem helyettesíti az alkalmazásszintű újrapróbálkozási logikát.
`ConnectRetryInterval`	`connectretryinterval`	`10`	Másodpercek az üres kapcsolati reziliencia újrakapcsolási kísérletek között.

Teljesítmény és hálózat

Az alapértelmezések a legtöbb alkalmazásnál működnek. Növekedés PacketSize (akár 32767-re) a tömeges adatátvitelre. Konfiguráld, KeepAlive hogy a kapcsolatok átlépnek-e tűzfalakon vagy terheléselosztókon, amelyek elengedik az üres TCP üléseket.

Keyword	Aliasok	Default	Leírás
`PacketSize`	`packet size`, `packetsize`	`4096`	Hálózati csomag mérete bájtokban (512–32767).
`KeepAlive`	`keepalive`	None	TCP életben tartási intervallum másodpercekben.
`KeepAliveInterval`	`keepaliveinterval`	None	A TCP életben tartási újrapróbálkozási intervallum másodpercekben.
`IpAddressPreference`	`ipaddresspreference`	None	IP-címcsalád preferenciája: `IPv4First`, `IPv6First`, `UsePlatformDefault`.

Fenntartott kulcsszavak

Keyword	Leírás
`Driver`	Belső használatra van fenntartva. A sofőr automatikusan kezeli ezt az értéket.
`APP`	Fenntartott Mindig a sofőr állítja be.`"MSSQL-Python"`

Microsoft Entra hitelesítési módok

A Authentication kulcsszó a következő értékeket támogatja. Válaszd ki a bevetésedhez illő módot:

Érték	Leírás	Mikor érdemes használni?
`ActiveDirectoryDefault`	Felhasználás `DefaultAzureCredential` az Azure Identity SDK-ból. Több hitelesítési módszert próbál egymás után.	Helyi fejlesztés az Azure CLI, Azure PowerShell és Azure Developer CLI területén. Gyártáshoz használj egy speciális módot (`ActiveDirectoryMSI`, `ActiveDirectoryServicePrincipal`), hogy elkerüld a lassú hitelesítési láncsétát.
`ActiveDirectoryInteractive`	Böngészőalapú interaktív bejelentkezés. Windows-on a ODBC driverre küld átruházást natív módon.	Helyi fejlesztés és olyan eszközök, ahol a felhasználó jelen van a böngészőben hitelesítéshez.
`ActiveDirectoryDeviceCode`	Eszközkód áramlása fej nélküli környezetekhez. Megjelenít egy kódot, amit be kell adni -nél `https://microsoft.com/devicelogin`.	SSH ülések, Docker konténerek vagy más böngésző nélküli környezetek.
`ActiveDirectoryPassword`	Deprecated. Felhasználónév- és jelszóhitelesítés Microsoft Entra ID-vel. A következő elemek szükségesek: `UID` és `PWD`. Használja a ROPC folyamatot, ami nem kompatibilis az MFA-val.	Nem ajánlott. Használja inkább a `ActiveDirectoryMSI` vagy `ActiveDirectoryServicePrincipal` elemet.
`ActiveDirectoryMSI`	Menedzselt szolgáltatásazonosító Azure-ban hódolt alkalmazásokhoz.	Azure VM-ek, App Service vagy Azure Functions, ahol a kezelt identitás konfigurálva van. Nincs szükség hitelesítő adatokra.
`ActiveDirectoryServicePrincipal`	Szolgáltatási alaphitelesítés. Szükség `UID` van (ügyfélazonosító) és `PWD` (kliens titkos).	CI/CD pipeline-ek és háttérszolgáltatások, amelyek regisztrált alkalmazás identitást használnak.
`ActiveDirectoryIntegrated`	Windows integrált hitelesítés Microsoft Entra ID-vel (Kerberos).	Domain-joined Windows gépek vállalati környezetben Kerberos konfigurálva.

A reprodukálható Docker, devcontainer és CI környezet beállításért lásd: Container és helyi fejlesztés. Ez a cikk központosítja a Python futási idejű választását, és bemutatja, hogyan lehet digest-pinned képeket használni megosztott környezetekben.

Példa: DefaultAzureCredential

ActiveDirectoryDefaulttérképezve az Azure Identity DefaultAzureCredential láncra. Először az Azure CLI tokent próbálja ki a helyi fejlesztés során, majd a Azure-ra telepítve a menedzselt identitást:

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

Példa: Eszközkód áramlás

Használd az eszközkód folyamatát böngésző nélküli környezetekben, például SSH ülésekben vagy Docker konténerekben. A meghajtó egy URL-t és egy kódot jelenít meg, amit egy külön eszközön kell beírni:

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

Példa: Szolgáltatási alap

A szolgáltatásfő hitelesítés regisztrált alkalmazásazonosítót használ, kliensazonosítóval és titkossal. Ezt a megközelítést alkalmazzuk CI/CD pipeline-ek és háttérszolgáltatások esetén, amelyek felhasználói interakció nélkül futnak:

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

Az alkalmazás regisztrálásához és adatbázis-hozzáférés megadásához lásd: Microsoft Entra szolgáltatáselvek Azure SQL-szel. A teljes beállításért lásd mssql-pythona Szolgáltatásfő hitelesítést.

Kapcsolati időkorlát

Állítsd be a hitelesítési időkorlátot a timeout paraméterrel. Használj időkorlátot, hogy megakadályozd, hogy az alkalmazásod határozatlan ideig lefagyjon, amikor a szerver elérhetetlen:

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

Connection.timeout egy különálló beállítás, amely minden állítást korlátoz, nem pedig a hitelesítési kísérletet. További információért lásd: Kapcsolat időkorlát.

conn.timeout = 60

Ha a célpont Azure SQL Database szerver nélküli rendszerrel, automatikus szünetet engedélyezve, használj legalább 60. Az automatikus felfüggesztett adatbázis folytatódik az első csatlakozási próbálkozásnál, és egy rövidebb időkorlát lejár, mielőtt a folytatás befejeződik. A próbálkozás 40613 hibával is megbukhat, amíg az adatbázis folytatódik, ezért az alkalmazásnak újra kell próbálkoznia. További információkért lásd: Automatikus szüneteltetés és automatikus folytatás.

Automatikus feladatátvételi mód

Alapértelmezés autocommit szerint False, ami explicit commit() hívásokat igényel. Engedélyezze az automatikus köteleződést DDL utasításokhoz vagy csak olvasható lekérdezésekhez, amelyek nem igényelnek tranzakcióvezérlést:

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

# Or after connection
conn.setautocommit(True)

Hitelesítő adatok objektumai

Ahelyett, hogy a kapcsolati karakterlánc-ben hitelesítési módot neveznél meg, az illesztőprogramnak adhatsz egy credential objektumot a token_provider paraméterrel. Ez a paraméter bármely objektumot elfogad, amelyhez medudus get_token(scope) tartozik, beleértve az összes jogosultságot a azure-identity csomagban:

import mssql_python
from azure.identity import DefaultAzureCredential

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Encrypt=yes",
    token_provider=DefaultAzureCredential(),
)

Ne kombináld token_provider a Authentication kulcsszóval ugyanabban a kapcsolatban. A sofőr felemel InterfaceError , ha mindketten jelen vannak. További információ: Microsoft Entra-hitelesítés.

Kapcsolati attribútumok

Az ODBC kapcsolat attribútumokat a kapcsolat létrehozása előtt beállítsuk a következők használatával 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,
    }
)

Programmatic kapcsolati karakterlánc építés

A kapcsolati karakterlánc befecskendezésének megakadályozása érdekében ne használj string conconcatationt vagy f-stringeket felhasználói bemenettel. Használj inkább kulcsszava-argumentumokat vagy környezeti változókat. További építési mintákért, beleértve a JSON/YAML konfigurációs fájlokat, Azure Key Vault-t és egy builder osztályt, lásd: Build connection strings programmatically.

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

Kapcsolati lánc ellenőrzése

Az illesztőprogram validálja a kapcsolódási láncokat és a jeleket ismeretlen vagy rosszul írt kulcsszavak esetén ConnectionStringParseError :

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

Kulcsszavak más meghajtókból

Az ellenőrzés még azelőtt fut el, hogy az illesztőprogram kapcsolatot nyitna, így egy kulcsszó, amit más SQL Server illegaszvezetők elfogadnak, itt azonnal meghibásodik. Az ADO.NET, ODBC vagy pyodbc csatornákról portolt kapcsolati láncok általában ezeket a helyettesítéseket igénylik:

Kulcsszó más meghajtókban	MSSQL-python megfelelője
`Data Source`	`Server`, vagy az és `addraddress` az álnevek
`Initial Catalog`	`Database`
`User ID`	`UID`
`Password`	`PWD`
`Connection Timeout`, `Connect Timeout`, `Timeout`, `Login Timeout`	A `timeout` paraméter `connect()`. További információért lásd: Kapcsolat időkorlát.
`Application Name`	Nincs. A meghajtó beállítja ezt az értéket, és ismeretlen kulcsszóként jelent jelentést `Application Name` .
`APP`	Nincs. Az illesztőprogram ezt az értéket állítja be, és a `APP` jelentést fenntartott kulcsszóként jelent. További információért lásd: Fenntartott kulcsszavak.
`Pooling`, `Max Pool Size`	Nincs. Konfiguráld a poolingot a kódban. További információkért lásd a Kapcsolatcsoportosítás című részt.
`Workstation ID`, `WSID`	Nincs. Távolítsd el a kulcsszót a kapcsolati karakterlánc-ből.
`MultipleActiveResultSets`, `MARS_Connection`	Nincs. Távolítsd el a kulcsszót. A lekérdezések egyidejű futtatásához külön kapcsolatokat használjunk. További információért lásd: Több kurzor.

És Driveresetén APP az illesztőprogram fenntartott kulcsszó-hibat jelent, nem ismeretlen kulcsszó hibát, mert mindkét értéket ő irányítja.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-09-04