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.

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 strictTDS 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 a Always On elérhetőségi csoport telepítéseire vonatkoznak. Ú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 be, MultiSubnetFailover=yes mikor terjed le a rendelkezésre állási csoportod több alhálózaton.

Keyword Aliasok Default Leírás
MultiSubnetFailover multisubnetfailover no Engedélyezze a többalhálózati failovert a Always On elérhetőségi csoportok számára.
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 kapcsolat időtúllépését a timeout paraméter segítségével. Használj időkorlátot, hogy megakadályozd, hogy az alkalmazásod határozatlan ideig lefagyjon, amikor a szerver elérhetetlen:

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

A meglévő kapcsolat időkorlátját is módosíthatod:

conn.timeout = 60

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)

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'

Kapcsolódó tartalom

  • Last updated on