Microsoft ODBC-drivrutin för SQL Server

Ladda ned ODBC-drivrutins

ODBC är det primära interna dataåtkomst-API:et för program som skrivits i C och C++ för SQL Server. 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.

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.

sqlcmd- och bcp-verktygen fungerar med denna drivrutin, men de installeras separat: paketet mssql-tools18 på Linux och macOS, samt Microsoft Command Line Utilities på Windows. 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

Produktionsbaslinje för Azure SQL

Använd det här kodfragmentet som utgångspunkt för en produktionsorienterad Azure SQL anslutning. Den laddar servernamnet och databasnamnet från applikationskonfigurationen, autentiserar med en hanterad identitet så att ingen hemlighet syns i reťazec pripojenia, och möjliggör Tabular Data Stream (TDS) 8.0-kryptering med fullständig certifikatvalidering. Den anger en inloggningstimeout för varje försök och försöker igen vid tillfälliga fel med exponentiell backoff och jitter.

C++-kodexemplet i den här artikeln utelämnar include-direktiv, allokering av handtag och loggningshjälpen av utrymmesskäl.

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 och ConnectRetryInterval aktivera vilolägesanslutningsresiliens, vilket transparent återställer en anslutning som tappats medan den var inaktiv. De gör inget nytt försök att ansluta initialt, därför innehåller det här kodexemplet även återförsökslogik på applikationsnivå. Behåll båda.

ODBC rapporterar diagnostik genom SQLGetDiagRec snarare än bara returkoden, så klassificera fel innan du försöker igen. Ett autentiserings- eller konfigurationsfel misslyckas sedan omedelbart istället för att förbruka hela återförsöksbudgeten.

Mer information om varje del av den här konfigurationen finns i:

För katalogen över Azure SQL-tillfälliga fel, se tillfälliga felkoder.

Centrala egenskaper

  • Plattformsoberoende: Samma API på Windows, Linux och macOS.
  • Microsoft Entra ID-autentisering: Lösenordslösa anslutningar med hanterad identitet, tjänsteprincip, interaktiva och integrerade flöden.
  • 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

Article Description
Ladda ned ODBC-drivrutinen för SQL Server Installerare och paketnedladdningar för varje stödd drivrutinsversion, på alla tre plattformar.
Utveckla C- och C++-applikationer med ODBC-drivrutinen Vilka headers som ska inkluderas, i vilken ordning, vilka bibliotek som ska länkas och hur man väljer mellan asynkron exekvering och trådar.
Anslut till och kör frågor mot en databas med C++ Ett komplett C++-exempel som kopplar in, kör en fråga och läser resultat, så att du kan bekräfta din setup från början till slut.
Supportlivscykel Vilka drivrutinsversioner som fortfarande stöds, och datumet då varje drivrutin lämnar stödet.
Större skillnader mellan olika versioner Vad går sönder när du går från version 17 till version 18, med början i ändringen av standardinställningen för kryptering.

Installera drivrutinen

Article Description
Systemkrav, installation och drivrutinsfiler (Windows) Stödde Windows-versioner, installationskommandoraden för tyst distribution och var varje drivrutinsfil hamnar på disken.
Systemkrav (Linux och macOS) Vilka Linux-distributioner och macOS-versioner varje drivrutinsversion stödjer, plus kompatibilitet med SQL Server-versionen.
Installera ODBC-drivrutinen på Linux Steg för pakethanterare i Alpine, Debian, Red Hat, SUSE, Ubuntu och Azure Linux, samt offlineinstallation och drivrutinsfilernas placeringar.
Installera ODBC-drivrutinen på macOS Homebrew-tryck och formelsteg för macOS, inklusive hur man installerar version 18, 17 eller 13.1.
Installera unixODBC-drivrutinshanteraren (Linux och macOS) Installera eller uppgradera unixODBC, drivrutinshanteraren som laddar ODBC-drivrutinen på Linux och macOS.

Konfigurera och ansluta

Article Description
Nyckelord och attribut för DSN och anslutningssträngar Den fullständiga katalogen över reťazec pripojenia-nyckelord, DSN-poster och SQLSetConnectAttr attribut, med accepterade värden för varje.
Nyckelord för anslutningssträngar och namn på datakällor (Linux och macOS) Hur odbc.ini och odbcinst.ini definierar en DSN på Linux och macOS, samt de TLS- och TCP-keepalive-inställningar som är specifika för dessa plattformar.
ODBC Data Source Administrator DSN (Windows) Alla alternativ på Windows DSN-guidsidor, för när du konfigurerar en datakälla via UI:t istället för en reťazec pripojenia.
Drivrutinsbaserad anslutningspoolning (Windows) Vilka nyckelord i anslutningssträngen och attribut gör att en anslutning hamnar i en egen pool, och vilka kräver en extra tur och retur för återställning?

Autentisera och säkra

Article Description
Använd Microsoft Entra ID med ODBC-drivrutinen Alla Authentication nyckelordsvärden, från hanterad identitet och tjänsthuvudnamn till interaktiv och integrerad, med den konfiguration som var och en kräver.
Använd Always Encrypted med ODBC-drivrutinen Kryptera känsliga kolumner i klientprocessen så att klartext aldrig når servern, med drivrutinens API-sammanfattning och dess dokumenterade begränsningar.
Dataklassificering Läs känslighetsetiketterna som servern fäster vid klassificerade kolumner, så att din applikation kan upprätthålla sin egen dataskyddspolicy.
Använd integrerad autentisering (Linux och macOS) Konfigurera Kerberos så att en Linux- eller macOS-klient kan ansluta med Windows-uppgifter istället för en SQL Server-inloggning.

Hög tillgänglighet och återhämtning

Article Description
Anslutningsmotståndskraft Hur ConnectRetryCount och ConnectRetryInterval återställer en anslutning när servern kopplar ned den när den är inaktiv, och fel av typen IMCxx som drivrutinen returnerar när återställning inte är möjlig.
Hög tillgänglighet och haveriberedskap Koppla upp dig via en tillgänglighetsgruppslyssnare och använd MultiSubnetFailover så att failover inte stannar vid en subnätstimeout.
Använd transparent nätverks-IP-upplösning Hur den gamla TransparentNetworkIPResolution reservlösningen fördelar anslutningsförsök mellan flera IP-adresser och varför MultiSubnetFailover ersätter den.

Arbeta med data

Article Description
Datatyp för vektor Bind, skicka och hämta vektortypen , inklusive dess inbyggda C-representation och stöd för bulkkopiering.
Använd XA-transaktioner med DTC Registrera SQL Server i en distribuerad transaktion via Microsoft Distributed Transaction Coordinator på Windows, Linux eller macOS.
Programmeringsriktlinjer (Linux och macOS) Vilka funktioner drivrutinen har stöd för i Linux och macOS, vilka den inte har stöd för, och hur hanteringen av teckenuppsättningar och OpenSSL skiljer sig från Windows.

Diagnostisera och felsöka

Article Description
Felsökning av anslutningskryptering Åtgärda certifikat- och krypteringsfel som version 18 visar eftersom den krypterar som standard.
Dataåtkomstspårning (Linux och macOS) Slå på förarspårning och samla in en loggfil när du behöver se vilka anrop din applikation faktiskt gör.
Kända problem (Linux och macOS) Bekräftade defekter och deras lösningar. Kontrollera här innan du skickar in ett supportärende.
Vanliga frågor (Linux och macOS) Korta svar på de frågor som oftast dyker upp om drivrutinen på Linux och macOS.

Versionsanteckningar och buggfixar

Article Description
Versionsnoter för Windows Nya funktioner, beteendeförändringar och fixar i varje Windows-drivrutinsrelease.
Versionsanteckningar för Linux och macOS Nya funktioner, beteendeförändringar och fixar i varje Linux- och macOS-drivrutinsversion.
Versionsanteckningar för SQL Server-verktygen Ändringar i sqlcmd- och bcp-verktygen , som installeras separat från drivrutinen på Linux och macOS.

Reference

Article Description
ODBC-drivrutin på Windows En versions-för-version sammanfattning av vad drivrutinen stödjer på Windows, samt ett index över Windows-specifika artiklar.
Funktioner i ODBC-drivrutinen på Windows Vilken version introducerade varje Windows-funktion, plus de beteendeförändringar som följde med den.

Begär en funktion

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

Relaterat innehåll

  • Last updated on