ODBC-Verbindungen zu Microsoft SQL konfigurieren

Konfigurieren Sie eine ODBC-Verbindung, indem Sie auswählen, wo ihre Einstellungen gespeichert werden, mit welcher Datenbank verbunden werden sollen, wie Sie authentifizieren und wie die Verbindung geschützt wird. Fügen Sie Routing-, Wiederherstellungs- oder anwendungsspezifische Einstellungen nur hinzu, wenn Ihre Bereitstellung sie benötigt.

Dieser Leitfaden erklärt diese Möglichkeiten für den Microsoft ODBC-Treiber für SQL Server unter Windows, Linux und macOS. ODBC Driver 18 ist die aktuelle Hauptversion; ODBC Driver 17 bleibt ein unterstütztes Ziel. Die Beispiele verwenden Treiber 18 und identifizieren Einstellungen, die sich in Treiber 17 unterscheiden. Verwenden Sie die Schlüsselwort- und Attributreferenz, um jedes akzeptierte Schlüsselwort, jeden Wert und jede Plattform nachzuschlagen.

Auswählen einer Verbindungsmethode

Eine Verbindungszeichenfolge liefert dem Treiber keyword=value;-Paare. Ein Datenquellenname (DSN) speichert Verbindungseinstellungen getrennt, sodass die Anwendung sie mit Namen ansprechen kann. Beide Methoden verwenden denselben Treiber, dieselben Authentifizierungsmethoden und dieselben Datenbankberechtigungen.

Method Wann wird es verwendet? Was die Anwendung bereitstellt
DSN-frei Behalten Sie die Konfiguration mit der Anwendung, zum Beispiel in einer Bereitstellungskonfiguration oder einem Container. Du musst nicht auf jedem Client eine DSN erstellen. Driver, Server, Database, Authentifizierung, und andere Verbindungseinstellungen. Der Treiber muss noch installiert werden.
Benutzer-DSN Konfigurieren Sie eine Desktop-Anwendung für einen einzelnen Betriebssystembenutzer oder eine Anwendung, die eine benannte Datenquelle benötigt. DSN=<data_source_name> sowie alle bei der Verbindung angegebenen Einstellungen, einschließlich Zugangsdaten. Nur die Anwendungen dieses Benutzers können das Benutzer-DSN verwenden.
System-DSN Lassen Sie Anwendungen, die unter verschiedenen Identitäten laufen, wie etwa ein Servicekonto, eine Konfiguration auf Maschinenebene verwenden. DSN=<data_source_name> und Verbindungszeiteinstellungen. Der Prozess muss Zugriff auf das System-DSN und dessen Treiber haben.
Datei-DSN Verwenden Sie eine Anwendung, die Verbindungseinstellungen in einer .dsn Datei erwartet. FileDSN=<file_path> und Verbindungszeiteinstellungen. Die Datei installiert den Treiber nicht und macht die Pfade nicht betriebssystemübergreifend nutzbar.

Verwenden Sie pro Verbindung eine Auswahlmethode. Kombinieren Sie DSN, Driver und FileDSN nicht, um den DSN-Treiber zu ändern. Ein Dienst verwendet nicht automatisch die DSN Ihres interaktiven Benutzers.

In nativen Anwendungen akzeptiert SQLConnect eine DSN sowie getrennte Argumente für Benutzer-ID und Passwort. SQLDriverConnect akzeptiert einen Verbindungszeichenfolge, einschließlich DSN- und DSN-loser Formen. Anwendungen und Frameworks, die ODBC verwenden, bestimmen, welche Eingabe sie bereitstellen. Folgen Sie der Konfigurationsoberfläche der Anwendung, anstatt davon auszugehen, dass sie jedes ODBC-Schlüsselwort als Befehlszeilenoption akzeptiert.

Beginnen Sie mit einer "Verbindungszeichenfolge"

Wählen Sie zuerst die Verbindungsform aus, und wählen Sie dann in den folgenden Abschnitten die Authentifizierung sowie weitere Optionen aus. Diese Beispiele verwenden SQL-Authentifizierung. Behalten Sie UID , PWD oder Authentication=SqlPassword beim Wechsel zu einer inkompatiblen Authentifizierungsmethode nicht bei.

Ersetzen Sie <server>, <database>, <user_id>und <password> durch Ihre Werte. Verwenden Sie für Azure SQL-Datenbank <server>.database.windows.net als Hostnamen. Die Beispiele verwenden den Transmission Control Protocol (TCP)-Port 1433; ersetzen Sie ihn durch den für Ihren Endpunkt konfigurierten Port.

Ohne DSN verbinden

Geben Sie den installierten Treibernamen und die Verbindungseinstellungen direkt an:

Driver={ODBC Driver 18 for SQL Server};Server=tcp:<server>,1433;Database=<database>;UID=<user_id>;PWD=<password>;Authentication=SqlPassword;Encrypt=yes;TrustServerCertificate=no;

Ersetzen Sie für Treiber 17 den Treibernamen durch ODBC Driver 17 for SQL Server. Die anderen Einstellungen in diesem Beispiel funktionieren mit beiden Hauptversionen.

Verbinden Sie sich mit einem DSN

Nachdem Sie die DSN erstellt haben, geben Sie ihren Namen und die Authentifizierungseinstellungen der Anwendung an:

DSN=MSSQLTest;UID=<user_id>;PWD=<password>;Authentication=SqlPassword;Encrypt=yes;TrustServerCertificate=no;

Das DSN wählt den Treiber, Server und die Datenbank aus. Das Beispiel wiederholt die Sicherheitseinstellungen explizit, sodass die Anwendung denselben Schutz bei beiden Verbindungsformen anfordert.

Speichere keine echten Passwörter in einer DSN, einer Datei-DSN, odbc.ini, einer Quelldatei oder einem Shell-Befehl. Rufen Sie Secrets über den Zugangsdatenverwaltungsmechanismus der Anwendung ab und geben Sie sie beim Verbindungsaufbau bereit. Behandeln Sie jede „Verbindungszeichenfolge“, die ein Passwort, einen Token oder ein Key-Store-Geheimnis enthält, als sensible Daten, auch in Logs und Diagnoseerfassungen.

Wählen Sie Treiber, Server und Datenbank aus

Diese Einstellungen bestimmen, was die Anwendung lädt und womit sie sich verbindet.

Setting Wann und wie man es benutzt
Driver Wählen Sie den installierten Treiber nach seinem registrierten Namen für eine DSN-freie Verbindung aus. Treiber 17 und Treiber 18 haben unterschiedliche Namen und können nebeneinander installiert werden. Die Installation von Treiber 18 leitet eine Verbindung nicht um, die explizit den Treiber 17 auswählt.
Server=tcp:<server>,1433 Verwenden Sie einen bekannten TCP-Endpunkt und -Port. Das Komma trennt den Hostnamen vom Port. Linux und macOS unterstützen nur TCP. Ein expliziter Port vermeidet die Abhängigkeit von der Erkennung benannter Instanzen.
Server=<server>\<instance> Verbinden Sie sich mit einer benannten SQL Server-Instanz, wenn die Instanzerkennung verfügbar ist. Unter Linux und macOS erfordert dies Treiber 17.4 und spätere Versionen, einschließlich Treiber 18. Wenn die Erkennung nicht verfügbar ist, erhalten Sie den TCP-Port der Instanz und verwenden Sie die Form mit expliziter Portangabe.
Database=<database> Wählen Sie die initiale Datenbank bewusst aus, insbesondere für einen Benutzer einer eigenständigen Datenbank oder eine Anwendung, die nicht von der Standarddatenbank des Logins abhängig sein darf. Diese Einstellung erstellt die Datenbank nicht und gewährt keinen Zugriff.
Address oder Addr Pflegen Sie eine Anwendung, die eine separate Netzwerkadresse verwendet. Vermeiden Sie, einen widersprüchlichen ServerEndpunkt anzugeben; verwenden Sie einen gezielt festgelegten Endpunkt, anstatt sich auf Vorrang zwischen Namen zu verlassen.
Network oder Net Pflegen Sie eine Windows-Konfiguration, die explizit eine Netzwerkbibliothek auswählt. Bevorzugen Sie das tcp: Serverpräfix für eine plattformübergreifende TCP-Verbindung. Kombinieren Sie kein Protokollpräfix mit einer widersprüchlichen Netzwerkauswahl.

Ein Serveralias, eine benannte Instanz, ein Domain Name System (DNS)-Hostname und ein Port sind nicht austauschbar. Verwenden Sie einen DNS-Namen, der mit dem Zertifikat einer verschlüsselten Fernverbindung übereinstimmt. Eine IP-Adresse behebt keinen Zertifikatnamenskonflikt.

Für Azure SQL-Datenbank und andere verwaltete Dienste verwenden Sie den veröffentlichten Endpunkt des Dienstes. Für eine Verfügbarkeitsgruppe verwenden Sie deren Listener, wenn Sie Failover oder schreibgeschütztes Routing wünschen, anstatt den Hostnamen einer Replika fest zu codieren.

Auswählen der Authentifizierung

Die Authentifizierung bestimmt, welche Identität die Verbindung herstellt. Es gewährt dieser Identität keine Datenbankberechtigungen und ersetzt auch nicht die Verschlüsselungseinstellungen.

Method Verbindungseinstellungen Wann Sie es verwenden sollten und die Voraussetzungen
SQL-Authentifizierung Authentication=SqlPassword, UIDund PWD. Das Zielsystem unterstützt die SQL-Authentifizierung, und Sie haben einen SQL-Login oder Datenbankbenutzer mit einem Passwort. Sowohl Treiber 17 als auch Treiber 18 unterstützen diese Form. UIDist der SQL-Benutzername, kein Microsoft Entra ID-Konto.
Integrierte Windows-Authentifizierung Trusted_Connection=yes; UID und PWD weglassen. Verwenden Sie die Windows-Identität des Prozesses für ein Ziel, das für Windows-Authentifizierung konfiguriert ist. Unter Linux und macOS konfigurieren Sie Kerberos und erhalten Sie ein Ticket für die Identität der Anwendung. Das ist keine integrierte Microsoft Entra-Authentifizierung.
Integrierte Microsoft Entra-Authentifizierung Authentication=ActiveDirectoryIntegrated; SQL-Anmeldeinformationen weglassen. Verwenden Sie eine bestehende Windows- oder Kerberos-Identität in einer Microsoft Entra-Konfiguration, die integrierte Authentifizierung unterstützt. Linux und macOS benötigen Treiber 17.6 und neuere Versionen, einschließlich Treiber 18.
Interaktive Microsoft Entra-Authentifizierung Authentication=ActiveDirectoryInteractive; PWD weglassen. Eine Person kann die Anmeldung und die Multifaktor-Authentifizierung durchführen. Unterstützt unter Windows, einschließlich Treiber 17.1 und neuerer Versionen. Geben Sie für Treiber 17.1 bis 17.7 den Microsoft Entra-Benutzernamen in UID an. Treiber 17.8 und neuere Versionen, einschließlich Treiber 18, erlauben es Ihnen, UID wegzulassen. Wählen Sie diese Methode nicht für einen unbeaufsichtigten Dienst.
Verwaltete Microsoft Entra-Identität Authentication=ActiveDirectoryMsi. Führen Sie auf einem Host aus, der einen unterstützten verwalteten Identitäts-Endpunkt bereitstellt. Eine systemzugewiesene Identität erfordert UID nicht. Eine vom Benutzer zugewiesene Identität erfordert UID mit der für diesen Host passenden Kennung. Verfügbar in Treiber 17.3.1.1 und späteren Versionen, einschließlich Treiber 18.
Microsoft Entra Service Principal Authentication=ActiveDirectoryServicePrincipal; UID ist die Client-ID der Anwendung und PWD ist sein Client-Geheimnis. Eine unbeaufsichtigte Anwendung verwendet eine Microsoft Entra-Anwendungsidentität, bei der die verwaltete Identität nicht geeignet ist. Verfügbar ab Driver 17.7 und höheren Versionen, einschließlich Driver 18. Schützen und erneuern Sie das Clientgeheimnis regelmäßig.
Von der Anwendung bereitgestelltes Microsoft Entra-Zugriffstoken Legen Sie das SQL_COPT_SS_ACCESS_TOKEN Verbindungsattribut vor der Verbindung fest. Die Anwendung erhält den Token selbst. Dies ist ein Attribut eines Application Programming Interface (API), kein Verbindungszeichenfolge-Schlüsselwort. Lasse UID, PWD, Trusted_Connection, und Authentication aus der Verbindungskonfiguration weg.

Wählen Sie eine Microsoft Entra-Methode nur dann aus, wenn das Ziel sie unterstützt und Sie den Datenbankzugriff der Identität konfiguriert haben. Eine vom Treiber unterstützte Methode ist nicht zwangsläufig bei jeder SQL Server-Bereitstellung oder jedem verwalteten Dienst verfügbar. Für Einrichtung, hostspezifische verwaltete Identitätskennungen und Plattformbeschränkungen siehe Microsoft Entra ID mit dem ODBC-Treiber verwenden und integrierte Authentifizierung unter Linux und macOS verwenden.

Kombinieren Sie Trusted_Connection=yes nicht mit einem Authentication-Wert. Platzieren Sie kein Access Token in PWD. Wenn Sie die Authentifizierungsmethode eines DSN ändern, entfernen Sie inkompatible Zugangsdaten und Anwendungsattribute sowie ändern Sie das Schlüsselwort.

ActiveDirectoryPasswordverwendet Microsoft Entra-Benutzernamen und Passwörter und ist veraltet. Wähle es nicht für eine neue Anwendung. Bevorzugen Sie eine Methode, die für einen interaktiven Benutzer oder eine Workload-Identität geeignet ist.

Verschlüsselung und Zertifikatsvalidierung konfigurieren

Verwenden Sie Encrypt=yes;TrustServerCertificate=no mit entweder Treiber 17 oder Treiber 18 für eine Transport Layer Security (TLS)-Verbindung, die das Serverzertifikat validiert. Der Client muss der ausstellenden Zertifizierungsstelle vertrauen, und das Zertifikat muss mit dem erwarteten Servernamen übereinstimmen.

Configuration Wann wird es verwendet? Verhalten von Treiber 17 und Treiber 18
Encrypt=yes;TrustServerCertificate=no Verschlüsselung und normale Zertifikatsvalidierung erfordern Wird von beiden Hauptversionen unterstützt. Treiber 18 akzeptiert mandatory ebenfalls als Synonym für yes.
Encrypt=strict Tabular Data Stream (TDS) 8.0-Verschlüsselung für einen Endpunkt erforderlich machen, der sie unterstützt. Nur in Treiber 18. Der Treiber validiert das Zertifikat und ignoriert TrustServerCertificate. Driver 17 hat kein Äquivalent.
Encrypt=yes;TrustServerCertificate=yes Eine absichtlich genehmigte Ausnahme, die den Datenverkehr ohne gewöhnliche Zertifikatsvalidierung verschlüsselt. Verwenden Sie es nicht als routinemäßige Lösung für einen Zertifikatsfehler. Es stellt nicht sicher, dass der Client mit dem vorgesehenen Server spricht. Im Strict-Modus wird die Validierung nicht deaktiviert.
Encrypt=no Führen Sie eine Konfiguration aufrecht, die keine vollständige Sitzungsverschlüsselung durch den Client erfordert. Dies ist nicht der Standard für Remoteverbindungen. Treiber 18 akzeptiert optional ebenfalls. Der Server kann weiterhin Verschlüsselung benötigen.

Treiber 18 fordert standardmäßig Verschlüsselung an. Treiber 17 fordert ihn normalerweise standardmäßig nicht an, aber eine nicht leere Authentication Einstellung oder ein bereitgestelltes Zugriffstoken ändert die Verschlüsselungseinstellung von Treiber 17. Explizit festlegen Encrypt , anstatt sich auf authentifizierungsabhängige Standardwerte zu verlassen.

Für gewöhnliche nicht-Strict-Verbindungen mit Encrypt=no und TrustServerCertificate=noveranlasst eine Server-only-Verschlüsselungsanfrage Treiber 18 die Validierung des Zertifikats, wählt aber keine normale Zertifikatsvalidierung in Treiber 17 aus. Verlassen Sie sich nicht nur auf serverpflichtige Verschlüsselung, um in beiden Treibern dasselbe Validierungsverhalten zu erhalten. Für die vollständige Interaktion mit Servereinstellungen siehe die Tabellen zum Verschlüsselungsverhalten.

Wählen Sie die erwartete Zertifikatsidentität aus

Die meisten Anwendungen benötigen nur ein vertrauenswürdiges Zertifikat und den korrekten Server Namen. Verwenden Sie die zusätzlichen Zertifikatsschlüsselwörter für eine spezifische Bereitstellungsanforderung:

Keyword Wann wird es verwendet? Anwendbarkeit und Grenzen
HostnameInCertificate Die Bereitstellung erfordert einen erwarteten Zertifikats-Hostnamen, der sich von dem des Verbindungsendpunkts unterscheidet, etwa ein konfiguriertes Alias. Nur für Treiber 18. Es stellt kein Vertrauen in eine nicht vertrauenswürdige ausstellende Behörde her. Es wird ignoriert, wenn ServerCertificate verwendet wird.
ServerCertificate Verwenden Sie eine explizit verteilte Server-Zertifikatsdatei statt der üblichen Zertifikatsketten- und Hostnamenvalidierung. Treiber 18.1 und spätere Versionen, nur mit Encrypt=strict Verwenden Sie ein Privacy Enhanced Mail (PEM)-Zertifikat oder ein Distinguished Encoding Rules (DER)-Zertifikat. Das Zertifikat muss exakt übereinstimmen, und die Gültigkeitsdaten werden weiterhin überprüft. Planen Sie, wie ein Ersatz verteilt wird, bevor das Serverzertifikat rotiert.
ClientCertificate und ClientKey Verwenden Sie den spezialisierten Zertifikatsauthentifizierungsmechanismus für Loopback-Verbindungen zu SQL Server für Linux. Diese sind keine allgemeinen Ersatzlösungen für SQL- oder Microsoft Entra-Authentifizierung, und sie sind auch nicht die Server-Zertifikats-Vertrauenseinstellungen.

Beheben Sie Probleme mit Zertifikatsketten, Hostnamen und Zertifikatdatei, anstatt die Validierung zu deaktivieren. Unter Linux und macOS prüfen Sie außerdem die vom Treiber unterstützte OpenSSL-Abhängigkeit und den für diesen Prozess verwendeten Vertrauensspeicher. Weitere Informationen finden Sie unter Fehlerbehebung bei Verbindungsverschlüsselung.

Vertrauen in Zertifikate unter Linux und macOS

TLS unter Linux und macOS verwendet OpenSSL. Beschaffen Sie genehmigtes Vertrauensmaterial und befolgen Sie das Verfahren zur Verwaltung des Truststores Ihrer Plattform. Ein Zertifikat, das von einem nicht authentifizierten Endpunkt heruntergeladen wurde, reicht nicht aus, um ihm zu vertrauen. Überprüfen Sie die Systemanforderungen für die von Ihrem Treiber und Ihrer Plattform unterstützten Bibliotheken.

Das folgende historische Plattforminventar erfasst OpenSSL-Mindestversionen und Standard-Zertifikats-Trust-Store-Standorte. Es belegt keine aktuelle Treiberunterstützung für diese Plattformversionen. Bestätigen Sie die OpenSSL-Version und die Trust-Store-Konfiguration, die von Ihrem installierten Treiber und Ihrer Plattform verwendet werden, bevor Sie sich auf einen angegebenen Speicherort verlassen.

Platform Minimale OpenSSL-Version Standard-Speicherort des Zertifikat-Trust-Stores
Debian 10, 11, 12 1.1.1 /etc/ssl/certs
Debian 9 1.1.0 /etc/ssl/certs
Debian 8.71 1.0.1 /etc/ssl/certs
OS X 10.11, macOS 1.0.2 /usr/local/etc/openssl/certs
Red Hat Enterprise Linux 9 3.0.1 /etc/pki/tls/cert.pem
Red Hat Enterprise Linux 8 1.1.1 /etc/pki/tls/cert.pem
Red Hat Enterprise Linux 7 1.0.1 /etc/pki/tls/cert.pem
Red Hat Enterprise Linux 6 1.0.0-10 /etc/pki/tls/cert.pem
SUSE Linux Enterprise 15 1.1.0 /etc/ssl/certs
SUSE Linux Enterprise 11, 12 1.0.1 /etc/ssl/certs
Ubuntu 22.04, 23.04 3.0.2 /etc/ssl/certs
Ubuntu 20.04 1.1.1 /etc/ssl/certs
Ubuntu 18.04 1.1.0 /etc/ssl/certs
Ubuntu 16.04 1.0.2 /etc/ssl/certs
Ubuntu 14.04 1.0.1 /etc/ssl/certs
Alpine 3.17, 3.18 3.0.1 /etc/ssl/certs

Routing und Failover konfigurieren

Wählen Sie diese Einstellungen entsprechend der Zieltopologie und Workload aus. Sie erstellen keine Replikate, konfigurieren keinen Listener und gewähren keinen Zugriff auf eine Sekundärinstanz.

Setting Wann wird es verwendet? Wichtiger Unterschied
MultiSubnetFailover=Yes Verbinden Sie sich mit einem Availability Group Listener, einer Failover-Cluster-Instanz, Azure SQL-Datenbank, Azure SQL Managed Instance oder einer SQL-Datenbank in Microsoft Fabric. Der Treiber versucht, TCP-Verbindungen zu aufgelösten Adressen parallel herzustellen. Es funktioniert auch, wenn der Name in eine einzige Adresse aufgelöst wird. Es wird von Treiber 17 und Treiber 18 unterstützt. Kombinieren Sie es nicht mit der Datenbankspiegelung Failover_Partner.
ApplicationIntent=ReadOnly Fordern Sie eine Verbindung für eine schreibgeschützte Workload an, einschließlich schreibgeschützten Routings über einen entsprechend konfigurierten Availability Group-Listener. Geben Sie die teilnehmende Datenbank an und konfigurieren Sie das serverseitige Routing. Diese Einstellung ist kein Ersatz für schreibgeschützte Datenbankberechtigungen. Der Standardwert lautet ReadWrite.
TransparentNetworkIPResolution Beibehalten oder diagnostizieren Sie das Legacy-Fallback des Treibers über mehrere aufgelöste IP-Adressen. Werte sind Enabled und Disabled; der Standard ist Enabled. Behandle das nicht als eine weitere Schreibweise von MultiSubnetFailover.
IpAddressPreference Wählen Sie IPv4-First, IPv6-first oder Betriebssystem-Adressreihenfolge für eine Bereitstellung mit einer bestimmten Adressfamilie-Anforderung. Treiber 18.1 und neuere Versionen. Die Werte sind IPv4First, IPv6First, und UsePlatformDefault. Dadurch werden DNS-Einträge nicht verändert und das Netzwerk-Routing nicht repariert.
Failover_Partner Pflegen Sie eine bestehende SQL Server-Datenbankspiegelverbindung. Nur Windows. Es ist nicht die Option des Verfügbarkeitsgruppen-Listeners. Treiber 18.7 und spätere Versionen akzeptieren ebenfalls den Alias FailoverPartner; Treiber 17 verwendet Failover_Partner.

Für eine schreibgeschützte Verfügbarkeitsgruppenverbindung fügen ApplicationIntent=ReadOnly;MultiSubnetFailover=Yes Sie den entsprechenden authentifizierten Verbindungszeichenfolge hinzu und verwenden Sie den Listener in Server. Eine direkte Verbindung zu einem beliebigen sekundären Replikat konfiguriert das schreibgeschützte Routing nicht.

Nach einem Failover muss die Anwendung möglicherweise eine neue Verbindung öffnen. Für Servervoraussetzungen und Anwendungsverhalten siehe Hohe Verfügbarkeit und Notfallwiederherstellung.

Timeouts, Wiederherstellungs- und Wiederholungsverhalten festlegen

Wählen Sie eine Einstellung für die Operation aus, die Sie steuern möchten. Eine Login-Timeout, Abfrage-Timeout, eine Richtlinie zur Wiederherstellung der Idle-Connection und eine Richtlinie zur Wiederholung des Befehls gelten für verschiedene Operationen.

Requirement Setting Wann und wie man es benutzt
Verbindungsaufbau begrenzen. SQL_ATTR_LOGIN_TIMEOUT, oder ConnectTimeout mit Treiber 18.7 und neueren Versionen. In nativen Anwendungen legen Sie das Attribut vor der Verbindung fest. Treiber 17 und frühere Versionen von Treiber 18 erfordern das Attribut anstelle dieses Schlüsselworts. Ein explizit gesetztes Attribut hat Vorrang vor ConnectTimeout.
Begrenzen Sie die Ausführung der Anweisung. SQL_ATTR_QUERY_TIMEOUT Statement-Attribut. Konfigurieren Sie es über die API der Anwendung. ConnectTimeout setzt kein Abfrage-Timeout fest.
Stellen Sie eine geeignete Verbindung wieder her, die im Leerlauf abgebrochen ist. ConnectRetryCount und ConnectRetryInterval. Unterstützt durch die aktuellen Treiber-17- und Treiber-18-Versionen. Standardeinstellungen sind ein Wiederherstellungsversuch und 10 Sekunden zwischen den Versuchen. Ein Wert von 0 deaktiviert die Wiederherstellung. Diese Einstellungen wiederholen weder die ursprüngliche Verbindung der Anwendung noch führen sie ihre Befehle erneut aus.
Erkennen Sie eine inaktive TCP-Verbindung, die nicht mehr reagiert. KeepAlive und KeepAliveInterval. Nur für eine gemessene Netzwerkanforderung einstellen. Standardwerte sind 30 Sekunden und 1 Sekunde. Treiber 17.4 führte Konfigurationsunterstützung ein; Verbindungszeichenfolge-Unterstützung erfordert Treiber 17.8 und spätere Versionen, einschließlich Treiber 18. Frühere unterstützte Versionen verwenden DSN oder Treiberkonfiguration.
Führen Sie ausgewählte fehlgeschlagene Befehle erneut aus. RetryExec. Treiber 18.1 und neuere Versionen. Definieren Sie Regeln für bestimmte Fehler und Befehle erst nachdem entschieden wurde, ob eine Wiederholung des Vorgangs sicher ist. Das ist keine Wiederherstellung inaktiver Verbindungen.

Beispielsweise wählt ConnectRetryCount=3;ConnectRetryInterval=2 bis zu drei Leerlauf-Wiederherstellungsversuche mit einem Intervall von 2 Sekunden aus. Es sorgt nicht dafür, dass ein anfänglicher Login-Fehlschlag erfolgreich ist oder ein unterbrochenes Schreiben erneut versucht wird.

ConnectRetryCount akzeptiert 0 bis 255, und ConnectRetryInterval akzeptiert 1 bis 60 Sekunden. Mit Treiber 18.7 und neueren Versionen fordert ConnectTimeout=30 ein 30-sekündiges Anmeldezeitlimit an. Der Standard beträgt 15 Sekunden; 0 fordert eine unbefristete Wartezeit an. Vermeiden Sie eine unbegrenzte Anmeldewartezeit, wenn die Anwendung eine begrenzte Antwortzeit benötigt.

Implementieren Sie eine begrenzte Anwendungs-Wiederholungsrichtlinie für vorübergehende anfängliche Verbindungsfehler. Wiederholen Sie keine Versuche mit falschen Zugangsdaten, fehlenden Treiberregistrierungen oder Zertifikatsvalidierungsfehlern, und behandeln Sie diese nicht als vorübergehende Ausfälle. Für Befehlsversuche sollten Sie berücksichtigen, ob der Server möglicherweise bereits einen Schreibprozess abgeschlossen hat, bevor die Verbindung fehlschlug.

Für Wiederherstellungsvoraussetzungen und Fehlerbehandlung siehe Connection resiliency. Zur Regelsyntax siehe RetryExec. Halten Sie die Verbindungs- und Abfrage-Timeout-Optionen im Einklang mit der Gesamtverzögerung, die Ihre Anwendung akzeptieren kann.

Linux- und macOS-Keep-alive-Konfiguration

KeepAlive steuert, wie oft TCP ein Paket sendet, um eine inaktive Verbindung zu überprüfen. KeepAliveInterval steuert das Intervall zwischen den Neuübertragungen, wenn keine Antwort eingeht. Ihre Standardwerte sind 30 Sekunden bzw. 1 Sekunde.

Mit Treiber 17.4 und neueren Versionen können Sie diese Werte im Treiberabschnitt von odbcinst.ini oder im DSN-Abschnitt von odbc.ini konfigurieren. Mit einer DSN-Verbindung haben die Einstellungen des DSN Vorrang vor den Treibereinstellungen. Ohne DSN verwendet der Treiber den ihm zugeordneten Abschnitt in odbcinst.ini. Wenn keine der Speicherorte einen Wert angibt, verwendet der Treiber den Standardwert.

Treiber 17.8 und spätere Versionen, einschließlich Treiber 18, akzeptieren ebenfalls KeepAlive und KeepAliveInterval in der Verbindungszeichenfolge. Ersetzen Sie ein bestehendes Schlüsselwort statt eines Duplikats anzufügen und überprüfen Sie den Konfigurationsvorrang beim Kombinieren von Verbindungszeiteinstellungen mit einem DSN.

Anwendungs- und Datenverhalten konfigurieren

Verwenden Sie diese Optionen, wenn die Anwendung dieses Verhalten benötigt, anstatt sie zu jeder Verbindungszeichenfolge hinzuzufügen.

Setting Wann wird es verwendet? Verhalten und Grenzwerte
APP Identifizieren Sie die Anwendung in serverseitigen Sitzungsinformationen. Verwenden Sie einen stabilen Anwendungsnamen. Es handelt sich weder um eine authentifizierte Identität noch um eine Zugriffskontrolle.
WSID Geben Sie eine Arbeitsstationskennung an, wenn Sie eine für die Sitzungsidentifikation benötigen. Treiber 18.7 und spätere Versionen akzeptieren WorkstationIDebenfalls . Treiber 17 verwendet WSID. Verwenden Sie keinen vom Kunden angegebenen Namen als Nachweis für die Identität des Anrufers.
MARS_Connection=Yes Die Anwendung benötigt mehrere aktive Ergebnissätze (MARS) auf einer einzigen Verbindung. Der Standardwert lautet No. Treiber 18.7 und spätere Versionen akzeptieren MultipleActiveResultSets=Yesebenfalls . Treiber 17 verwendet MARS_Connection.
LongAsMax=Yes Senden Sie lange Zeichen- oder Binärparameter als varchar(max), nvarchar(max) oder varbinary(max) anstelle von Legacy-Large-Object-Typen. Nur Treiber 18; die Standardeinstellung ist No. Überprüfen Sie die Parameter- und Schema-Erwartungen der Anwendung, bevor Sie sie ändern.
GetDataExtensions=Yes Eine Anwendung pflegen, die Spaltendaten mit SQLGetData in abweichender Reihenfolge abrufen muss. Nur für Treiber 18. Dieses Kompatibilitätsverhalten kann den Speicherverbrauch erhöhen und die Leistung verringern. Bevorzugen Sie das Abrufen von Spalten in aufsteigender Reihenfolge in neuen Anwendungen.
Language Wählen Sie die Server-Nachrichtensprache der Sitzung aus. Verwenden Sie eine auf dem Server installierte Sprache. Es wählt die Kodierung des Quellcodes der Anwendung nicht aus.
AutoTranslate Steuerung der Übersetzung zwischen Client- und Server-Codepages für Nicht-Unicode-Zeichendaten. Der Standardwert lautet Yes. Testen Sie mit den tatsächlichen Zeichendaten der Anwendung, bevor Sie diese ändern; Das Deaktivieren der Übersetzung kann die Interpretation der Zeichen verändern.
Regional Pflegen Sie eine Anwendung, die beim Umwandeln von Währungs-, Datums- oder Uhrzeitdaten in Zeichendaten eine regionale Formatierung des Clients erwartet. Der Standardwert lautet No. Gehen Sie nicht davon aus, dass eine Änderung der Ausgabeformatierung diese regionalen Zeichenketten zu gültigen Eingabeparametern macht.
AnsiNPW Beibehalten Sie das Sitzungsverhalten für Null-Behandlung, Zeichenauffüllung und Warnungen. Der Standardwert lautet Yes. Überprüfen Sie die entsprechenden Transact-SQL (T-SQL)-Sitzungsoptionen und das Serverversionsverhalten, bevor Sie diese ändern.
QuotedId Steuern, ob die Sitzung doppelte Anführungszeichen für Identifikatoren verwendet. Der Standardwert lautet Yes. Ändern Sie ihn nur, wenn das T-SQL der Anwendung ein anderes QUOTED_IDENTIFIER Verhalten erfordert.
ConcatNullYieldsNull Null-Konkatenationsverhalten steuern, wenn der Server diese Sitzungsoption unterstützt. Treiber 18.6 und spätere Versionen. Driver 17 erkennt dieses Schlüsselwort nicht.
UseFMTONLY Behalten Sie einen Metadatenermittlungspfad bei, der SET FMTONLY anstelle der üblichen Metadatenerkennung des Treibers erfordert. Der Standardwert lautet No. Für eine gewöhnliche Verbindung ist das nicht notwendig.

Konfigurieren Sie das Verbindungspooling über den Treibermanager oder die ODBC-Umgebung der Anwendung. Kopieren Sie nicht das Pooling Schlüsselwort eines anderen Anbieters in die Verbindungszeichenfolge dieses Treibers. Für die native ODBC-Konfiguration siehe Driver Manager Connection Pooling. Für Windows-spezifisches Wiederverwendungsverhalten siehe treiberabhängiges Verbindungspooling.

Spezialisierte Funktionen konfigurieren

Die folgenden Optionen erfordern eine funktionsspezifische Einrichtung über die Verbindungszeichenfolge hinaus.

Settings Wann man sie einsetzen sollte Was sonst noch benötigt wird
ColumnEncryption=Enabled Lesen oder schreiben Sie Spalten, die mit Always Encrypted geschützt sind. Zugriff auf die Spaltenverschlüsselungsschlüssel über einen unterstützten Schlüsselspeicher. Always Encrypted schützt Spaltenwerte und ist von der Netzwerkverschlüsselung getrennt. Für Enclave-Verbindungen verwenden Sie die funktionsspezifischen Verbindungseinstellungen.
KeystoreAuthentication, KeystorePrincipalId und KeystoreSecret Authentifizieren Sie den Treiber bei einem Schlüsselspeicher, der für Always Encrypted verwendet wird. Identität und Berechtigungen des Schlüsselspeichers. Diese Zugangsdaten sind nicht die Anmeldedaten der Datenbank. Schützen Sie Geheimnisse im Schlüsselspeicher so, wie Sie ein Passwort schützen würden.
ServerSPN Geben Sie einen Service Principal Name (SPN) für eine Kerberos-Bereitstellung an, die einen expliziten Wert benötigt. Die aktuellen Versionen von Treiber 17 und Treiber 18 unterstützen diese Einstellung unter Windows, Linux und macOS. Konfigurieren Sie die Registrierung des Kerberos-Dienstes so, dass sie mit dem bereitgestellten SPN übereinstimmt. Ein SPN ist kein TLS-Zertifikats-Hostname.
FailoverPartnerSPN Pflegen Sie ein explizites Kerberos-SPN für einen Datenbankspiegelpartner. Nur unter Windows, mit der entsprechenden Spiegelkonfiguration.
AttachDBFileName Verwenden Sie einen SQL Server-Workflow, der eine Datenbankdatei anhängt. Der übereinstimmende Name Database, die serverzugängliche Datei und die erforderlichen Berechtigungen. Verwenden Sie es nicht, um eine bestehende Datenbank in der Azure SQL-Datenbank zu identifizieren.
Replication=Yes Verwenden Sie eine Verbindung, die absichtlich Replikationsagenten-Verhalten benötigt. Treiber 17.8 und spätere Versionen, einschließlich Treiber 18. Es ändert das Verhalten von Objekten, die mit , NOT FOR REPLICATIONgekennzeichnet sind, einschließlich Trigger; es ist keine allgemeine Performance-Option.
QueryLog_On, QueryLogFile, QueryLogTime, StatsLog_On, und StatsLogFile Diagnostizieren Sie eine bestehende Windows-Anwendung über Treiberabfragen oder Leistungsprotokolle. Nur unter Windows; diese Verbindungseinstellungen erfordern ein DSN. Setzen Sie den Schwellenwert für langsame Abfragen mit QueryLogTime in Millisekunden fest. Verwenden Sie ein kontrolliertes Logging-Ziel, entsprechende Berechtigungen und eine Aufbewahrungsrichtlinie. Behandeln Sie Diagnoseprotokolle nicht als frei von sensiblen Daten.

Für Setup und Limits siehe Always Encrypted, Kerberos SPNs und die Keyword-Referenz. Einige native Funktionen, wie die Enlist verteilter Transaktionen, erfordern API-Attribute statt eines Schlüsselworts einer Verbindungszeichenfolge.

Erstellen eines DSN

Erstellen Sie eine DSN nur, wenn Sie eine DSN-basierte Verbindung wählen. Ein DSN speichert die Konfiguration; das Speichern gewährleistet nicht, dass die Anwendung sich authentifizieren oder eine Abfrage ausführen kann.

Windows-Benutzer-DSN

Das folgende Verfahren erstellt eine Benutzer-DSN für das SQL-Authentifizierungsbeispiel. Wählen Sie für einen Dienst bewusst System-DSN und ordnen Sie den Zugriff unter der Service-Identität an.

  1. Öffnen Sie den ODBC Data Source Administrator, der zur Architektur Ihrer Anwendung passt.

  2. Wählen Sie bei Benutzer-DSNHinzufügen aus.

  3. Wählen Sie ODBC Driver 18 für SQL Server oder ODBC Driver 17 für SQL Server. Wählen Sie Fertigstellen, um den Treiberassistenten zu öffnen.

  4. Nennen Sie das DSN MSSQLTest. Geben Sie tcp:<server>,1433 als Server ein und wählen Sie Weiter.

  5. Wählen Sie SQL-Authentifizierung aus. Löschen Sie Login-ID und Passwort und wählen Sie Weiter.

  6. Aktivieren Sie Standarddatenbank ändern in. Geben Sie <database> ein, ohne die Datenbankliste zu öffnen, und wählen Sie Weiter.

  7. Wählen Sie für Treiber 18 die Verbindungsverschlüsselung Obligatorisch aus. Wählen Sie für Treiber 17 " Starke Verschlüsselung für Daten verwenden". Lassen Sie Serverzertifikat vertrauen nicht ausgewählt.

  8. Wählen Sie Fertig stellen aus und überprüfen Sie die Konfigurationsübersicht.

  9. Wählen Sie OK, um das DSN zu speichern, ohne den Verbindungstest des Assistenten auszuführen. Bestätigen Sie, dass MSSQLTest auf Benutzer-DSN angezeigt wird.

Die Anwendung stellt die SQL-Anmeldedaten zur Verbindungszeit bereit. Für weitere Authentifizierungsmethoden und Assistentenfelder siehe ODBC Data Source Administrator DSN-Optionen.

Linux- oder macOS-Benutzer-DSN

Führen Sie odbcinst -j aus, um die Pfade für USER DATA SOURCES und SYSTEM DATA SOURCES für Ihre unixODBC-Installation zu finden. Fügen Sie der Benutzerdatei folgenden Abschnitt hinzu und ersetzen Sie die Server- und Datenbankplatzhalter:

[MSSQLTest]
Driver = ODBC Driver 18 for SQL Server
Server = tcp:<server>,1433
Database = <database>
Authentication = SqlPassword
Encrypt = yes
TrustServerCertificate = no

Ändern Sie für Treiber 17 den Treibernamen. Speichern Sie PWD nicht in dieser Datei. Die Treiberregistrierung in odbcinst.ini und die DSN odbc.ini erfüllen unterschiedliche Zwecke: Die eine lokalisiert die Treiberbibliothek, die andere nennt Verbindungseinstellungen.

Fügen Sie für eine System-DSN dieselben Einstellungen mit Administratorrechten zur angegebenen SYSTEM DATA SOURCES-Datei hinzu. Für einen Dienst richten Sie den Zugriff unter der Service-Identität ein.

Der Driver Wert kann der Name des registrierten Treibers oder der Pfad zur in der Installationsvorlage angegebenen Treiberbibliothek sein. In odbc.ini, verwenden Sie den registrierten Namen ohne Klammern für Verbindungszeichenketten. Geben Sie den Serverport in Server; Port ist kein gültiges DSN-Schlüsselwort für diesen Treiber unter Linux oder macOS.

Alternativ können Sie den DSN-Abschnitt in einer Vorlagendatei speichern und eine Benutzer-DSN mit folgendem Befehl registrieren:

odbcinst -i -s -h -f <template_file>

Ersetzen Sie <template_file> durch den Pfad der Vorlage. Details zur .ini Datei und Registrierung finden Sie in der unixODBC-Dokumentation. Testen Sie die Verbindung über die Anwendung, die das DSN verwendet; Registrierung allein stellt keine Datenbankverbindung her.

Datei-DSN

Verwenden Sie, FileDSN=<file_path> wenn die Anwendung eine Dateidatenquelle erwartet. Der Client benötigt weiterhin einen installierten Treiber, der die Einstellungen interpretieren kann. Bewahren Sie Ihre Zugangsdaten außerhalb der Datei auf.

SaveFile fordert, dass Verbindungseinstellungen nach erfolgreicher Verbindung in einer Datei gespeichert werden. Verwenden Sie es nur, wenn die Anwendung absichtlich eine Datei-DSN erstellt. Für Dateiinhalte und Zusammenführungsregeln siehe die SQLDriverConnect-Referenz.

Konfigurationsvorrang verstehen

Eine Anwendung kann Einstellungen aus einer DSN, deren Verbindungszeichenfolge und API-Attributen beziehen. Überprüfen Sie alle drei, wenn die effektive Verbindung von der von Ihnen erwarteten Zeichenfolge abweicht.

Quelle oder Syntax Rule
Schreibweise von Schlüsselwörtern Der Treiber passt zu Schlüsselwortnamen ohne Beachtung der Groß-/Kleinschreibung. Akzeptierte Werte sind schlüsselwortspezifisch; gehen Sie nicht davon aus, dass jede boolesche Option true und falseakzeptiert.
Wiederholtes Schlüsselwort Beim Parsen von Treiberoptionen behalten Treiber 17 und Treiber 18 das erste Vorkommen eines erkannten Schlüsselworts. Aliasen für dieselbe Option bieten keine separate Übersteuerung. Diese Regel regelt nicht die frühere Treiber- oder DSN-Auswahl des Treibermanagers: unixODBC verwendet das letzte Vorkommen eines wiederholten Driver Werts DSN in diesem Stadium. Ersetzen Sie bestehende Werte, anstatt doppelte Werte anzuhängen, und geben Sie das Auswahl-Schlüsselwort nur einmal an.
connection string versus DSN Explizite Verbindungszeichenfolge-Werte überschreiben normalerweise entsprechende DSN-Felder. Die RegPrecedence DSN-Einstellung des Treibers kann diese Rangfolge umkehren. Überprüfen Sie es, wenn sich ein bestehendes DSN unerwartet verhält.
API-Attribute Von der Anwendung festgelegte Attribute können die effektive Konfiguration ändern. Überprüfen Sie die Spezifikation des jeweiligen Attributs, anstatt davon auszugehen, dass jedes Attribut dieselbe Zusammenführungsregel verwendet.
Werte in geschweiften Klammern Schließen Sie einen Wert mit einem Semikolon in geschweifte Klammern ein und verdoppeln Sie eine schließende geschweifte Klammer innerhalb des Werts. Zum Beispiel Database={database;name} gibt es einen Datenbanknamen an. Shell- oder Programmiersprach-Quoting ist vom ODBC-Escaping getrennt.

Halten Sie die Authentifizierungs- und Sicherheitseinstellungen über DSN und Anwendung hinweg einheitlich. Wenn Sie die Treiber ändern, aktualisieren Sie den ausgewählten Treiber des DSN oder den DSN-losen Driver-Wert nach Bedarf entsprechend. Für Migrationsprüfungen siehe Wesentliche Versionsunterschiede.

Überprüfen Sie die Verbindung in Ihrer Anwendung

Testen Sie unter der tatsächlichen Betriebssystemidentität und Bereitstellungskonfiguration der Anwendung. Ein erfolgreicher DSN-Assistententest beweist nicht, dass ein Dienst dieselbe DSN sehen oder dieselben Anmeldedaten verwenden kann.

  1. Verbinden Sie sich mit der gewählten DSN- oder DSN-freien Zeichenfolge und der vorgesehenen Authentifizierungsmethode.
  2. Nachdem die Verbindung erfolgreich ist, bestätigen Sie, welchen Treiber und welche Version die Anwendung lädt. Verwenden SQLGetInfo Sie im nativen Code mit SQL_DRIVER_NAME und SQL_DRIVER_VER.
  3. Führen Sie eine Abfrage in der vorgesehenen Datenbank aus und überprüfen Sie ihr Ergebnis. Ein vollständiges Anwendungsbeispiel finden Sie unter Verbinden mit einer Datenbank und Abfragen mit C++.
  4. Überprüfen Sie die Verschlüsselung und das erforderliche Verhalten der Anwendung, wie z. B. schreibgeschütztes Routing oder Wiederherstellung. Testen Sie jede von Ihnen bereitgestellte Verbindungsart unabhängig voneinander.
  5. Fehler erfassen, ohne Zugangsdaten freizugeben. Für SQLSTATE-Werte, native Fehlercodes und geschützte Diagnosesammlung siehe ODBC-Diagnostik.

Wenn eine Verbindung fehlschlägt, überprüfen Sie die Treiberregistrierung und die DSN-Sichtbarkeit, bevor Sie die Authentifizierung ändern. Überprüfen Sie den Endpunkt und die Erreichbarkeit, bevor Sie die Wiederholungseinstellungen ändern. Bei einem Zertifikatsfehler beheben Sie die Vertrauens- oder Namenskonfiguration, anstatt TrustServerCertificate=yes festzulegen, damit der Fehler verschwindet.