Verbindungsstrings für mssql-python

Der mssql-python-Treiber unterstützt folgende Verbindungszeichenfolge-Schlüsselwörter beim Anschluss an SQL Server, Azure SQL-Datenbank, Azure SQL Managed Instance und SQL Database in Microsoft Fabric.

Syntax von Verbindungszeichenfolgen

Verbindungsstrings verwenden durch Semikolon getrennte Schlüssel-Wert-Paare:

keyword1=value1;keyword2=value2;...

Wickelwerte, die spezielle Zeichen (Semikolon, Gleichzeichenzeichen oder gelockte Klammer) enthalten, in Krause:

PWD={my;complex=password}

Um eine buchstäbliche schließende Strebe in einen Wert einzubeziehen, verwenden Sie zwei schließende Klammern (}}):

PWD={password}}with}}brace}

Grundlegende Verbindungsbeispiele

Die folgenden Beispiele zeigen, wie man sich mit verschiedenen Authentifizierungsmethoden verbindet. Für Produktionsanwendungen verwenden Sie wann immer möglich die Microsoft Entra-Authentifizierung. Es entfernt Passwörter aus deinem Code und den Verbindungssträngen.

SQL Server mit Microsoft Entra-Authentifizierung (empfohlen)

Dieses Beispiel verwendet ActiveDirectoryDefault, das mehrere Zugangsdatenquellen (Azure CLI, Umgebungsvariablen, verwaltete Identität) der Reihe nach ausprobiert. Im Code wird kein Passwort gespeichert:

import mssql_python

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

SQL Server mit SQL-Authentifizierung

Verwenden Sie SQL-Authentifizierung nur für lokale Entwicklung gegenüber einer SQL Server-Instanz, die Sie kontrollieren. Zugangsdaten sind in die Verbindungszeichenfolge eingebettet, daher sollten Sie sie in Umgebungsvariablen oder einer .env Datei speichern, anstatt im Quellcode:

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

Azure SQL with Microsoft Entra authentication

Die Verbindungszeichenfolge für Azure SQL-Datenbank ist dieselbe wie für SQL Server. ActiveDirectoryDefaultfunktioniert über lokale Entwicklung, Container und Azure-gehostete Umgebungen ohne Codeänderungen:

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

Verwendung von Schlüsselwortargumenten

Du kannst Verbindungsparameter als Schlüsselwortargumente anstelle oder zusätzlich zu einer Verbindungszeichenfolge weitergeben. Keyword-Argumente vermeiden die ausweichenden Fallstricke der Verbindungszeichenfolge-Assemblierung. Passwörter mit Sonderzeichen wie @, ;, , {oder } benötigen kein Curly-Brace Wrapping, wenn sie als Schlüsselwortargumente übergeben werden:

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

Vergleichen Sie mit der Verbindungszeichenfolge assembly, bei der ein Passwort, das das enthält@, gewrappt werden muss:

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

Der Treiber fügt nach der Normalisierung Schlüsselwortargumente in die Verbindungszeichenfolge ein. Wenn ein Schlüsselwortargument mit einem bereits im Verbindungszeichenfolge vorhandenen Parameter übereinstimmt, erhält das Schlüsselwortargument Vorrang und überschreibt den Wert des Verbindungszeichenfolge:

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

Das folgende Beispiel kombiniert eine Verbindungszeichenfolge mit Schlüsselwortargumenten:

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

Schlüsselwörter für Verbindungszeichenfolgen

Server und Datenbank

Gib die Zielinstanz SQL Server Instanz und Datenbank für die Verbindung an.

Keyword	Decknamen	Vorgabe	Beschreibung
`Server`	`addr`, `address`	Nichts	SQL Server-Hostname, IP-Adresse oder benannte Instanz. Für benannte Instanzen verwenden `server\instance`Sie . Für Azure SQL verwenden `server.database.windows.net`Sie . Um einen Port anzugeben, verwenden `server,port`Sie .
`Database`	Nichts	Nichts	Datenbankname, mit dem eine Verbindung hergestellt werden soll.

Authentifizierung

Geben Sie Zugangsdaten für SQL-Authentifizierung bereit oder geben Sie einen Microsoft Entra-Authentifizierungsmodus an. Für passwortlose Optionen siehe Microsoft Entra-Authentifizierungsmodi.

Keyword	Decknamen	Vorgabe	Beschreibung
`UID`	`uid`	Nichts	Benutzername für SQL-Authentifizierung.
`PWD`	`pwd`	Nichts	Passwort für SQL-Authentifizierung.
`Trusted_Connection`	`trusted_connection`	`no`	Verwenden Sie die integrierte Authentifizierung von Windows. Zum Aktivieren auf `yes` festlegen.
`Authentication`	`authentication`	Nichts	Microsoft Entra-Authentifizierungsmodus. Siehe Microsoft Entra-Authentifizierung.

Verschlüsselung und Sicherheit

Alle Verbindungen werden standardmäßig verwendet Encrypt=yes . Für die meisten Anwendungen reicht der Standard aus. Verwenden strict Sie nur, wenn Ihre SQL Server-Instanz TDS 8.0 unterstützt und Sie TLS 1.3 benötigen. TrustServerCertificate=yes Verwendung nur in Entwicklungsumgebungen mit selbstsignierten Zertifikaten.

Keyword	Decknamen	Vorgabe	Beschreibung
`Encrypt`	`encrypt`	`yes`	Aktivieren Sie die TLS-Verschlüsselung. Werte: `yes`, `no`, `strict`. Verwendung `strict` für TDS 8.0 mit verpflichtendem TLS 1.3.
`TrustServerCertificate`	`trust_server_certificate`, `trustservercertificate`	`no`	Vertrauen Sie selbstsignierten Serverzertifikaten ohne Validierung. Nur für `yes` die Entwicklung eingestellt.
`HostnameInCertificate`	`hostnameincertificate`	Nichts	Erwarteter Hostname im TLS-Zertifikat des Servers.
`ServerCertificate`	`servercertificate`	Nichts	Pfad zu einer PEM-Datei, die die vertrauenswürdige Zertifizierungsstelle enthält.
`ServerSPN`	`serverspn`	Nichts	Server Service Principal Name für Kerberos-Authentifizierung.

Hohe Verfügbarkeit und Failover

Diese Schlüsselwörter beziehen sich auf Always On-Verfügbarkeitsgruppen-Deployments. Stellen Sie ein, ApplicationIntent=ReadOnly dass leseintensive Arbeitslasten (Berichte, Analysen) auf sekundäre Repliken weitergeleitet werden, wodurch die Belastung des primären Codes reduziert wird. Stell ein, MultiSubnetFailover=yes wenn deine Verfügbarkeitsgruppe mehrere Subnetze umfasst.

Keyword	Decknamen	Vorgabe	Beschreibung
`MultiSubnetFailover`	`multisubnetfailover`	`no`	Multi-Subnet-Failover für Always On-Verfügbarkeitsgruppen aktivieren.
`ApplicationIntent`	`applicationintent`	`ReadWrite`	Geben Sie den Typ der Anwendungsarbeit an. `ReadOnly` Verwendung für Nur-Lese-Routing zu sekundären Replikaten.
`ConnectRetryCount`	`connectretrycount`	`1`	Anzahl der automatischen Wiederanschlussversuche für die Widerstandsfähigkeit der Leerlaufverbindung. Dies ist eine Funktion auf Treiberebene für unterbrochene Leerlaufverbindungen, kein Ersatz für Anwendungs-Wiederholungslogik.
`ConnectRetryInterval`	`connectretryinterval`	`10`	Sekunden zwischen den Versuchen der Wiederanschlussverbindung in Leerlaufverbindung.

Aufführung und Netzwerk

Die Standardeinstellungen funktionieren für die meisten Anwendungen. Erhöhung PacketSize (bis zu 32767) für Massenübertragungen von Daten. Konfigurieren Sie KeepAlive , ob Verbindungen Firewalls oder Load Balancer überschreiten, die Leerlauf-TCP-Sitzungen abbrechen.

Keyword	Decknamen	Vorgabe	Beschreibung
`PacketSize`	`packet size`, `packetsize`	`4096`	Netzwerkpaketgröße in Bytes (512–32767).
`KeepAlive`	`keepalive`	Nichts	TCP-Halte-Alive-Intervall in Sekunden.
`KeepAliveInterval`	`keepaliveinterval`	Nichts	TCP-Halte-Alive-Wiederholungsintervall in Sekunden.
`IpAddressPreference`	`ipaddresspreference`	Nichts	IP-Adressfamilienpräferenz: `IPv4First`, `IPv6First`, `UsePlatformDefault`.

Reservierte Schlüsselwörter

Keyword	Beschreibung
`Driver`	Reserviert für die interne Verwendung. Der Fahrer verwaltet diesen Wert automatisch.
`APP`	Reserviert. Immer vom `"MSSQL-Python"` Fahrer auf gestellt.

Microsoft Entra-Authentifizierungsmodi

Das Schlüsselwort Authentication unterstützt die folgenden Werte. Wählen Sie den Modus, der zu Ihrer Bereitstellung passt:

Wert	Beschreibung	Wann verwenden?
`ActiveDirectoryDefault`	Verwendet `DefaultAzureCredential` das Azure Identity SDK. Versucht mehrere Authentifizierungsmethoden hintereinander.	Lokale Entwicklung über Azure CLI, Azure PowerShell und Azure Developer CLI. Für die Produktion verwenden Sie einen bestimmten Modus (`ActiveDirectoryMSI`, `ActiveDirectoryServicePrincipal`), um den langsamen Credential-Chain-Walk zu vermeiden.
`ActiveDirectoryInteractive`	Browserbasierte interaktive Anmeldung. Unter Windows delegiert man nativ an den ODBC-Treiber.	Lokale Entwicklung und Tools, bei denen ein Benutzer anwesend ist, um sich im Browser zu authentifizieren.
`ActiveDirectoryDeviceCode`	Gerätecode-Fluss für headless-Umgebungen. Zeigt einen Code an, den man bei eingeben muss `https://microsoft.com/devicelogin`.	SSH-Sitzungen, Docker-Container oder andere Umgebungen ohne Browser.
`ActiveDirectoryPassword`	Deprecated. Benutzernamens- und Passwortauthentifizierung mit Microsoft Entra ID. Erfordert `UID` und `PWD`. Verwendet den ROPC-Fluss, der mit MFA nicht kompatibel ist.	Nicht empfohlen. Verwenden Sie stattdessen `ActiveDirectoryMSI` oder `ActiveDirectoryServicePrincipal`.
`ActiveDirectoryMSI`	Managed Service Identity für von Azure gehostete Anwendungen.	Azure VMs, App Service oder Azure Functions, bei denen die verwaltete Identität konfiguriert ist. Es sind keine Anmeldeinformationen erforderlich.
`ActiveDirectoryServicePrincipal`	Authentifizierung des Dienstprinzipals. Benötigt `UID` (Client-ID) und `PWD` (Client-Geheimnis).	CI/CD-Pipelines und Hintergrunddienste, die eine registrierte Anwendungsidentität verwenden.
`ActiveDirectoryIntegrated`	Windows integrierte Authentifizierung mit Microsoft Entra ID (Kerberos).	Domänengebundene Windows-Rechner in Unternehmensumgebungen mit konfiguriertem Kerberos.

Für reproduzierbare Docker-, Devcontainer- und CI-Umgebungseinrichtungen siehe Container und lokale Entwicklung. Dieser Artikel zentralisiert die Python-Laufzeitauswahl und zeigt, wie man Digest-gepinnte Bilder in geteilten Umgebungen verwendet.

Beispiel: DefaultAzureCredential

ActiveDirectoryDefaultauf die Azure Identity-Kette DefaultAzureCredential abgebildet. Es versucht zuerst das Azure CLI-Token während der lokalen Entwicklung und dann die verwaltete Identität, wenn es auf Azure bereitgestellt wird:

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

Beispiel: Gerätecodefluss

Verwenden Sie den Gerätecodefluss, wenn Sie in Umgebungen ohne Browser laufen, wie z. B. SSH-Sitzungen oder Docker-Container. Der Treiber zeigt eine URL und einen Code an, den man auf einem separaten Gerät eingeben kann:

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

Beispiel: Service Principal

Die Service Principal Authentifizierung verwendet eine registrierte Anwendungsidentität mit einer Client-ID und einem Geheimnis. Verwenden Sie diesen Ansatz für CI/CD-Pipelines und Hintergrunddienste, die ohne Benutzerinteraktion laufen:

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

Um die Anwendung zu registrieren und Datenbankzugriff zu gewähren, siehe Microsoft Entra Service Principals with Azure SQL. Für die vollständige Einrichtung in mssql-python, siehe Service Principal Authentication.

Verbindungstimeout

Stellen Sie das Verbindungs-Timeout mit dem Parameter timeout ein. Nutzen Sie eine Zeitpause, um zu verhindern, dass Ihre Anwendung unbegrenzt hängt, wenn der Server nicht erreichbar ist:

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

Sie können auch die Zeitgrenze bei einer bestehenden Verbindung ändern:

conn.timeout = 60

Autocommit-Modus

Standardmäßig autocommit ist False, was explizite commit() Aufrufe erfordert. Autocommit für DDL-Anweisungen oder schreibgeschützte Abfragen aktivieren, die keine Transaktionssteuerung benötigen:

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

# Or after connection
conn.setautocommit(True)

Verbindungsattribute

Setzen Sie ODBC-Verbindungsattribute, bevor die Verbindung hergestellt wird, indem Sie verwenden 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,
    }
)

Programmatisches Verbindungszeichenfolge-Aufbau

Um Verbindungszeichenfolge injection zu verhindern, verwenden Sie keine String-Verkettung oder f-Strings mit Benutzereingabe. Verwenden Sie stattdessen Keyword-Argumente oder Umgebungsvariablen. Für weitere Konstruktionsmuster, einschließlich JSON/YAML-Konfigurationsdateien, Azure Key Vault und einer Builder-Klasse, siehe 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"
)

Validierung von Verbindungsstrings

Der Treiber validiert Verbindungsstrings und erhöht ConnectionStringParseError für unbekannte oder falsch geschriebene Schlüsselwörter:

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

Feedback

War diese Seite hilfreich?

Last updated on 2026-07-22