Microsoft ODBC-drivrutin för SQL Server

Ladda ned ODBC-drivrutins

ODBC är ett inbyggt applikationsprogrammeringsgränssnitt (API) för dataåtkomst för applikationer skrivna i C och C++. Microsoft ODBC Driver för SQL Server ansluter till SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics och SQL database i Microsoft Fabric. För de databasversioner som varje drivrutinsversion stödjer, se SQL-versionskompatibilitet.

Din applikation anropar ODBC-drivrutinshanteraren, som laddar drivrutinen och skickar ODBC-anrop till den. Använd Windows ODBC Driver Manager på Windows och unixODBC på Linux och macOS.

Andra språk som kan använda ODBC är COBOL, Perl, PHP och Python. ODBC används i stor utsträckning i dataintegrationsscenarier, och Microsoft-drivrutinerna för PHP för SQL Server är byggda på denna drivrutin.

ODBC-varianten av sqlcmd och verktyget bcp använder denna drivrutin, men de installeras separat: paketet mssql-tools18 på Linux och macOS, samt Microsoft Command Line Utilities på Windows. Go-varianten av sqlcmd använder inte denna drivrutin. Använd sqlcmd för att köra Transact-SQL (T-SQL)-satser, systemprocedurer och skriptfiler. Använd bcp för att bulkkopiera data mellan en instans av SQL Server och en datafil, i båda riktningarna.

Välj startpunkt

• För att installera drivrutinen, gå till Systemkrav, installation och drivrutinsfiler för Windows, eller installera ODBC-drivrutinen på Linux, installera ODBC-drivrutinen på macOS och installera unixODBC-drivrutinshanteraren.
• För att skriva ditt första program går du till Anslut till och fråga en databas med C++. För alternativ för datakällnamn (DSN) och anslutningssträng, använd DSN och nyckelord och attribut för anslutningssträng. Om din kompilator inte kan hitta headers eller om din build inte länkar, gå till Utveckla C- och C++-applikationer med ODBC-drivrutinen.
• För att ansluta till Azure SQL med lösenordslös autentisering, gå till Använd Microsoft Entra ID med ODBC-drivrutinen.
• För att göra en befintlig app motståndskraftig mot tillfälliga fel, gå till Anslutningsresiliens och hög tillgänglighet samt katastrofåterställning.
• För att uppgradera från version 17, gå till Stora versionsskillnader och Felsökning av anslutningskryptering.
• För att diagnostisera ett anslutnings- eller frågefel, gå till Felsökning av anslutningskryptering och Kända problem (Linux och macOS).

Produktionsbaslinje för Azure SQL

Använd detta kompletta C++17-program som utgångspunkt för en Azure-hostad applikation. Den kopplar in, kör SELECT 1, kontrollerar resultatet och släpper ODBC-handtagen. Installera Driver 18 och plattformens ODBC-utvecklingsfiler innan du bygger det. För förkunskapskrav, se Utveckla C- och C++-applikationer med ODBC-drivrutinen.

Ställ ODBC_CONNECTION_STRING in i applikationens miljö till din kompletta reťazec pripojenia. Följande exempel använder en systemtilldelad hanterad identitet. Värddatorn måste ha den identiteten aktiverad, och databasen måste ge den åtkomst. För värdkrav, användar-assignerade identiteter och lokal utvecklingsautentisering, se Använd Microsoft Entra ID med ODBC-drivrutinen.

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 kräver en endpoint som stöder Tabular Data Stream (TDS) 8.0. Annars använder du Encrypt=yes;TrustServerCertificate=no. Konfigurera ett certifikat som klienten litar på och vars namn matchar servern. För installation och verifiering, se Felsökning av anslutningskryptering.

Håll inloggningsuppgifter borta från källfiler och shellhistorik. För kommandon för att sätta miljövariabeln, se Konfigurera anslutningen. På Linux och macOS, ange dess värde som UTF-8. Spara följande program som 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;
    }
}

Programmet begär en 30-sekunders anslutningstimeout för var och en av högst fyra anslutningsförsök samt en 10-sekunders frågetimeout. Mellan misslyckade tillfälliga anslutningsförsök väntar den 10, 20 och 40 sekunder, var och en med 0 till 250 millisekunder av slumpmässig fördröjning. Dessa begränsningar sätter ingen strikt total deadline för autentisering. Exemplet klassificerar utvalda tillfälliga anslutningsfel; anpassa policyn till din arbetsbelastning med Azure SQL transient fault error catalog. Den försöker inte igen med applikationskommandon eller skrivningar.

ConnectRetryCount och ConnectRetryInterval konfigurerar anslutningstålighet för anslutningar som stöds som kopplas ned när de är inaktiva. De försöker inte återupprätta den initiala anslutningen eller spelar upp programkommandon igen. Se till att viloåterställningsfördröjningarna är kortare än din frågetimeout. Kodexemplet loggar SQLSTATE-värden och inbyggda felnummer istället för anslutningssträngar eller fullständiga diagnostiska meddelanden. Om du behöver meddelandetext för felsökning, registrera den i en skyddad diagnostisk logg.

Bygg och kör baseline

Använd en kompilatormiljö som matchar applikationens processorarkitektur. På Windows, kör kommandona i Developer PowerShell för Visual Studio. På Linux och macOS, använd ett skal med din kompilator och unixODBC-utvecklingsfiler tillgängliga.

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

En lyckad första anslutning skriver ut följande resultat. Ytterligare diagnostikposter kan också dyka upp.

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

Rensa ODBC_CONNECTION_STRING när du är klar: använd Remove-Item Env:\ODBC_CONNECTION_STRING i PowerShell, eller unset ODBC_CONNECTION_STRING i Bash eller Zsh.

För availability group-lyssnare och failover-inställningar använder du High availability and disaster recovery.

Centrala egenskaper

• Plattformsoberoende: Samma API på Windows, Linux och macOS.
• Microsoft Entra ID-autentisering: Hanterad identitet, tjänstens huvudnamn och integrerad autentisering, plus interaktiv autentisering på Windows. Tillgängliga metoder beror på värd- och databaskonfigurationen.
• Strikt kryptering: TDS 8.0-anslutningar med full certifikatvalidering i version 18 och senare versioner.
• Alltid krypterat: Klientbaserad kryptering för känsliga kolumner, med stöd för anpassade nyckellagringsleverantörer.
• Anslutningsresiliens: Transparent återställning av en anslutning som tappats medan den var inaktiv.
• Hög tillgänglighet: Stöd för lyssnare för tillgänglighetsgrupp med MultiSubnetFailover.
• Dataklassificering: Känslighetsmetadata för klassificerade kolumner.
• Vektordatatyp: Inbyggt stöd för vektortypen .
• Distribuerade transaktioner: XA-transaktionsstöd via Microsoft Distributed Transaction Coordinator (MSDTC).
• Följeslagarverktyg: sqlcmd och bcp, installerade separat.

Get started

Installera drivrutinen

Konfigurera och ansluta

Autentisera och säkra

Hög tillgänglighet och återhämtning

Arbeta med data

Diagnostisera och felsöka

Versionsanteckningar och buggfixar

Reference

Begär en funktion

För att begära en funktion, skicka in en idé via SQL Server-feedback.

Relaterat innehåll

• ODBC Programmer's Reference: ODBC API-specifikationen som denna drivrutin implementerar, dokumenterad separat från drivrutinen.
• SQL Server Native Client-funktioner: Historisk API-kontext. Kontrollera aktuell drivrutinsdokumentation för plattformsstöd, autentisering och krypteringsbeteende. Native Client- och OLE DB-vägledning fastställer inte aktuellt ODBC-drivrutinsstöd.
• BCP-verktyg: Bulkkopieringsverktyget, installerat separat från drivrutinen.
• sqlcmd-verktyg: Kommandoradsfrågeverktyget, installerat separat från drivrutinen.
• Matris för drivrutinsfunktionsstöd
• blogg SQL Server-drivrutiner