Microsoft ODBC-Treiber für SQL Server

ODBC-Treiber herunterladen

ODBC ist eine native Datenzugriffs-Anwendungsprogrammierschnittstelle (API) für Anwendungen, die in C und C++ geschrieben sind. 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.

Deine Anwendung ruft den ODBC-Treibermanager auf, der den Treiber lädt und ODBC-Aufrufe an ihn weiterleitet. Verwenden Sie den Windows ODBC Driver Manager unter Windows und unixODBC unter Linux und macOS.

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 ODBC-Variante von sqlcmd und das bcp-Dienstprogramm verwenden diesen Treiber, installieren sich jedoch separat: das mssql-tools18 Paket unter Linux und macOS sowie die Microsoft Command Line Utilities unter Windows. Die Go-Variante von sqlcmd verwendet diesen Treiber nicht. 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++ ab. Für Optionen für Datenquellennamen (DSN) und Verbindungszeichenfolge verwenden Sie DSN- und Verbindungszeichenfolge-Schlüsselwörter und -attribute. Wenn Ihr Compiler die Header nicht findet oder der Build keine Verbindung herstellt, gehen Sie zu C- und C++-Anwendungen mit dem ODBC-Treiber entwickeln.
• Um mit Azure SQL mithilfe der kennwortlosen Authentifizierung eine Verbindung herzustellen, wechseln Sie zu Microsoft Entra ID mit dem ODBC-Treiber verwenden.
• Um eine bestehende App robust gegenüber vorübergehenden Fehlern zu machen, gehen Sie zu Verbindungsresilienz und Hochverfügbarkeit und Notfallwiederherstellung.
• Um von Version 17 zu aktualisieren, gehen Sie zu Unterschiede zwischen Hauptversionen und Fehlerbehebung bei der Verbindungsverschlüsselung.
• Um ein Verbindungs- oder Abfrageproblem zu diagnostizieren, gehe zu Fehlerbehebung der Verbindungsverschlüsselung und Bekannte Probleme (Linux und macOS).

Produktionsbasisplan für Azure SQL

Nutzen Sie dieses vollständige C++17-Programm als Ausgangspunkt für eine von Azure gehostete Anwendung. Es verbindet, läuft SELECT 1, prüft das Ergebnis und gibt die ODBC-Handles frei. Installiere Driver 18 und die ODBC-Entwicklungsdateien der Plattform, bevor du es baust. Für Voraussetzungen siehe Develop C und C++ applications with the ODBC driver.

Setze ODBC_CONNECTION_STRING in der Anwendungsumgebung deinen kompletten Verbindungszeichenfolge. Das folgende Beispiel verwendet eine systemzugeordnete verwaltete Identität. Der Host muss diese Identität aktiviert haben, und die Datenbank muss ihm Zugriff gewähren. Für Host-Anforderungen, benutzerzugewiesene Identitäten und lokale Entwicklungsauthentifizierung siehe Use Microsoft Entra ID with the ODBC Driver.

Driver={ODBC Driver 18 for SQL Server};Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=ActiveDirectoryMsi;Encrypt=strict;ConnectRetryCount=3;ConnectRetryInterval=2;

Encrypt=strict benötigt einen Endpunkt, der Tabular Data Stream (TDS) 8.0 unterstützt. Verwenden Sie andernfalls Encrypt=yes;TrustServerCertificate=no. Konfigurieren Sie ein Zertifikat, dem der Client vertraut und dessen Name mit dem Server übereinstimmt. Für Einrichtung und Verifizierung siehe Fehlerbehebung der Verbindungsverschlüsselung.

Halte Zugangsdaten aus Quelldateien und Shell-Historie heraus. Für Befehle zur Einstellung der Umgebungsvariable siehe Verbindung konfigurieren. Unter Linux und macOS liefert ihr den Wert als UTF-8. Speichere das folgende Programm als odbc-baseline.cpp:

#ifdef _WIN32
#include <windows.h>
#else
#include <iconv.h>
#endif
#include <sql.h>
#include <sqlext.h>

#include <chrono>
#include <cstdint>
#include <cstdlib>
#include <cstring>
#include <iostream>
#include <random>
#include <stdexcept>
#include <string>
#include <thread>
#include <vector>

struct Handles {
    SQLHENV env = SQL_NULL_HENV;
    SQLHDBC dbc = SQL_NULL_HDBC;
    SQLHSTMT stmt = SQL_NULL_HSTMT;
    bool connected = false;

    ~Handles() {
        if (stmt) SQLFreeHandle(SQL_HANDLE_STMT, stmt);
        if (connected) SQLDisconnect(dbc);
        if (dbc) SQLFreeHandle(SQL_HANDLE_DBC, dbc);
        if (env) SQLFreeHandle(SQL_HANDLE_ENV, env);
    }
};

bool logDiagnostics(SQLSMALLINT type, SQLHANDLE handle) {
    bool retry = false;
    bool permanent = false;
    for (SQLSMALLINT record = 1; ; ++record) {
        SQLWCHAR state[6] = {};
        SQLWCHAR message[1024] = {};
        SQLINTEGER native = 0;
        SQLRETURN rc = SQLGetDiagRecW(type, handle, record, state, &native,
                                     message, 1024, nullptr);
        if (rc == SQL_NO_DATA) break;
        if (!SQL_SUCCEEDED(rc)) {
            std::cerr << "event=diagnostics_failed rc=" << rc << '\n';
            return false;
        }
        std::string sqlstate;
        for (int i = 0; i < 5; ++i) {
            sqlstate += static_cast<char>(state[i]);
        }
        std::cerr << "event=odbc_diagnostic sqlstate=" << sqlstate
                  << " native_error=" << native << '\n';
        permanent |= sqlstate.substr(0, 2) == "28" ||
                     sqlstate.substr(0, 2) == "IM" ||
                     sqlstate == "HY024" || sqlstate == "HY092";
        retry |= sqlstate == "08S01" || sqlstate == "HYT00" ||
                 sqlstate == "HYT01";
        switch (native) {
            case 10928: case 10929: case 10936:
            case 40197: case 40501: case 40613:
            case 49918: case 49919: case 49920:
                retry = true;
        }
    }
    return retry && !permanent;
}

void requireSuccess(SQLRETURN rc, SQLSMALLINT type, SQLHANDLE handle,
                    const char* operation) {
    if (rc == SQL_SUCCESS) return;
    logDiagnostics(type, handle);
    if (!SQL_SUCCEEDED(rc)) throw std::runtime_error(operation);
}

std::vector<SQLWCHAR> readConnectionString() {
    static_assert(sizeof(SQLWCHAR) == 2, "Use a driver manager with 16-bit SQLWCHAR");
#ifdef _WIN32
    size_t length = 0;
    if (_wgetenv_s(&length, nullptr, 0, L"ODBC_CONNECTION_STRING") != 0 ||
        length == 0) {
        throw std::runtime_error("ODBC_CONNECTION_STRING is required");
    }
    std::vector<wchar_t> raw(length);
    if (_wgetenv_s(&length, raw.data(), raw.size(), L"ODBC_CONNECTION_STRING") != 0) {
        throw std::runtime_error("Cannot read ODBC_CONNECTION_STRING");
    }
    std::vector<SQLWCHAR> result(raw.begin(), raw.end() - 1);
#else
    const char* raw = std::getenv("ODBC_CONNECTION_STRING");
    if (!raw) throw std::runtime_error("ODBC_CONNECTION_STRING is required");
    iconv_t converter = iconv_open("UTF-16LE", "UTF-8");
    if (converter == reinterpret_cast<iconv_t>(-1)) {
        throw std::runtime_error("Cannot create UTF-8 converter");
    }
    size_t inputBytes = std::strlen(raw);
    std::vector<SQLWCHAR> result(inputBytes + 1);
    char* input = const_cast<char*>(raw);
    char* output = reinterpret_cast<char*>(result.data());
    size_t outputBytes = result.size() * sizeof(SQLWCHAR);
    const size_t capacity = outputBytes;
    size_t status = iconv(converter, &input, &inputBytes, &output, &outputBytes);
    int closeStatus = iconv_close(converter);
    if (status == static_cast<size_t>(-1) || inputBytes != 0 || closeStatus != 0) {
        throw std::runtime_error("ODBC_CONNECTION_STRING must be valid UTF-8");
    }
    result.resize((capacity - outputBytes) / sizeof(SQLWCHAR));
#endif
    if (result.empty() || result.size() >= 32767) {
        throw std::runtime_error("Invalid ODBC_CONNECTION_STRING length");
    }
    result.push_back(0);
    return result;
}

void connectWithRetry(SQLHDBC dbc, std::vector<SQLWCHAR>& connectionString) {
    constexpr int maxAttempts = 4;
    std::mt19937 random{std::random_device{}()};
    std::uniform_int_distribution<int> jitter{0, 250};
    for (int attempt = 1; attempt <= maxAttempts; ++attempt) {
        requireSuccess(SQLSetConnectAttr(
            dbc, SQL_ATTR_LOGIN_TIMEOUT,
            reinterpret_cast<SQLPOINTER>(std::uintptr_t{30}), 0),
            SQL_HANDLE_DBC, dbc, "Set login timeout");
        SQLRETURN rc = SQLDriverConnectW(
            dbc, nullptr, connectionString.data(), SQL_NTS,
            nullptr, 0, nullptr, SQL_DRIVER_NOPROMPT);
        if (SQL_SUCCEEDED(rc)) {
            if (rc == SQL_SUCCESS_WITH_INFO) logDiagnostics(SQL_HANDLE_DBC, dbc);
            std::cout << "event=connected attempt=" << attempt << '\n';
            return;
        }
        bool transient = logDiagnostics(SQL_HANDLE_DBC, dbc);
        if (!transient || attempt == maxAttempts) {
            throw std::runtime_error("Connect failed");
        }
        auto delay = std::chrono::milliseconds{
            (1 << (attempt - 1)) * 10000 + jitter(random)};
        std::cerr << "event=connect_retry attempt=" << attempt
                  << " delay_ms=" << delay.count() << '\n';
        std::this_thread::sleep_for(delay);
    }
}

int main() {
    try {
        auto connectionString = readConnectionString();
        Handles handles;
        if (!SQL_SUCCEEDED(SQLAllocHandle(
                SQL_HANDLE_ENV, SQL_NULL_HANDLE, &handles.env))) {
            throw std::runtime_error("Allocate environment");
        }
        requireSuccess(SQLSetEnvAttr(
            handles.env, SQL_ATTR_ODBC_VERSION,
            reinterpret_cast<SQLPOINTER>(std::uintptr_t{SQL_OV_ODBC3}), 0),
            SQL_HANDLE_ENV, handles.env, "Set ODBC version");
        requireSuccess(SQLAllocHandle(SQL_HANDLE_DBC, handles.env, &handles.dbc),
                       SQL_HANDLE_ENV, handles.env, "Allocate connection");
        connectWithRetry(handles.dbc, connectionString);
        handles.connected = true;
        requireSuccess(SQLAllocHandle(SQL_HANDLE_STMT, handles.dbc, &handles.stmt),
                       SQL_HANDLE_DBC, handles.dbc, "Allocate statement");
        requireSuccess(SQLSetStmtAttr(
            handles.stmt, SQL_ATTR_QUERY_TIMEOUT,
            reinterpret_cast<SQLPOINTER>(std::uintptr_t{10}), 0),
            SQL_HANDLE_STMT, handles.stmt, "Set query timeout");
        SQLWCHAR query[] = {'S', 'E', 'L', 'E', 'C', 'T', ' ', '1', 0};
        requireSuccess(SQLExecDirectW(handles.stmt, query, SQL_NTS),
                       SQL_HANDLE_STMT, handles.stmt, "Execute probe");
        requireSuccess(SQLFetch(handles.stmt),
                       SQL_HANDLE_STMT, handles.stmt, "Fetch probe");
        SQLINTEGER value = 0;
        SQLLEN indicator = 0;
        requireSuccess(SQLGetData(handles.stmt, 1, SQL_C_SLONG,
                                 &value, sizeof(value), &indicator),
                       SQL_HANDLE_STMT, handles.stmt, "Read probe");
        if (indicator == SQL_NULL_DATA || value != 1) {
            throw std::runtime_error("Unexpected probe result");
        }
        std::cout << "event=ready result=" << value << '\n';
        return 0;
    } catch (const std::exception& error) {
        std::cerr << "event=failed operation=\"" << error.what() << "\"\n";
        return 1;
    }
}

Das Programm fordert für jeden von maximal vier Verbindungsversuchen eine 30-sekündige Verbindungszeit sowie eine 10-sekündige Abfragezeit. Zwischen fehlgeschlagenen transienten Verbindungsversuchen wartet er 10, 20 und 40 Sekunden, jeweils mit 0 bis 250 Millisekunden zufälligen Jitters. Diese Beschränkungen setzen keine feste Gesamtfrist für die Authentifizierung. Das Beispiel klassifiziert ausgewählte transiente Verbindungsfehler; passe die Richtlinie mit dem Azure SQL Transient Fault Error Catalog an deine Arbeitslast an. Es versucht keine Anwendungsbefehle oder Schreibvorgänge erneut.

ConnectRetryCount und ConnectRetryInterval die Verbindungsresilienz für berechtigte Verbindungen zu konfigurieren, die im Leerlauf abbrechen. Sie versuchen die Erstverbindung nicht erneut oder spielen die Anwendungsbefehle erneut ab. Halte die Idle-Recovery-Verzögerungen kürzer als deine Abfragezeit. Das Beispiel protokolliert SQLSTATE-Werte und native Fehlerzahlen anstelle von Verbindungszeichenketten oder vollständigen Diagnosemeldungen. Wenn Sie Nachrichtentexte zur Fehlersuche benötigen, speichern Sie diese in einem geschützten Diagnoseprotokoll.

Baue und führe die Baseline durch

Verwenden Sie eine Compiler-Umgebung, die zur Prozessorarchitektur Ihrer Anwendung passt. Unter Windows führe die Befehle in Developer PowerShell für Visual Studio aus. Unter Linux und macOS verwenden Sie eine Shell mit Ihrem Compiler und unixODBC-Entwicklungsdateien zur Verfügung.

cl /nologo /std:c++17 /EHsc /W4 odbc-baseline.cpp odbc32.lib
.\odbc-baseline.exe

g++ -std=c++17 -Wall -Wextra -pthread odbc-baseline.cpp -lodbc -o odbc-baseline
./odbc-baseline

clang++ -std=c++17 -Wall -Wextra -pthread \
  -I"$(brew --prefix unixodbc)/include" -L"$(brew --prefix unixodbc)/lib" \
  odbc-baseline.cpp -lodbc -liconv -o odbc-baseline
./odbc-baseline

Eine erfolgreiche erste Verbindung druckt die folgende Ausgabe. Zusätzliche Diagnoseunterlagen könnten ebenfalls erscheinen.

event=connected attempt=1
event=ready result=1

Löschen ODBC_CONNECTION_STRING , wenn du fertig bist: Nutze Remove-Item Env:\ODBC_CONNECTION_STRING es in PowerShell oder unset ODBC_CONNECTION_STRING in Bash oder Zsh.

Für Verfügbarkeitsgruppen-Listener und Failover-Einstellungen verwenden Sie High Availability und Disaster Recovery.

Wichtigste Funktionen

• Cross-Platform: Die gleiche API unter Windows, Linux und macOS.
• Microsoft Entra ID-Authentifizierung: Verwaltete Identität, Service Principal und integrierte Authentifizierung sowie interaktive Authentifizierung auf Windows. Verfügbare Methoden hängen von der Host- und Datenbankkonfiguration ab.
• 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 für Availability Group Listener 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

Anfordern eines Features

Um eine Funktion anzufordern, reichen Sie eine Idee über SQL Server Feedback ein.

Verwandte Inhalte

• ODBC Programmer's Reference: Die ODBC API-Spezifikation, die dieser Treiber implementiert, separat vom Treiber dokumentiert.
• Funktionen des SQL Server Native Client: Historischer API-Kontext. Überprüfen Sie die aktuelle Treiberdokumentation auf Plattformunterstützung, Authentifizierung und Verschlüsselungsverhalten. Die native Client- und OLE-Datenbank-Anleitung stellt keine aktuelle ODBC-Treiberunterstützung fest.
• BCP-Utility: Das Bulk-Copy-Tool, das separat vom Treiber installiert wird.
• sqlcmd-Utility: Das Kommandozeilen-Abfragetool, das separat vom Treiber installiert wird.
• Matrix der unterstützten Treiberfunktionen
• Blog zu SQL Server-Treibern