Verbindingsstrings voor mssql-python

De mssql-python-driver ondersteunt de volgende verbindingsreeks-sleutelwoorden bij verbinding met SQL Server, Azure SQL Database, Azure SQL Managed Instance en SQL database in Microsoft Fabric.

Syntaxis van verbindingsreeks

Verbindingsstrings gebruiken met puntkomma-gescheiden sleutel-waarde paren:

keyword1=value1;keyword2=value2;...

Wikkelwaarden die speciale tekens bevatten (puntkomma's, gelijke tekens of krulbare haakjes) in krulbare hakjes:

PWD={my;complex=password}

Om een letterlijke sluitende scène in een waarde op te nemen, gebruik je twee sluitingscrace (}}):

PWD={password}}with}}brace}

Basisvoorbeelden van verbindingen

De volgende voorbeelden laten zien hoe je verbinding kunt maken met verschillende authenticatiemethoden. Voor productieapplicaties gebruik Microsoft Entra-authenticatie waar mogelijk. Het verwijdert wachtwoorden uit je code en verbindingsstrings.

SQL Server met Microsoft Entra-authenticatie (aanbevolen)

Dit voorbeeld gebruikt ActiveDirectoryDefault, dat meerdere credentialbronnen probeert (Azure CLI, omgevingsvariabelen, beheerde identiteit) in volgorde. Er wordt geen wachtwoord opgeslagen in de code:

import mssql_python

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

SQL Server met SQL-authenticatie

Gebruik SQL-authenticatie alleen voor lokale ontwikkeling tegen een SQL Server-instantie die jij beheert. Inloggegevens zijn ingebed in de verbindingsreeks, dus bewaar ze in omgevingsvariabelen of een .env bestand in plaats van in de broncode:

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

Azure SQL met Microsoft Entra authentication

De verbindingsreeks voor Azure SQL Database is hetzelfde als voor SQL Server. ActiveDirectoryDefaultwerkt over lokale ontwikkeling, containers en door Azure gehoste omgevingen zonder codewijzigingen:

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

Gebruik trefwoordargumenten

Je kunt verbindingsparameters als trefwoordargumenten doorgeven in plaats van of als aanvulling op een verbindingsreeks. Trefwoordargumenten vermijden de ontsnappingsvalkuilen van verbindingsreeks assembly. Wachtwoorden met speciale tekens zoals @, ;, , {of } hoeven geen curly-brace wrapping te gebruiken wanneer ze als trefwoordargumenten worden doorgegeven:

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

Vergelijk met een verbindingsreeks assembly, waarbij een wachtwoord dat bevat @ moet worden gewrapped:

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

De driver voegt sleutelwoordargumenten samen in de verbindingsreeks na normalisatie. Als een trefwoordargument overeenkomt met een parameter die al in de verbindingsreeks zit, krijgt het trefwoordargument voorrang en overschrijft het de waarde van de verbindingsreeks:

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

Het volgende voorbeeld combineert een verbindingsreeks met trefwoordargumenten:

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

Trefwoorden voor verbindingsreeks

Server en database

Specificeer de doel-SQL Server-instantie en database voor de verbinding.

Authentication

Geef inloggegevens voor SQL-authenticatie of specificeer een Microsoft Entra-authenticatiemodus. Voor opties zonder wachtwoord, zie Microsoft Entra authenticatiemodi.

Versleuteling en beveiliging

Alle verbindingen worden standaard gebruikt Encrypt=yes . Voor de meeste toepassingen is de standaard voldoende. Gebruik strict alleen wanneer je SQL Server-instantie TDS 8.0 ondersteunt en je TLS 1.3 nodig hebt. TrustServerCertificate=yes Gebruik alleen in ontwikkelomgevingen met zelfondertekende certificaten.

Hoge beschikbaarheid en failover

Deze trefwoorden zijn van toepassing op Always On-beschikbaarheidsgroepen. Stel in ApplicationIntent=ReadOnly dat leesintensieve workloads (rapporten, analytics) naar secundaire replica's worden geleid, waardoor de belasting op de primaire wordt verminderd. Stel MultiSubnetFailover=yes in wanneer je beschikbaarheidsgroep meerdere subnetten beslaat.

Optreden en netwerk

De standaardinstellingen werken voor de meeste applicaties. Verhoog PacketSize (tot 32767) voor bulkgegevensoverdrachten. Configureer KeepAlive of verbindingen firewalls of load balancers overschrijden die de inactieve TCP-sessies laten vallen.

Gereserveerde trefwoorden

Microsoft Entra-authenticatiemodi

Het Authentication trefwoord ondersteunt de volgende waarden. Kies de modus die bij je inzet past:

Voor reproduceerbare Docker-, devcontainer- en CI-omgevingsopstelling, zie Container en lokale ontwikkeling. Dat artikel centraliseert de runtimeselectie van Python en laat zien hoe digest-vastgepinde afbeeldingen in gedeelde omgevingen gebruikt kunnen worden.

Voorbeeld: DefaultAzureCredential

ActiveDirectoryDefaultwordt overeengebracht met de Azure Identity-ketenDefaultAzureCredential. Het probeert eerst de Azure CLI-token tijdens lokale ontwikkeling, daarna managed identity wanneer het wordt uitgezonden naar Azure:

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

Voorbeeld: Apparaatcodeflow

Gebruik apparaatcodeflow wanneer je draait in omgevingen zonder browser, zoals SSH-sessies of Docker-containers. De driver toont een URL en een code die op een apart apparaat ingevoerd moet worden:

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

Voorbeeld: Service Principal

Service principal-authenticatie gebruikt een geregistreerde applicatie-identiteit met een client-ID en geheim. Gebruik deze aanpak voor CI/CD-pijplijnen en achtergrondservices die draaien zonder gebruikersinteractie:

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

Om de applicatie te registreren en database-toegang te verlenen, zie Microsoft Entra service principals with Azure SQL. Voor de volledige setup in mssql-python, zie Service principal authenticatie.

Verbindingstijdoverschrijding

Stel de verbindingstime-out in met de timeout parameter. Gebruik een timeout om te voorkomen dat je applicatie oneindig vastloopt wanneer de server onbereikbaar is:

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

Je kunt ook de time-out op een bestaande verbinding wijzigen:

conn.timeout = 60

Modus Automatisch aanpassen

Standaard autocommit is False, wat expliciete commit() aanroepen vereist. Schakel autocommit in voor DDL-statements of alleen-lezen queries die geen transactiecontrole nodig hebben:

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

# Or after connection
conn.setautocommit(True)

Verbindingskenmerken

Stel ODBC-verbindingsattributen in voordat de verbinding wordt opgebouwd door te gebruiken 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 verbindingsreeks building

Om verbindingsreeks injection te voorkomen, gebruik geen stringconcatenatie of f-strings met gebruikersinvoer. Gebruik in plaats daarvan trefwoordargumenten of omgevingsvariabelen. Voor meer constructiepatronen, waaronder JSON/YAML-configuratiebestanden, Azure Key Vault en een builder-klasse, zie 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"
)

Verificatie van verbindingsstrings

De driver valideert verbindingsstrings en verhoogt ConnectionStringParseError voor onbekende of verkeerd gespelde trefwoorden:

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

Verwante onderwerpen

• Bouw verbindingsstrings programmatisch
• Installeer mssql-python
• Microsoft Entra-authenticatie
• Groepsgewijze verbindingen
• Verbindingsbeheer