Ovladač Microsoft ODBC pro SQL Server

Stáhnout ovladač ODBC

ODBC je nativní aplikační programovací rozhraní (API) pro přístup k datům pro aplikace napsané v C a C++. Ovladač Microsoft ODBC Driver for SQL Server se připojuje k systému SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics a databázi SQL v Microsoft Fabric. Pro verze databáze, které každé vydání ovladačů podporuje, viz kompatibilita verzí SQL.

Vaše aplikace volá správce ovladačů ODBC, který načte ovladač a předá mu volání ODBC. Používejte Windows ODBC Driver Manager ve Windows a unixODBC v Linuxu a macOS.

Mezi další jazyky, které můžou používat ROZHRANÍ ODBC, patří COBOL, Perl, PHP a Python. ODBC je široce používán v datových integračních scénářích a Microsoft Drivers for PHP for SQL Server jsou postaveny na tomto ovladači.

Varianta ODBC nástroje sqlcmd a nástroj bcp používají tento ovladač, ale instalují se samostatně: balíček mssql-tools18 v Linuxu a macOS a Microsoft Command Line Utilities ve Windows. Varianta sqlcmd pro Go tento ovladač nepoužívá. Použijte sqlcmd k spouštění Transact-SQL (T-SQL) příkazů, systémových procedur a skriptových souborů. Použijte bcp k hromadnému kopírování dat mezi instancí serveru SQL Server a datovým souborem, v obou směrech.

Výběr výchozího bodu

Směrný plán výroby pro Azure SQL

Použijte tento kompletní program v C++17 jako výchozí bod pro aplikaci hostovanou v Azure. Připojí se, spustí SELECT 1, zkontroluje výsledek a uvolní ODBC handle. Nainstalujte Driver 18 a vývojové soubory platformy ODBC před jeho sestavením. Předpoklady najdete v tématu Vývoj aplikací v C a C++ pomocí ovladače ODBC.

V prostředí aplikace nastavte ODBC_CONNECTION_STRING na váš úplný připojovací řetězec. Následující příklad používá systémově přiřazenou spravovanou identitu. Hostitel musí mít tuto identitu povolenou a databáze jí musí udělit přístup. Pro požadavky na hostitele, uživatelem přiřazené identity a lokální vývojovou autentizaci viz Použijte Microsoft Entra ID s ovladačem ODBC.

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 vyžaduje koncový bod podporující Tabular Data Stream (TDS) 8.0. V opačném případě použijte Encrypt=yes;TrustServerCertificate=no. Nakonfigurujte certifikát, kterému klient důvěřuje a jehož název se shoduje s názvem serveru. Pro nastavení a ověření viz Řešení problémů s šifrováním připojení.

Nechte přihlašovací údaje mimo zdrojové soubory a historii shellu. Pro příkazy pro nastavení proměnné prostředí viz Konfigurace připojení. Na Linuxu a macOS uveďte jeho hodnotu jako UTF-8. Uložte následující program jako 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;
    }
}

Program požaduje 30sekundový časový limit připojení pro každý z nejvýše čtyř pokusů o připojení a 10sekundový časový limit dotazu. Mezi neúspěšnými pokusy o připojení, které selhaly kvůli přechodné chybě, čeká 10, 20 a 40 sekund, přičemž každý má od 0 do 250 milisekund náhodného jitteru. Tato omezení nestanovují pevný celkový termín pro ověření. Příklad klasifikuje vybrané přechodné chyby připojení; přizpůsobte politiku vaší zátěži pomocí katalogu přechodných chyb Azure SQL. Nezkouší znovu aplikační příkazy ani zápisy.

ConnectRetryCount a ConnectRetryInterval konfigurují odolnost připojení pro podporovaná připojení, která se během nečinnosti přeruší. Nezkoušejí znovu navázat počáteční připojení ani znovu provést příkazy aplikace. Udržujte zpoždění obnovení po nečinnosti kratší než časový limit dotazu. Ukázka zaznamenává hodnoty SQLSTATE a nativní chybová čísla místo řetězců spojení nebo plných diagnostických zpráv. Pokud potřebujete text zprávy pro řešení problémů, zaznamenejte ho do chráněného diagnostického logu.

Sestavte a spusťte základní verzi

Používejte prostředí kompilátoru, které odpovídá architektuře procesoru vaší aplikace. Na Windows spusťte příkazy v Developer PowerShell for Visual Studio. Na Linuxu a macOS použijte shell s vaším kompilátorem a unixODBC vývojovými soubory.

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

Úspěšné první připojení vytiskne následující výstup. Mohou se také objevit další diagnostické záznamy.

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

Vymaž ODBC_CONNECTION_STRING po dokončení: použij Remove-Item Env:\ODBC_CONNECTION_STRING v PowerShellu, nebo unset ODBC_CONNECTION_STRING v Bash či Zsh.

Pro posluchače skupin dostupnosti a nastavení failoveru použijte vysokou dostupnost a obnovu po havárii.

Klíčové funkce

  • Cross-platform: Stejné API na Windows, Linuxu a macOS.
  • Autentizace Microsoft Entra ID: Spravovaná identita, instanční objekt služby a integrovaná autentizace, plus interaktivní autentizace ve Windows. Dostupné metody závisí na konfiguraci hostitele a databáze.
  • Přísné šifrování: Připojení TDS 8.0 s plnou validací certifikátů ve verzi 18 a novějších.
  • Always Encrypted: Šifrování na straně klienta pro citlivé sloupce, s podporou pro poskytovatele vlastních úložišť klíčů.
  • Odolnost spojení: Transparentní obnovení spojení, které se během nečinnosti vytratilo.
  • Vysoká dostupnost: Podpora skupinových posluchačů s .MultiSubnetFailover
  • Klasifikace dat: Citlivostní metadata pro klasifikované sloupce.
  • Vektorový datový typ: Nativní podpora vektorového typu.
  • Distribuované transakce: Podpora transakcí XA prostřednictvím služba MS DTC (Microsoft Distributed Transaction Coordinator) (MSDTC).
  • Doprovodné nástroje: sqlcmd a bcp, instalované zvlášť.

Začínáme

Článek Description
Stažení ovladače ODBC pro SQL Server Instalační a balíčkové soubory ke stažení pro všechny podporované verze ovladačů na všech třech platformách.
Vývoj aplikací v C a C++ s ovladačem ODBC Které hlavičky zahrnout, v jakém pořadí, které knihovny propojit a jak si vybrat mezi asynchronním vykonáním a vlákny.
Připojte se k databázi a dotazujte ji pomocí C++ Kompletní vzorek C++, který se připojí, provádí dotaz a čte výsledky, takže můžete ověřit své nastavení od začátku do konce.
Životní cyklus podpory Které verze ovladačů jsou stále podporovány a kdy každá z nich ukončí podporu.
Rozdíly v hlavních verzích Co se rozbije, když přejdete z verze 17 na verzi 18, počínaje změnou výchozího šifrování.

Instalace ovladače

Článek Description
Systémové požadavky, instalace a soubory ovladačů (Windows) Podporoval verze pro Windows, instalační příkazový řádek pro tiché nasazení a místo, kde se každý ovladač nachází na disku.
Systémové požadavky (Linux a macOS) Které linuxové distribuce a macOS vydávají jednotlivé verze ovladačů, plus kompatibilita verzí SQL Server.
Nainstalujte ovladač ODBC na Linux Kroky správce balíčků pro Alpine, Debian, Red Hat, SUSE, Ubuntu a Azure Linux, plus offline instalace a umístění souborů ovladačů.
Nainstalujte ovladač ODBC na macOS Postup pro tap a formule Homebrew v systému macOS, včetně postupu instalace verze 18, 17 nebo 13.1.
Nainstalujte správce ovladačů unixODBC (Linux a macOS) Nainstalujte nebo upgradujte unixODBC, správce ovladačů, který načítá ODBC ovladače na Linuxu a macOS.

Konfigurace a připojení

Článek Description
DSN a klíčová slova a atributy připojovacího řetězce Kompletní katalog klíčových slov připojovací řetězec, DSN položek a SQLSetConnectAttr atributů, s akceptovanými hodnotami pro každý z nich.
Klíčová slova v řetězcích spojení a názvy datových zdrojů (Linux a macOS) Jak odbc.ini a odbcinst.ini definují DSN na Linuxu a macOS, plus nastavení protokolu Transport Layer Security (TLS) a nastavení udržování spojení (keep-alive) protokolu Transmission Control Protocol (TCP) specifická pro tyto platformy.
Správce zdrojů dat ODBC DSN (Windows) Nakonfigurujte datový zdroj přes uživatelské rozhraní Windows místo připojovacího řetězce.
Poolování připojení s ohledem na ovladač (Windows) Která klíčová slova a atributy připojovacího řetězce zařazují připojení do samostatného fondu a která při resetování vyžadují další zpáteční komunikaci.

Autentizace a zabezpečení

Článek Description
Použijte Microsoft Entra ID s ovladačem ODBC Každá hodnota klíčového slova Authentication, od spravované identity a instančního objektu služby až po interaktivní a integrované, včetně nastavení, které každá z nich vyžaduje.
Používejte Always Encrypted s ovladačem ODBC Před odesláním do databáze šifrujte citlivé hodnoty sloupců spolu se shrnutím API ovladače a zdokumentovanými omezeními.
Klasifikace dat Přečtěte si štítky citlivosti, které server přiřazuje ke sloupcům klasifikací, aby vaše aplikace mohla vynucovat vlastní politiku ochrany dat.
Používejte integrovanou autentizaci (Linux a macOS) Nakonfigurujte Kerberos tak, aby se klient pro Linux nebo macOS mohl připojit pomocí přihlašovacích údajů pro Windows místo přihlášení do SQL Server.

Vysoká dostupnost a odolnost proti chybám

Článek Description
Odolnost připojení Jak ConnectRetryCount a ConnectRetryInterval obnovují připojení, když ho server při nečinnosti ukončí, a chyby IMCxx, které ovladač vrací, když obnova není možná.
Vysoká dostupnost a zotavení po havárii Připojte se přes skupinový posluchač dostupnosti a používejte MultiSubnetFailover tak, aby se failover nezasekl při timeoutu podsítě.
Používejte transparentní síťové IP rozlišení Jak starší mechanismus fallback TransparentNetworkIPResolution řadí pokusy o připojení napříč více adresami internetového protokolu (IP) a proč jej MultiSubnetFailover nahrazuje.

Práce s daty

Článek Description
Vektorový datový typ Svázat, odesílat a načítat typ vector, včetně jeho nativní reprezentace v jazyce C a podpory hromadného kopírování.
Používejte XA transakce s DTC Zaregistrujte SQL Server do distribuované transakce přes služba MS DTC (Microsoft Distributed Transaction Coordinator) na Windows, Linux nebo macOS.
Programátorské pokyny (Linux a macOS) Najděte pokyny k programování pro Linux a macOS, včetně stavu funkcí, úvah o znakových sadách, OpenSSL a Alpine Linux.

Diagnostika a řešení potíží

Článek Description
Řešení problémů s šifrováním spojení Opravte chyby v certifikátech a šifrování, které se objevují ve verzi 18, protože šifruje ve výchozím nastavení.
Sledování přístupu k datům (Linux a macOS) Zapněte sledování ovladačů a zachyťte logovací soubor, když potřebujete vidět volání, která vaše aplikace skutečně vykonává.
Známé problémy (Linux a macOS) Potvrzené vady a jejich obcházení. Podívejte se zde před podáním žádosti o podporu.
Často kladené otázky (Linux a macOS) Krátké odpovědi na otázky, které se nejčastěji objevují ohledně ovladače na Linuxu a macOS.

Poznámky k vydání a opravy chyb

Článek Description
Poznámky k vydání pro Windows Nové funkce, změny chování a opravy v každém vydání ovladačů Windows.
Poznámky k vydání pro Linux a macOS Nové funkce, změny chování a opravy v každém vydání ovladačů pro Linux a macOS.
Poznámky k vydání nástrojů SQL Server Změny v utilitách sqlcmd a bcp , které se instalují samostatně od ovladače na Linuxu a macOS.

Reference

Článek Description
ODBC ovladač na Windows Shrnutí verzí po verzi toho, co ovladač podporuje ve Windows, a index článků specifických pro Windows.
Funkce ovladače ODBC v systému Windows Které vydání představilo každou funkci Windows a změny chování, které s tím přišly.

Žádost o funkci

Pro žádost o funkci pošlete nápad prostřednictvím zpětné vazby přes SQL Server.

Související obsah

  • Poslední aktualizace v