Verbindung zu einem Microsoft SQL Server mit Python und Pyodbc

Mit pyodbc verbinden Sie eine Python-Anwendung über ODBC mit Microsoft SQL Server. Installieren Sie sowohl das Python-Paket als auch einen kompatiblen SQL-Server-ODBC-Treiber. Übergeben Sie anschließend Server, Datenbank, Treiber und Authentifizierungseinstellungen an pyodbc.connect(). Diese Anleitung verwendet direktes SQL. Ein ORM ist eine weitere Möglichkeit, wenn Sie Datenbanktabellen als Python-Objekte abbilden möchten.

pyodbc und den SQL-Server-ODBC-Treiber installieren

Installieren Sie pyodbc in derselben Python-Umgebung, in der Ihre Anwendung ausgeführt wird, beispielsweise mit python -m pip install pyodbc. Damit wird die Python-Schnittstelle installiert, nicht jedoch der ODBC-Treiber von Microsoft. Installieren Sie einen SQL-Server-ODBC-Treiber separat auf dem Rechner oder im Container, auf dem das Programm läuft. Achten Sie darauf, dass sein Name exakt mit dem installierten Treiber übereinstimmt. Ein gängiger Name ist ODBC Driver 18 for SQL Server; verwenden Sie den Namen, der auf Ihrem System verfügbar ist.

Besorgen Sie vor dem Verbindungsaufbau die Serveradresse und den Datenbanknamen. Als Serverangabe kommen ein Hostname, eine Adresse oder ein Host mit Instanzname infrage, etwa db.example.net\SQLEXPRESS; bei gehosteten Umgebungen ist möglicherweise zusätzlich ein Port erforderlich. Ihre Administration muss dem Konto eventuell Zugriff auf die ausgewählte Datenbank gewähren. Die SQL-Server-Verbindungsdaten hängen nicht vom Arbeitsverzeichnis von Python ab. Der Treiber muss jedoch dem ODBC-Manager des Betriebssystems zur Verfügung stehen.

Mit einem Treiber und vertrauenswürdiger Authentifizierung verbinden

Verwenden Sie in einer für integrierte Authentifizierung konfigurierten Windows-Umgebung eine treiberbasierte Verbindungszeichenfolge mit Trusted_Connection=yes. Ersetzen Sie die Angaben zu Treiber, Server und Datenbank durch die Werte Ihrer Installation. Das folgende kurze Programm erstellt die Zeichenfolge und gibt sie aus, damit Sie sehen können, wie die Felder zusammengesetzt werden. Es stellt keine Verbindung zu einer Datenbank her.

Führen Sie dieses Beispiel aus:

Der Code und die angezeigten Bezeichnungen oder Ausgaben in diesem Abschnitt bleiben auf Englisch.

driver = "ODBC Driver 18 for SQL Server"
server = "db.example.net"
database = "Sales"
connection_string = (
    f"Driver={{{driver}}};"
    f"Server={server};"
    f"Database={database};"
    "Trusted_Connection=yes;"
)
print(connection_string)

Driver={ODBC Driver 18 for SQL Server};Server=db.example.net;Database=Sales;Trusted_Connection=yes;

Um die Verbindung in Ihrer Anwendung zu öffnen, übergeben Sie die Zeichenfolge an pyodbc.connect(connection_string). Bei der integrierten Authentifizierung wird die Identität des Prozesses verwendet. Welche Identität das ist, hängt von der Konfiguration des Betriebssystems, des Treibers und von SQL Server ab. Das ist nicht dasselbe wie die Angabe eines SQL-Server-Benutzernamens und eines Kennworts. Richten Sie TLS gemäß den Zertifikatsvorgaben Ihrer Organisation ein. Verschiedene Treiberversionen können unterschiedliche Verschlüsselungsstandards verwenden. Deaktivieren Sie daher nicht die Zertifikatsprüfung, nur damit eine Verbindung zustande kommt.

Über einen DSN mit Zugangsdaten verbinden

Ein Data Source Name (DSN) ist eine auf dem Host eingerichtete ODBC-Konfiguration. Darin können gemeinsame Server- und Treibereinstellungen hinterlegt werden. Die Anwendung muss dann nur den DSN-Namen und, falls erforderlich, die Zugangsdaten angeben. Die Verbindungszeichenfolge hat beispielsweise die Form DSN=SalesReadOnly;UID=app_reader;PWD=<secret>;. Der DSN muss in derselben Umgebung eingerichtet und für den Python-Prozess sichtbar sein. Ein für einen interaktiven Benutzer konfigurierter DSN ist möglicherweise für ein Dienstkonto oder einen Container nicht verfügbar.

Beziehen Sie Zugangsdaten aus einem Secret-Manager oder einer umgebungsspezifischen Konfiguration, statt sie in den Quellcode aufzunehmen. Enthält ein Secret Sonderzeichen, beachten Sie die Zitierregeln für ODBC-Verbindungszeichenfolgen oder konfigurieren Sie die Zugangsdaten separat. Andernfalls kann ein Semikolon als Feldtrenner interpretiert werden. Geben Sie die vollständige Verbindungszeichenfolge nicht aus, da dadurch das Kennwort in Protokollen offengelegt werden kann. Verwenden Sie denselben Aufruf pyodbc.connect(...) mit der DSN-Zeichenfolge und wählen Sie je nach Konfiguration des DSN und des Servers die integrierte oder die SQL-Authentifizierung.

Eine Abfrage ausführen und Ressourcen schließen

Erstellen Sie nach dem Verbindungsaufbau einen Cursor, führen Sie SQL aus und rufen Sie die zurückgegebenen Zeilen ab oder durchlaufen Sie sie. Verwenden Sie Parameterplatzhalter für Werte aus Benutzereingaben oder Anwendungsdaten. In pyodbc ist ? der Positionsplatzhalter. Wenn Sie Werte separat übergeben, bleiben sie vom SQL-Text getrennt. Parameter sind für Datenwerte vorgesehen, nicht für Tabellen- oder Spaltennamen. Muss ein Bezeichner variieren, wählen Sie ihn aus einer festen Zulassungsliste aus und maskieren Sie ihn gemäß den SQL-Server-Regeln.

Ein typischer Ablauf in einer Anwendung ist connection = pyodbc.connect(connection_string), gefolgt von cursor = connection.cursor() und cursor.execute("SELECT name FROM dbo.Customers WHERE customer_id = ?", customer_id). Durchlaufen Sie cursor, um die Zeilen zu verarbeiten, oder rufen Sie fetchall() auf, wenn das Ergebnis klein genug ist, um im Arbeitsspeicher zu bleiben. Große Ergebnismengen sollten Sie schrittweise verarbeiten. Die Abfrage setzt voraus, dass die angegebene Tabelle und Spalte in der ausgewählten Datenbank vorhanden sind; passen Sie sie an Ihr Schema an.

Sobald connection = pyodbc.connect(connection_string) erfolgreich war, führen Sie Cursoroperationen innerhalb eines try-Blocks aus und schließen Sie die Verbindung in dessen finally-Klausel: try: ... finally: connection.close(). Verwenden Sie für den Cursor innerhalb dieses Blocks with connection.cursor() as cursor:; beim Verlassen des Kontexts wird der Cursor geschlossen. Ein Verbindungskontext von pyodbc wie with connection: verwaltet den Transaktionsumfang: Er bestätigt die Transaktion bei normalem Verlassen und setzt sie zurück, wenn eine Ausnahme weitergereicht wird. Er schließt jedoch nicht die Verbindung. Sie können diesen Transaktionskontext zusammen mit dem Cursor-Kontext im try-Block verwenden und anschließend in finally connection.close() aufrufen. Damit wird die Verbindung nach der Abfrage sowohl bei normalem als auch bei fehlerhaftem Ablauf geschlossen, sofern sie erfolgreich geöffnet wurde. Wenn Sie Daten ändern, legen Sie ausdrücklich fest, wann die Transaktion bestätigt werden soll. Dieses Verwendungsmuster setzt einen konfigurierten SQL Server, Treiber und ein passendes Schema voraus. Es wurde im Rahmen dieses Artikels nicht ausgeführt.

Häufige Verbindungsfehler beheben

Meldet pyodbc, dass ein Treiber nicht gefunden wurde, prüfen Sie, ob der ODBC-Treiber in der Laufzeitumgebung des Programms installiert ist und ob der Wert Driver={...} exakt seinem registrierten Namen entspricht, einschließlich Leerzeichen und Versionsnummer. Ist der Server nicht erreichbar, kontrollieren Sie DNS-Auflösung und Hostnamen, Port- und Instanzeinstellungen, Firewallzugriff sowie die Netzwerkkonfiguration von SQL Server. Ein Timeout weist häufig auf Verbindungsprobleme oder eine hohe Serverlast hin. Eine längere Wartezeit behebt keine falsche Zieladresse.

Prüfen Sie bei Anmeldefehlern, welche Identität die Verbindung tatsächlich verwendet. Die vertrauenswürdige Authentifizierung nutzt die Prozessidentität; UID und PWD fordern dagegen SQL-Zugangsdaten an. Werden diese Verfahren verwechselt, kann die falsche Identität übermittelt werden. Prüfen Sie danach den Datenbanknamen und die Zugriffsrechte. Klären Sie bei Zertifikats- oder Verschlüsselungsfehlern mit Ihrer Administration die Zertifikatskette des Servers und die Verschlüsselungseinstellungen des Treibers, statt die Prüfung abzuschwächen. Kontrollieren Sie zum Schluss die Verbindungszeichenfolge auf fehlende Semikolons, nicht geschlossene geschweifte Klammern um Treibernamen, versehentliche Leerzeichen in Schlüsseln und nicht maskierte Sonderzeichen. Protokolle sollten bei der Fehlersuche helfen, aber Kennwörter und andere Secrets müssen darin geschwärzt werden.

Details zu Treibern und Verbindungszeichenfolgen finden Sie in der Anleitung für pyodbc-Verbindungen mit SQL Server und in der offiziellen pyodbc-Dokumentation. Ein verwandter Beitrag zeigt, wie Sie Abfrageergebnisse lesen: Elemente aus einer Datenbank mit fetchall() in Python auslesen. Für diesen Beitrag ist kein deutsches Linkziel verfügbar; der Link führt deshalb weiterhin zur englischen Fassung.