Microsoft ODBC-stuurprogramma voor SQL Server

ODBC-stuurprogramma downloaden

ODBC is de primaire systeemeigen API voor gegevenstoegang voor toepassingen die zijn geschreven in C en C++ voor SQL Server. 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.

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 sqlcmd- en bcp-programma's werken met deze driver, maar ze installeren apart: het mssql-tools18 pakket op Linux en macOS, en de Microsoft Command Line Utilities op Windows. 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

Productiebasislijn voor Azure SQL

Gebruik dit fragment als uitgangspunt voor een productiegerichte Azure SQL-verbinding. Het laadt de servernaam en databasenaam vanuit applicatieconfiguratie, authenticeert met een beheerde identiteit zodat er geen geheim in de verbindingsreeks verschijnt, en schakelt Tabular Data Stream (TDS) 8.0-encryptie in met volledige certificaatvalidatie. Het stelt een time-out per aanmeldpoging in en probeert het opnieuw bij tijdelijke fouten, met exponentiële back-off en jitter.

Het C++-fragment in dit artikel laat omwille van de beknoptheid de includes, de handle-allocatie en de logginghelper weg.

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 en ConnectRetryInterval maken veerkracht van een inactieve verbinding mogelijk, waarmee een verbinding die wegviel terwijl deze inactief was, transparant wordt hersteld. Ze proberen de initiële verbinding niet opnieuw, daarom implementeert dit fragment ook opnieuw proberen op applicatieniveau. Hou ze allebei.

ODBC rapporteert diagnostische gegevens via SQLGetDiagRec in plaats van alleen via de retourcode, dus classificeer fouten voordat je het opnieuw probeert. Een authenticatie- of configuratiefout mislukt dan direct in plaats van het hele retrybudget te verbruiken.

Zie voor meer informatie over elk onderdeel van deze configuratie:

Voor de catalogus van Azure SQL tijdelijke fouten, zie tijdelijke foutcodes.

Belangrijkste kenmerken

  • Cross-platform: Dezelfde API op Windows, Linux en macOS.
  • Microsoft Entra ID-authenticatie: Wachtwoordloze verbindingen met beheerde identiteit, service principal, interactieve en geïntegreerde stromen.
  • 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

Article Description
Het ODBC-stuurprogramma voor SQL Server downloaden Installer- en pakketdownloads voor elke ondersteunde driverversie, op alle drie de platforms.
Verbind met en raadpleeg een database met C++ Een compleet C++-voorbeeld dat verbindt, een query uitvoert en de resultaten leest, zodat je je setup end-to-end kunt bevestigen.
Ondersteuningslevenscyclus Welke driverversies nog worden ondersteund, en de datum waarop elke driverversie de ondersteuning verlaat.
Grote verschillen in versies Wat gaat er kapot als je van versie 17 naar versie 18 gaat, te beginnen met de standaardwijziging van encryptie.

Het stuurprogramma installeren

Article Description
Systeemvereisten, installatie en driverbestanden (Windows) Ondersteunde Windows-versies, de installer-opdrachtregel voor stille deployment, en waar elk driverbestand op de schijf terechtkomt.
Systeemvereisten (Linux en macOS) Welke Linux-distributies en macOS-releases elke driverversie ondersteunt, plus SQL Server-versiecompatibiliteit.
Installeer de ODBC-driver op Linux Pakketbeheerdersstappen voor Alpine, Debian, Red Hat, SUSE, Ubuntu en Azure Linux, plus offline installatie en de locaties van de driverbestanden.
Installeer de ODBC-driver op macOS Homebrew tap en formulestappen voor macOS, inclusief hoe je versie 18, 17 of 13.1 installeert.
Installeer het unixODBC-stuurprogrammabeheer (Linux en macOS) Installeer of werk unixODBC bij, de stuurprogrammabeheerder die op Linux en macOS het ODBC-stuurprogramma laadt.

Configureren en verbinding maken

Article Description
DSN- en verbindingsreekstrefwoorden en -kenmerken De volledige catalogus van verbindingsreeks-sleutelwoorden, DSN-vermeldingen en SQLSetConnectAttr attributen, met geaccepteerde waarden voor elk.
Verbindingsstring-sleutelwoorden en databronnamen (Linux en macOS) Hoe odbcinst.ini en odbc.ini een DSN definiëren op Linux en macOS, evenals de TLS- en TCP-keep-alive-instellingen die specifiek zijn voor deze platforms.
ODBC Gegevensbronbeheerder DSN (Windows) Elke optie op de Windows DSN-wizardpagina's, voor wanneer je een databron via de UI configureert in plaats van een verbindingsreeks.
Driver-bewuste verbindingspooling (Windows) Welke trefwoorden en kenmerken van de verbindingsreeks zorgen ervoor dat een verbinding een eigen pool krijgt, en welke vereisen een extra heen-en-weer naar de server om te worden gereset.

Authenticeren en beveiligen

Article Description
Gebruik Microsoft Entra ID met de ODBC-driver Elke Authentication zoekwoordwaarde, van beheerde identiteit en serviceprincipe tot interactief en geïntegreerd, met de setup die elk nodig heeft.
Gebruik Always Encrypted met de ODBC-driver Versleutel gevoelige kolommen in het clientproces zodat platte tekst de server nooit bereikt, met de API-samenvatting van de driver en de bijbehorende beperkingen.
Gegevensclassificatie Lees de gevoeligheidslabels die de server aan geclassificeerde kolommen koppelt, zodat je applicatie haar eigen gegevensbeschermingsbeleid kan handhaven.
Gebruik geïntegreerde authenticatie (Linux en macOS) Configureer Kerberos zodat een Linux- of macOS-client verbinding kan maken met Windows-inloggegevens in plaats van via een SQL Server-login.

Hoge beschikbaarheid en tolerantie

Article Description
Verbindingstolerantie Hoe ConnectRetryCount en ConnectRetryInterval een verbinding herstelt wanneer de server deze verbreekt terwijl hij inactief is, en de IMCxx fouten die de driver teruggeeft wanneer herstel niet mogelijk is.
Hoge beschikbaarheid en herstel na noodgevallen Maak verbinding via een availability group listener en gebruik MultiSubnetFailover zodat failover niet vastloopt bij een subnettimeout.
Gebruik transparante netwerk-IP-resolutie Hoe de verouderde TransparentNetworkIPResolution fallback verbindingspogingen over meerdere IP-adressen rangschikt en waarom MultiSubnetFailover deze vervangt.

Werken met gegevens

Article Description
Vectorgegevenstype Bind, verzend en haal het vectortype op, inclusief de native C-representatie en ondersteuning voor bulkkopiëren.
Gebruik XA-transacties met DTC Neem SQL Server op in een gedistribueerde transactie via Microsoft Distributed Transaction Coordinator in Windows, Linux of macOS.
Programmeerrichtlijnen (Linux en macOS) Welke functies de driver ondersteunt op Linux en macOS, welke niet, en hoe verschillen tekensets en OpenSSL-afhandeling van Windows.

Diagnosticeren en problemen oplossen

Article Description
Probleemoplossing voor verbindingsversleuteling Los de certificaat- en versleutelingsfouten op die versie 18 veroorzaakt, omdat deze standaard versleutelt.
Tracering van gegevenstoegang (Linux en macOS) Zet driver tracing aan en maak een logbestand wanneer je de oproepen van je applicatie daadwerkelijk wilt zien.
Bekende problemen (Linux en macOS) Bevestigde defecten en tijdelijke oplossingen. Bekijk hier voordat je een ondersteuningszaak indient.
Veelgestelde vragen (Linux en macOS) Korte antwoorden op de vragen die het vaakst opkomen over de driver op Linux en macOS.

Releaseopmerkingen en opgeloste bugs

Article Description
Releaseopmerkingen voor Windows Nieuwe functies, gedragsveranderingen en fixes in elke Windows-driverrelease.
Release notes voor Linux en macOS Nieuwe functies, gedragswijzigingen en fixes in elke Linux- en macOS-driverrelease.
Release notes voor de SQL Server-tools Wijzigingen aan de sqlcmd- en bcp-programma's , die apart van de driver op Linux en macOS worden geïnstalleerd.

Reference

Article Description
ODBC-driver voor Windows Een versie-voor-versie samenvatting van wat de driver ondersteunt op Windows, en een index van de Windows-specifieke artikelen.
Kenmerken van de ODBC-driver op Windows Welke release introduceerde elke Windows-functie, plus de gedragsveranderingen die erbij hoorden.

Verwante onderwerpen

  • Last updated on