Microsoft ODBC-Treiber für SQL Server

ODBC-Treiber herunterladen

ODBC ist die primäre native Datenzugriffs-API für in C und C++ geschriebene Anwendungen für SQL Server. Der Microsoft ODBC Driver für SQL Server verbindet sich mit SQL Server, Azure SQL-Datenbank, Azure SQL Managed Instance, Azure Synapse Analytics und SQL Database in Microsoft Fabric. Für die Datenbankversionen, die jede Treiberversion unterstützt, siehe SQL-Versionskompatibilität.

Andere Programmiersprachen, die ODBC verwenden können, sind u.a. COBOL, Perl, PHP und Python. ODBC wird häufig in Datenintegrationsszenarien eingesetzt, und die Microsoft-Treiber für PHP für SQL Server basieren auf diesem Treiber.

Die sqlcmd- und bcp-Dienstprogramme funktionieren mit diesem Treiber, werden aber separat installiert: das mssql-tools18 Paket unter Linux und macOS sowie die Microsoft Command Line Utilities unter Windows. Verwenden Sie sqlcmd , um Transact-SQL (T-SQL)-Anweisungen, Systemprozeduren und Skriptdateien auszuführen. Verwenden Sie BCP, um Daten in Bulk zwischen einer SQL Server-Instanz und einer Datendatei in beide Richtungen zu kopieren.

Auswählen des Startpunkts

• Um den Treiber zu installieren, gehe zu Systemanforderungen, Installation und Treiberdateien für Windows, oder installiere den ODBC-Treiber unter Linux, installiere den ODBC-Treiber auf macOS und installiere den unixODBC-Treibermanager.
• Um Ihre erste Anwendung zu schreiben, gehen Sie zu Connect to und fragen Sie eine Datenbank mit C++,DSN und Verbindungszeichenfolge-Schlüsselwörtern und Attributen ab.
• Um sich mit passwortloser Authentifizierung mit Azure SQL zu verbinden, gehe zu Use Microsoft Entra ID with the ODBC driver.
• Um eine bestehende App widerstandsfähig gegen vorübergehende Ausfälle zu machen, gehen Sie zu Connection Resiliency and High Availability and Disaster Recovery.
• Um von Version 17 aufzusteigen, gehe zu Major Version differences und Connection Encryption Troubleshooting.
• Um ein Verbindungs- oder Abfrageproblem zu diagnostizieren, gehe zu Fehlerbehebung der Verbindungsverschlüsselung und Bekannte Probleme (Linux und macOS).

Produktionsbasisplan für Azure SQL

Verwenden Sie diesen Codeausschnitt als Ausgangspunkt für eine produktionsorientierte Azure SQL Verbindung. Er lädt den Servernamen und den Datenbanknamen aus der Anwendungskonfiguration, authentifiziert sich mit einer verwalteten Identität, sodass kein Geheimnis in der Verbindungszeichenfolge erscheint, und aktiviert die Verschlüsselung von Tabular Data Stream (TDS) 8.0 mit vollständiger Zertifikatsvalidierung. Es setzt eine Anmeldezeit pro Versuch und versucht vorübergehende Fehler mit exponentiellem Backoff und Jitter erneut.

Der C++-Ausschnitt in diesem Artikel lässt Handle-Allokation und den Logging-Helfer der Kürze halber weg.

std::wstring BuildConnectionString(const wchar_t* server, const wchar_t* database) {
    std::wstring cs = L"Driver={ODBC Driver 18 for SQL Server}";
    cs += L";Server=tcp:"; cs += server; cs += L",1433";
    cs += L";Database="; cs += database;
    cs += L";Authentication=ActiveDirectoryMsi";   // managed identity, no stored secret
    cs += L";Encrypt=strict";                      // TDS 8.0 with certificate validation
    cs += L";ConnectRetryCount=3";                 // idle connection resiliency, not initial connect
    cs += L";ConnectRetryInterval=10";
    return cs;
}

// Transient fault codes documented for Azure SQL, plus the resource governance
// codes. Network termination and timeout errors (64, 233, 258, 10053, 10054,
// 10060) are retried a bounded number of times, which is the documented
// guidance for them. 258 is the code the driver reports for a connect timeout.
// 10053 and 10054 can also mean the encryption handshake failed rather than a
// plain network reset, so read the error text before assuming a network fault.
bool IsTransient(SQLINTEGER nativeError) {
    switch (nativeError) {
        case 615: case 926: case 4060: case 4221:
        case 10928: case 10929: case 10936:
        case 40197: case 40501: case 40613:
        case 42108: case 42109:
        case 49918: case 49919: case 49920:
        case 40020: case 40143: case 40166: case 40540:   // failover subcodes
        case 64: case 233: case 258:
        case 10053: case 10054: case 10060:
            return true;
        default:
            return false;
    }
}

// Retries only errors that a new connection can clear, with exponential backoff
// plus jitter so that concurrent clients don't retry in lockstep.
SQLRETURN ConnectWithRetry(SQLHDBC hDbc, const std::wstring& connectionString, int maxAttempts) {
    SQLRETURN rc = SQL_ERROR;
    for (int attempt = 1; attempt <= maxAttempts; ++attempt) {
        // Set the per-attempt connect timeout through the connection attribute.
        // This works on every driver version, so the sample doesn't depend on
        // which connection string keywords a given release accepts.
        SQLSetConnectAttrW(hDbc, SQL_ATTR_LOGIN_TIMEOUT,
                           reinterpret_cast<SQLPOINTER>(static_cast<SQLLEN>(30)), 0);

        rc = SQLDriverConnectW(hDbc, nullptr,
                               const_cast<SQLWCHAR*>(reinterpret_cast<const SQLWCHAR*>(connectionString.c_str())),
                               SQL_NTS, nullptr, 0, nullptr, SQL_DRIVER_NOPROMPT);
        if (SQL_SUCCEEDED(rc)) {
            Log("INFO", "connected on attempt %d/%d", attempt, maxAttempts);
            return rc;
        }

        // Walks the diagnostic records and returns the first record that carries
        // a real SQL Server error number. Microsoft Entra failures report several
        // driver-specific records first, whose native error is 0.
        SQLINTEGER native = LogDiagnostics(SQL_HANDLE_DBC, hDbc, "connect");
        if (attempt == maxAttempts || !IsTransient(native)) return rc;

        // Cap the backoff at 64 seconds. This also keeps the shift in range
        // when a caller passes a large maxAttempts.
        int shift = (attempt - 1 < 6) ? attempt - 1 : 6;
        DWORD delayMs = (1UL << shift) * 1000UL + (DWORD)(GetTickCount64() % 500);
        Log("WARN", "retrying in %lu ms (attempt %d/%d)", delayMs, attempt + 1, maxAttempts);
        Sleep(delayMs);
    }
    return rc;
}

ConnectRetryCount und ConnectRetryInterval aktiviert die Widerstandsfähigkeit der Idle-Verbindungen, die transparent eine Verbindung wiederherstellt, die im Leerlauf abgebrochen wurde. Sie versuchen den initialen Connect nicht erneut, weshalb dieser Ausschnitt auch Anwendungs-Wiederholung implementiert. Behalte beides.

ODBC meldet Diagnosen über den Rückgabecode und nicht nur über SQLGetDiagRec den Rückgabecode, also klassifiziere Fehler vor einem erneuten Versuch. Ein Authentifizierungs- oder Konfigurationsfehler schlägt dann sofort fehl, anstatt das gesamte Wiederversuchsbudget zu verbrauchen.

Weitere Informationen zu den einzelnen Teilen dieser Konfiguration finden Sie unter:

• Schlüsselwörter und Attribute der DSN- und Verbindungszeichenfolge
• Verwenden Sie Microsoft Entra ID mit dem ODBC-Treiber
• Fehlerbehebung der Verbindungsverschlüsselung
• Verbindungsresilienz
• Hohe Verfügbarkeit und Notfallwiederherstellung

Für den Katalog der Azure SQL Transient Errors siehe Transient Fault Error Codes.

Wichtigste Funktionen

• Cross-Platform: Die gleiche API unter Windows, Linux und macOS.
• Microsoft Entra ID-Authentifizierung: Passwortlose Verbindungen mit verwalteter Identität, Service Principal, interaktiven und integrierten Flows.
• Strenge Verschlüsselung: TDS-8.0-Verbindungen mit vollständiger Zertifikatsvalidierung in Version 18 und späteren Versionen.
• Immer verschlüsselt: Client-seitige Verschlüsselung für sensible Spalten, mit Unterstützung für benutzerdefinierte Keystore-Anbieter.
• Verbindungsresilienz: Transparente Wiederherstellung einer Verbindung, die im Leerlauf abgebrochen ist.
• Hohe Verfügbarkeit: Unterstützung der Verfügbarkeitsgruppe für Zuhörergruppen mit MultiSubnetFailover.
• Datenklassifikation: Sensitivitätsmetadaten für klassifizierte Spalten.
• Vektordatentyp: Native Unterstützung für den Vektortyp .
• Verteilte Transaktionen: XA-Transaktionsunterstützung über den Microsoft Distributed Transaction Coordinator (MSDTC).
• Begleitwerkzeuge: sqlcmd und bcp, separat installiert.

Erste Schritte

Installieren des Treibers

Konfigurieren und Verbinden

Authentifizieren und sichern

Hohe Verfügbarkeit und Resilienz

Mit Daten arbeiten

Diagnostizieren und Problembehandlung

Release Notes und Fehlerbehebungen

Reference

Verwandte Inhalte

• ODBC Programmer's Reference: Die ODBC API-Spezifikation, die dieser Treiber implementiert, separat vom Treiber dokumentiert.
• Funktionen des SQL Server Native Client: Treiberverhalten wird nur im Inhalt des nativen Clients dokumentiert. Diese Artikel beziehen sich auf den ODBC-Treiber für SQL Server, außer dort, wo sie OLE DB beschreiben.
• BCP-Utility: Das Bulk-Copy-Tool, das separat vom Treiber installiert wird.
• sqlcmd-Utility: Das Kommandozeilen-Abfragetool, das separat vom Treiber installiert wird.
• Treiber-Feature-Unterstützungsmatrix
• Blog zu SQL Server-Treibern