Ovladač Microsoft ODBC pro SQL Server

Stáhnout ovladač ODBC

ODBC je primární nativní rozhraní API pro přístup k datům pro aplikace napsané v jazyce C a C++ pro SQL Server. 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.

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.

Nástroje sqlcmd a bcp fungují s tímto ovladačem, ale instalují se samostatně: mssql-tools18 balíček na Linux a macOS a Microsoft Command Line Utilities na Windows. 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í 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

Tento fragment kódu použijte jako výchozí bod pro produkční Azure SQL připojení. Načítá název serveru a název databáze z konfigurace aplikace, autentizuje se spravovanou identitou, aby se v připojovací řetězec neobjevilo žádné tajemství, a umožňuje šifrování Tabular Data Stream (TDS) 8.0 s plnou validací certifikátů. Nastaví časový limit pro každý pokus o přihlášení a při přechodných selháních opakuje pokusy s exponenciálně prodlužovanými intervaly a náhodným rozptylem.

Ukázka kódu v jazyce C++ v tomto článku kvůli stručnosti vynechává direktivy include, alokaci handle a pomocnou funkci pro protokolování.

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 a ConnectRetryInterval umožňují odolnost nečinného připojení, což transparentně obnovuje spojení, které bylo během nečinnosti přerušeno. Nezkoušejí znovu provádět počáteční připojení, proto tento úryvek také implementuje opakované zkoušení na úrovni aplikace. Ponechte si obojí.

ODBC hlásí diagnostické informace prostřednictvím SQLGetDiagRec, nikoli pouze pomocí návratového kódu, proto před opakováním pokusu nejprve klasifikujte selhání. Chyba autentizace nebo konfigurace pak okamžitě selže místo toho, aby se spotřeboval celý rozpočet na opakované pokusy.

Další informace o jednotlivých částech této konfigurace najdete tady:

Pro katalog přechodných chyb v Azure SQL viz přechodné chybové kódy.

Klíčové funkce

  • Cross-platform: Stejné API na Windows, Linuxu a macOS.
  • Ověřování Microsoft Entra ID: Bezheslová připojení pomocí spravované identity, instančního objektu služby a interaktivních a integrovaných postupů.
  • 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.
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 určují DSN v Linuxu a macOS a nastavení TLS a TCP keep-alive specifická pro tyto platformy.
Správce zdrojů dat ODBC DSN (Windows) Každá možnost na stránkách průvodce Windows DSN, když konfigurujete datový zdroj pomocí uživatelského rozhraní 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 Šifrovat citlivé sloupce v klientském procesu tak, aby otevřený text nikdy nedorazil na server, včetně shrnutí API ovladače a jeho zdokumentovaných omezení.
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ší záložní mechanismus TransparentNetworkIPResolution řadí pokusy o připojení k více IP adresám 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) Které funkce ovladače podporují na Linuxu a macOS, což ne, a jak se liší zpracování znakových sad a OpenSSL od Windows.

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.

Související obsah

  • Last updated on