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 platí pro nasazení skupin Always On pro dostupnost. 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. Nastavit MultiSubnetFailover=yes , kdy vaše skupina dostupnosti zasahuje do více podsítí.

Keyword Přezdívky Výchozí Popis
MultiSubnetFailover multisubnetfailover no Povolte přepnutí v rámci více podsítí pro skupiny dostupnosti Always On.
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 připojení 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 connection timeout
conn = mssql_python.connect(connection_string, timeout=30)

Můžete také změnit časový limit na existujícím připojení:

conn.timeout = 60

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)

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'

Související obsah

  • Last updated on