Connection strings for mssql-python

Ovladač mssql-python podporuje následující klíčová slova připojovací řetězec při připojování k SQL Server, Azure SQL Database, Azure SQL Managed Instance a SQL databázi v Microsoft Fabric.

Syntaxe připojovacího řetězce

Spojovací řetězce používají páry klíč-hodnota oddělené středníkem:

keyword1=value1;keyword2=value2;...

Hodnoty wrapu, které obsahují speciální znaky (středníky, rovnátka nebo kudrnaté závorky) v kudrnatých závorkách:

PWD={my;complex=password}

Pro zahrnutí doslovné uzavírající závorky v hodnotě použijte dvě uzavírající závorky (}}):

PWD={password}}with}}brace}

Základní příklady spojení

Následující příklady ukazují, jak se připojit pomocí různých autentizačních metod. Pro produkční aplikace používejte Microsoft Entra autentizaci, kdykoli je to možné. Odstraní hesla z vašeho kódu a spojovacích řetězců.

Tento příklad používá ActiveDirectoryDefault, který zkouší více zdrojů přihlašovacích údajů (Azure CLI, proměnné prostředí, spravovaná identita) v pořadí. V kódu není uloženo žádné heslo:

import mssql_python

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

SQL Server s ověřením SQL

SQL autentizaci používejte pouze pro lokální vývoj proti instanci SQL Server, kterou ovládáte. Přihlašovací údaje jsou vloženy do připojovací řetězec, proto je uchovávejte v proměnných prostředí nebo v souboru.env, nikoli ve zdrojovém kódu:

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

Azure SQL with Microsoft Entra authentication

připojovací řetězec pro Azure SQL Database je stejný jako v SQL Server. ActiveDirectoryDefaultfunguje napříč lokálním vývojem, kontejnery a prostředími hostovanými v Azure bez změn kódu:

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

Používejte argumenty s klíčovými slovy

Parametry spojení můžete předávat jako argumenty klíčových slov místo nebo navíc k připojovací řetězec. Argumenty klíčových slov se vyhýbají úskalím sestavování připojovací řetězec. Hesla se speciálními znaky jako @, ;, {, nebo } nepotřebují zavírání závorkami, když jsou předána jako argumenty klíčových slov:

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

Porovnejte s assemblerem připojovací řetězec, kde musí být heslo obsahující @ zabaleno:

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

Ovladač po normalizaci sloučí argumenty klíčových slov do připojovací řetězec. Pokud argument klíčového slova odpovídá parametru již v připojovací řetězec, má přednost argument klíčového slova a přepisuje hodnotu připojovací řetězec:

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

Následující příklad kombinuje připojovací řetězec s argumenty klíčových slov:

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

Klíčová slova připojovacího řetězce

Server a databáze

Specifikujte cílovou instanci SQL Server a databázi pro připojení.

Keyword Přezdívky Výchozí Popis
Server addr, address Žádný SQL Server název hostitele, IP adresa nebo pojmenovaná instance. Pro pojmenované instance použijte server\instance. For Azure SQL, use server.database.windows.net. Pro určení portu použijte server,port.
Database Žádný Žádný Název databáze, ke kterému se připojit.

Autentizace

Zadejte přihlašovací údaje pro SQL autentizaci nebo zadejte režim autentizace Microsoft Entra. Pro možnosti bez hesla viz Microsoft Entra autentizační režimy.

Keyword Přezdívky Výchozí Popis
UID uid Žádný Uživatelské jméno pro SQL autentizaci.
PWD pwd Žádný Heslo pro SQL autentizaci.
Trusted_Connection trusted_connection no Používejte Windows integrovanou autentizaci. Nastavte na yes, chcete-li povolit.
Authentication authentication Žádný Autentizační režim Microsoft Entra. Viz ověřování Microsoft Entra.

Šifrování a zabezpečení

Všechny připojení se používají Encrypt=yes ve výchozím nastavení. Pro většinu aplikací je výchozí nastavení dostačující. Používejte strict jen tehdy, když vaše instance SQL Server podporuje TDS 8.0 a potřebujete TLS 1.3. Používejte TrustServerCertificate=yes pouze ve vývojových prostředích s vlastními certifikáty.

Keyword Přezdívky Výchozí Popis
Encrypt encrypt yes Povolte šifrování TLS. Hodnoty: yes, no, strict. Použití strict pro TDS 8.0 s povinným TLS 1.3.
TrustServerCertificate trust_server_certificate, trustservercertificate no Důvěřujte samopodepsaným serverovým certifikátům bez ověření. Nastaveno pouze yes pro vývoj.
HostnameInCertificate hostnameincertificate Žádný Očekávané jméno hostitele v TLS certifikátu serveru.
ServerCertificate servercertificate Žádný Cesta k souboru PEM obsahujícímu důvěryhodnou certifikační autoritu.
ServerSPN serverspn Žádný Server Service Principal Name for Kerberos authentication.

Vysoká dostupnost a převzetí služeb při selhání

Tato klíčová slova zahrnují skupiny dostupnosti Always On, cíle Azure SQL a odolnost nečinného připojení. Nastavte ApplicationIntent=ReadOnly směrování čtení náročných zátěží (reporty, analytika) na sekundární repliky, čímž se snižuje zátěž na primární repliku. Nastavte MultiSubnetFailover=yes cíl, kdy je cílem Azure SQL Database, Azure SQL Managed Instance, SQL databáze v Microsoft Fabric, naslouchač skupiny dostupnosti nebo instance failover clusteru. Když se název serveru přeloží na více než jednu IP adresu, ovladač se připojí ke všem těmto adresám současně a použije tu, která zareaguje jako první. Bez něj řidič zkouší adresy jednu po druhé. Adresa, která neodpoví, se zastaví, dokud nevyprší časový limit TCP připojení operačního systému, což může vyčerpat přihlašovací časový limit dříve, než ovladač dorazí na adresu, která odpoví. Když DNS přejde na jednu adresu, ovladač provede jeden pokus o připojení, takže nastavení je bezpečné nechat zapnuté.

MultiSubnetFailover=yes má následující limity. Nemůžete ho použít přes jiný protokol než TCP, připojení k instanci SQL Server s více než 64 IP adresami selže a nelze ho použít s databázovým zrcadlením. Zrcadlení databází je ve všech podporovaných verzích SQL Server zastaralé. Místo toho používejte skupiny dostupnosti AlwaysOn.

Keyword Přezdívky Výchozí Popis
MultiSubnetFailover multisubnetfailover no Připojte se ke všem vyřešeným adresám současně a použijte první úspěšné spojení.
ApplicationIntent applicationintent ReadWrite Deklarujte typ zátěže aplikace. Použití ReadOnly pro směrování pouze pro čtení na sekundární repliky.
ConnectRetryCount connectretrycount 1 Počet pokusů o automatické opětovné připojení pro odolnost nečinného spojení. Toto je funkce na úrovni ovladače pro přerušení nečinných spojení, nikoli náhrada za logiku opakovaných pokusů na úrovni aplikace.
ConnectRetryInterval connectretryinterval 10 Sekundy mezi pokusy o obnovení odolnosti nečinného připojení.

Výkon a síť

Výchozí nastavení funguje pro většinu aplikací. Zvýšení PacketSize (až na 32767) pro hromadné přenosy dat. Konfigurujte KeepAlive , zda spojení překračují firewally nebo load balancery, které přerušují nečinné TCP relace.

Keyword Přezdívky Výchozí Popis
PacketSize packet size, packetsize 4096 Velikost síťového paketu v bajtech (512–32767).
KeepAlive keepalive Žádný TCP udržuje interval naživu během několika sekund.
KeepAliveInterval keepaliveinterval Žádný TCP udržuje interval opakování během několika sekund.
IpAddressPreference ipaddresspreference Žádný Preference IPv4Firstrodiny IP adres: , IPv6First, . UsePlatformDefault

Vyhrazená klíčová slova

Keyword Popis
Driver Vyhrazeno pro interní použití. Řidič tuto hodnotu spravuje automaticky.
APP Rezervovaný. Vždy nastavené "MSSQL-Python" řidičem.

Autentizační režimy Microsoft Entra

Klíčové Authentication slovo podporuje následující hodnoty. Vyberte režim, který odpovídá vašemu nasazení:

Hodnota Popis Kdy ho použít
ActiveDirectoryDefault Použití DefaultAzureCredential z Azure Identity SDK. Zkouší více autentizačních metod za sebou. Lokální vývoj napříč Azure CLI, Azure PowerShell a Azure Developer CLI. Pro produkci použijte specifický režim (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal), abyste se vyhnuli pomalému řetězovému postupu s přihlašováním.
ActiveDirectoryInteractive Interaktivní přihlášení v prohlížeči. Na Windows se ovladač ODBC řídí nativně. Lokální vývoj a nástroje, kde je přítomen uživatel pro autentizaci v prohlížeči.
ActiveDirectoryDeviceCode Tok kódu zařízení pro prostředí bez hlavy. Zobrazuje kód pro zadání na .https://microsoft.com/devicelogin SSH relace, Docker kontejnery nebo jiná prostředí bez prohlížeče.
ActiveDirectoryPassword Deprecated. Ověření uživatelského jména a hesla pomocí Microsoft Entra ID. Vyžaduje UID a PWD. Používá ROPC flow, který není kompatibilní s MFA. Nedoporučuje se. Použijte ActiveDirectoryMSI nebo ActiveDirectoryServicePrincipal místo toho.
ActiveDirectoryMSI Managed Service Identity pro aplikace hostované v Azure. Azure VMs, App Service nebo Azure Functions, kde je řízená identita konfigurována. Nejsou potřeba žádné přihlašovací údaje.
ActiveDirectoryServicePrincipal Autentizace principa služby. Vyžaduje UID (client ID) a PWD (client secret). CI/CD pipeline a služby na pozadí, které používají registrovanou identitu aplikace.
ActiveDirectoryIntegrated Windows Integrated authentication with Microsoft Entra ID (Kerberos). Doménově připojené Windows stroje v podnikových prostředích s konfigurovaným Kerberosem.

Pro reprodukovatelné nastavení prostředí Docker, devcontainer a CI viz Container a lokální vývoj. Tento článek centralizuje výběr v běhu v Python a ukazuje, jak používat obrázky připnuté digestem ve sdílených prostředích.

Příklad: DefaultAzureCredential

ActiveDirectoryDefaultmapuje na řetězec Azure IdentityDefaultAzureCredential. Nejprve zkouší token Azure CLI během lokálního vývoje, poté spravovanou identitu při nasazení do Azure:

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

Příklad: Tok kódu zařízení

Používejte flow kódu zařízení při provozu v prostředích bez prohlížeče, jako jsou SSH relace nebo Docker kontejnery. Ovladač zobrazí URL a kód pro zadání na samostatném zařízení:

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říklad: Hlavní představitel služby

Autentizace principu služby používá registrovanou identitu aplikace s ID klienta a tajemstvím. Použijte tento přístup pro CI/CD pipeline a služby na pozadí, které běží bez interakce uživatele:

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

Pro registraci aplikace a udělení přístupu do databáze viz Microsoft Entra service principals with Azure SQL. Pro úplné nastavení v mssql-python, viz Servisní principální autentizace.

Časový limit připojení vypršel

Nastavte časový limit autentizace pomocí parametru timeout . Použijte časový limit, abyste zabránili tomu, aby vaše aplikace zasekla na neurčito, když je server nedostupný:

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

Connection.timeout je samostatné nastavení, které omezuje každý příkaz, nikoli samotný pokus o autentizaci. Pro více informací viz Časový limit připojení.

conn.timeout = 60

Pokud je cílem serverless Azure SQL Database s povoleným automatickým pauzováním, použijte alespoň 60. Automaticky pozastavená databáze pokračuje při prvním pokusu o připojení a kratší časový limit vyprší před dokončením obnovení. Pokus může také selhat s chybou 40613, zatímco databáze pokračuje, takže aplikace musí zkusit znovu. Více informací naleznete v části Automatické pozastavení a automatické obnovení.

Režim automatického dokončování

Ve výchozím nastavení autocommit je False, což vyžaduje explicitní commit() volání. Povolte autocommit pro DDL příkazy nebo dotazy pouze pro čtení, které nepotřebují řízení transakcí:

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

# Or after connection
conn.setautocommit(True)

Objekty přihlašovacích údajů

Místo pojmenování autentizačního režimu v připojovací řetězec můžete ovladači předat přihlašovací objekt s parametremtoken_provider. Tento parametr přijímá jakýkoli objekt s metodou get_token(scope) , včetně všech přihlašovacích údajů v balíčku azure-identity :

import mssql_python
from azure.identity import DefaultAzureCredential

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

Nekombinujte token_provider to s Authentication klíčovým slovem ve stejném spojení. Řidič zvedá ruku InterfaceError , když jsou přítomni oba dva. Další informace naleznete v tématu ověřování Microsoft Entra.

Atributy připojení

Nastavte atributy spojení ODBC před navázáním spojení pomocí 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,
    }
)

Programové budování připojovací řetězec

Aby se zabránilo vstřikování připojovací řetězec, nepoužívejte konkatenaci řetězců ani f-stringy s uživatelským vstupem. Používejte místo toho argumenty klíčových slov nebo proměnné prostředí. Pro více konstrukčních vzorů včetně konfiguračních souborů JSON/YAML, Azure Key Vault a třídy builder viz Build connection strings programmaticky.

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

Validace spojovacích řetězců

Ovladač ověřuje spojovací řetězce a zvyšuje počet ConnectionStringParseError klíčových slov pro neznámá nebo špatně napsaná slova:

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

Klíčová slova z jiných ovladačů

Validace probíhá před tím, než ovladač otevře připojení, takže klíčové slovo, které ostatní ovladače SQL Server akceptují, zde okamžitě selže. Spojovací řetězce portované z ADO.NET, ODBC nebo pyodbc obvykle vyžadují tyto substituce:

Klíčové slovo v jiných ovladačích MSSQL-Python ekvivalent
Data Source Server, nebo jeho addr a address aliasy
Initial Catalog Database
User ID UID
Password PWD
Connection Timeout, Connect Timeout, , TimeoutLogin Timeout Parametr timeoutconnect(). Pro více informací viz Časový limit připojení.
Application Name Žádné. Ovladač nastaví tuto hodnotu a hlásí Application Name jako neznámé klíčové slovo.
APP Žádné. Ovladač nastaví tuto hodnotu a hlásí APP jako rezervované klíčové slovo. Pro více informací viz Rezervovaná klíčová slova.
Pooling, Max Pool Size Žádné. Nastavte pooling v kódu. Pro více informací viz Sdružování připojení.
Workstation ID, WSID Žádné. Odstraňte klíčové slovo z připojovací řetězec.
MultipleActiveResultSets, MARS_Connection Žádné. Odstraňte klíčové slovo. Pro současné spouštění dotazů používejte samostatná připojení. Pro více informací viz Více kurzorů.

Pro APP a Driver, ovladač hlásí chybu rezervovaného klíčového slova místo chyby neznámého klíčového slova, protože řídí obě hodnoty.

Související obsah

  • Last updated on