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.

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.

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.

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.

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.

Reservierte Schlüsselwörter

Microsoft Entra-Authentifizierungsmodi

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

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'

Verwandte Inhalte

• Erstellen Sie Verbindungsstrings programmatisch
• Installiere mssql-python
• Microsoft Entra-Authentifizierung
• Verbindungspooling
• Verbindungsverwaltung