Microsoft ODBC-stuurprogramma voor SQL Server

ODBC-stuurprogramma downloaden

ODBC is een native programmeerinterface voor gegevenstoegang (API) voor applicaties geschreven in C en C++. De Microsoft ODBC Driver for SQL Server maakt verbinding met SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics en SQL database in Microsoft Fabric. Voor de databaseversies die elke driverversie ondersteunt, zie SQL-versiecompatibiliteit.

Je applicatie roept de ODBC-drivermanager aan, die de driver laadt en ODBC-aanroepen aan de driver doorgeeft. Gebruik de Windows ODBC Driver Manager op Windows en unixODBC op Linux en macOS.

Andere talen die ODBC kunnen gebruiken, zijn COBOL, Perl, PHP en Python. ODBC wordt veel gebruikt in data-integratiescenario's, en de Microsoft Drivers voor PHP voor SQL Server zijn op deze driver gebouwd.

De ODBC-variant van sqlcmd en het hulpprogramma bcp gebruiken deze driver, maar worden afzonderlijk geïnstalleerd: het pakket mssql-tools18 op Linux en macOS, en de Microsoft Command Line Utilities op Windows. De Go-variant van sqlcmd gebruikt deze driver niet. Gebruik sqlcmd om Transact-SQL (T-SQL) statements, systeemprocedures en scriptbestanden uit te voeren. Gebruik bcp om data in bulk te kopiëren tussen een instantie van SQL Server en een databestand, in beide richtingen.

Uw beginpunt kiezen

• Om de driver te installeren, ga je naar Systeemvereisten, installatie en driverbestanden voor Windows, of installeer je de ODBC-driver op Linux, installeer je de ODBC-driver op macOS en installeer je de unixODBC-drivermanager.
• Om je eerste applicatie te schrijven, ga je naar Verbinding maken met en een database bevragen met C++. Voor opties voor databronnaam (DSN) en verbindingsreeks gebruik DSN en verbindingsreeks sleutelwoorden en attributen. Als je compiler de headers niet kan vinden of je build niet linkt, ga dan naar Develop C- en C++-applicaties met de ODBC-driver.
• Om verbinding te maken met Azure SQL met wachtwoordloze authenticatie, ga je naar Gebruik Microsoft Entra ID met de ODBC-driver.
• Om een bestaande app weerbaar te maken tegen tijdelijke storingen, ga je naar Verbindingsbestendigheid en Hoge beschikbaarheid en noodherstel.
• Om te upgraden van versie 17, ga naar Belangrijke versieverschillen en Verbindingsencryptie probleemoplossing.
• Om een verbindings- of queryprobleem te diagnosticeren, ga naar Verbindingsversleuteling probleemoplossing en Bekende problemen (Linux en macOS).

Productiebasislijn voor Azure SQL

Gebruik dit complete C++17-programma als startpunt voor een Azure-gehoste applicatie. Het maakt verbinding, voert uit, SELECT 1controleert het resultaat en geeft de ODBC-handles vrij. Installeer Driver 18 en de ODBC-ontwikkelingsbestanden van het platform voordat je het bouwt. Zie voor vereisten C- en C++-toepassingen ontwikkelen met het ODBC-stuurprogramma.

Stel ODBC_CONNECTION_STRING in de applicatieomgeving in als je volledige verbindingsreeks. Het volgende voorbeeld gebruikt een door het systeem toegewezen beheerde identiteit. De host moet die identiteit ingeschakeld hebben, en de database moet die identiteit toegang geven. Voor hostvereisten, door gebruikers toegewezen identiteiten en lokale ontwikkelauthenticatie, zie Gebruik Microsoft Entra ID met de 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 vereist een eindpunt dat Tabular Data Stream (TDS) 8.0 ondersteunt. Gebruik anders Encrypt=yes;TrustServerCertificate=no. Configureer een certificaat dat door de client wordt vertrouwd en waarvan de naam overeenkomt met die van de server. Voor de installatie en verificatie, zie Problemen met verbindingsversleuteling oplossen.

Houd inloggegevens uit bronbestanden en shellgeschiedenis. Voor commando's om de omgevingsvariabele in te stellen, zie De verbinding configureren. Op Linux en macOS geef je de waarde ervan als UTF-8. Sla het volgende programma op 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;
    }
}

Het programma vraagt een verbindingstimeout van 30 seconden aan voor elk van maximaal vier verbindingspogingen en een querytimeout van 10 seconden. Tussen mislukte tijdelijke verbindingspogingen wacht hij 10, 20 en 40 seconden, telkens met 0 tot 250 milliseconden willekeurige jitter. Deze limieten leggen geen vaste algemene deadline op voor authenticatie. Het voorbeeld classificeert geselecteerde tijdelijke verbindingsfouten; pas het beleid aan aan je workload met de Azure SQL transient fault error catalogus. Het probeert applicatiecommando's of schrijfopdrachten ook niet opnieuw.

ConnectRetryCount en ConnectRetryInterval configureren verbindingsveerkracht voor in aanmerking komende verbindingen die wegvallen terwijl ze inactief zijn. Ze proberen de initiële verbinding niet opnieuw te maken of applicatiecommando's opnieuw af te spelen. Houd de vertragingen voor idle-recovery korter dan de timeout van je query. Het voorbeeld logt SQLSTATE-waarden en native foutnummers in plaats van verbindingsstrings of volledige diagnostische berichten. Als je de berichttekst nodig hebt voor probleemoplossing, leg deze dan vast in een beschermd diagnostisch logboek.

Bouw en run de baseline

Gebruik een compileromgeving die aansluit bij de processorarchitectuur van je applicatie. Op Windows voer je de commando's uit in Developer PowerShell voor Visual Studio. Op Linux en macOS gebruik je een shell met je compiler en unixODBC-ontwikkelbestanden beschikbaar.

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

Een succesvolle eerste verbinding print de volgende output. Aanvullende diagnostische records kunnen ook verschijnen.

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

Wis ODBC_CONNECTION_STRING als je klaar bent: gebruik Remove-Item Env:\ODBC_CONNECTION_STRING in PowerShell, of unset ODBC_CONNECTION_STRING in Bash of Zsh.

Voor beschikbaarheidsgroep-luisteraars en failover-instellingen gebruik High availability and disaster recovery.

Belangrijkste kenmerken

• Cross-platform: Dezelfde API op Windows, Linux en macOS.
• Microsoft Entra ID-authenticatie: Beheerde identiteit, service principal en geïntegreerde authenticatie, plus interactieve authenticatie op Windows. Beschikbare methoden hangen af van de host- en databaseconfiguratie.
• Strikte encryptie: TDS 8.0-verbindingen met volledige certificaatvalidatie in versie 18 en latere versies.
• Altijd versleuteld: Client-side encryptie voor gevoelige kolommen, met ondersteuning voor aangepaste keystore-providers.
• Verbindingsveerkracht: Transparant herstel van een verbinding die tijdens een inactieve verbinding is weggevallen.
• Hoge beschikbaarheid: listenerondersteuning voor beschikbaarheidsgroepen met MultiSubnetFailover.
• Dataclassificatie: Gevoeligheidsmetadata voor geclassificeerde kolommen.
• Vectorgegevenstype: Ingebouwde ondersteuning voor het type vector.
• Gedistribueerde transacties: XA-transactieondersteuning via de Microsoft Distributed Transaction Coordinator (MSDTC).
• Begeleidende tools: sqlcmd en bcp, apart geïnstalleerd.

Aan de slag

Het stuurprogramma installeren

Configureren en verbinding maken

Authenticeren en beveiligen

Hoge beschikbaarheid en tolerantie

Werken met gegevens

Diagnosticeren en problemen oplossen

Releaseopmerkingen en opgeloste bugs

Reference

Verzoeken om een functie toe te voegen

Om een functie aan te vragen, dien je een idee in via SQL Server feedback.

Verwante onderwerpen

• ODBC Programmer's Referentie: De ODBC API-specificatie die deze driver implementeert, apart gedocumenteerd van de driver.
• SQL Server Native Client-functies: Historische API-context. Controleer de huidige driverdocumentatie voor platformondersteuning, authenticatie en encryptiegedrag. Native Client- en OLE DB-richtlijnen geven geen uitsluitsel over de huidige ondersteuning voor ODBC-stuurprogramma's.
• BCP utility: De bulk copy utility, geïnstalleerd apart van de driver.
• sqlcmd-hulpprogramma: De opdrachtregelqueryhulp, geïnstalleerd apart van de driver.
• Driverfunctieondersteuningsmatrix
• SQL Server-stuurprogramma's blog