Sterownik ODBC firmy Microsoft dla programu SQL Server

pobierz sterownika ODBC

ODBC to podstawowy natywny interfejs API dostępu do danych dla aplikacji napisanych w języku C i C++ dla programu SQL Server. Sterownik Microsoft ODBC dla SQL Server łączy się z SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics oraz bazą danych SQL w Microsoft Fabric. Aby uzyskać wersje bazy danych, które obsługuje każda wersja sterownika, zobacz kompatybilność wersji SQL.

Inne języki, które mogą używać ODBC, to COBOL, Perl, PHP i Python. ODBC jest szeroko stosowany w scenariuszach integracji danych, a sterowniki Microsoft for PHP for SQL Server są zbudowane na tym sterowniku.

Narzędzia sqlcmd i bcp działają z tym sterownikiem, ale instalują się osobno: pakiet mssql-tools18 na Linuksie i macOS oraz narzędzia Microsoft Command Line Utilities na Windows. Użyj sqlcmd do uruchamiania Transact-SQL (T-SQL) instrukcji, procedur systemowych i plików skryptów. Użyj bcp do masowego kopiowania danych między instancją SQL Server a plikiem danych, w obu kierunkach.

Wybieranie punktu początkowego

• Aby zainstalować sterownik, przejdź do Wymagania Systemowe, pliki instalacyjne i sterowniki dla Windows, albo Zainstaluj sterownik ODBC na Linuksie, Zainstaluj sterownik ODBC na macOS oraz zainstaluj menedżera sterowników unixODBC.
• Aby napisać swoją pierwszą aplikację, przejdź do artykułów Nawiązywanie połączenia z bazą danych i wykonywanie zapytań przy użyciu języka C++ oraz Słowa kluczowe i atrybuty nazw źródeł danych (DSN) oraz parametrów połączenia.
• Aby połączyć się z Azure SQL z uwierzytelnieniem bez hasła, przejdź do opcji Use Microsoft Entra ID ze sterownikiem ODBC.
• Aby uczynić istniejącą aplikację odporną na przejściowe awarie, przejdź do Odporności na połączenia oraz Wysoka dostępność i odzyskiwanie po awarii.
• Aby zaktualizować wersję 17, przejdź do Główne różnice w wersji oraz Rozwiązywanie problemów z szyfrowaniem połączenia.
• Aby zdiagnozować problem z połączeniem lub zapytaniem, przejdź do sekcji Rozwiązywanie problemów z szyfrowaniem połączenia i Znane problemy (Linux i macOS).

Plan bazowy produkcji dla Azure SQL

Użyj tego fragmentu kodu jako punktu wyjścia dla połączenia zorientowanego na środowisko produkcyjne Azure SQL. Ładuje nazwę serwera i nazwę bazy danych z konfiguracji aplikacji, uwierzytelnia się za pomocą zarządzanej tożsamości, aby żadna tajemnica nie pojawiała się w parametry połączenia, oraz umożliwia szyfrowanie Tabular Data Stream (TDS) 8.0 z pełną weryfikacją certyfikatów. Ustawia limit czasu logowania na każdą próbę i ponownie próbuje przejściowe niepowodzenia z wykładniczym cofnięciem i drżeniem.

Fragment kodu C++ w tym artykule pomija dyrektywy include, alokację uchwytów oraz funkcję pomocniczą do logowania dla zachowania zwięzłości.

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 oraz ConnectRetryInterval umożliwiają odporność połączenia w stanie bezczynności, co automatycznie przywraca połączenie przerwane w stanie bezczynności. Nie ponawiają początkowej próby połączenia, dlatego ten fragment implementuje także mechanizm ponawiania na poziomie aplikacji. Zachowaj oba.

ODBC zgłasza informacje diagnostyczne za pośrednictwem SQLGetDiagRec, a nie wyłącznie za pomocą kodu zwrotnego, więc klasyfikuj błędy przed ponowieniem próby. Wtedy błąd uwierzytelniania lub konfiguracji od razu kończy się niepowodzeniem, zamiast wyczerpywać cały limit ponownych prób.

Aby uzyskać więcej informacji na temat każdej części tej konfiguracji, zobacz:

• Słowa kluczowe i atrybuty DSN oraz ciągu połączenia
• Użyj Microsoft Entra ID z sterownikiem ODBC
• Rozwiązywanie problemów z szyfrowaniem połączenia
• Odporność połączenia
• Wysoka dostępność i odzyskiwanie po awarii

Aby zobaczyć katalog przejściowych błędów Azure SQL, zobacz kody błędów przejściowych.

Kluczowe funkcje

• Cross-platform: To samo API na Windows, Linux i macOS.
• Uwierzytelnianie Microsoft Entra ID: połączenia bezhasłowe z zarządzaną tożsamością, zasadą usługi, interaktywnymi i zintegrowanymi przepływami.
• Ścisłe szyfrowanie: połączenia TDS 8.0 z pełną walidacją certyfikatów w wersjach 18 i nowszych.
• Zawsze szyfrowane: szyfrowanie po stronie klienta dla wrażliwych kolumn, z wsparciem dla niestandardowych dostawców keystore'ów.
• Odporność połączenia: Przejrzyste przywrócenie połączenia, które zerwało się podczas bezczynności.
• Wysoka dostępność: Obsługa detektora grupy dostępności za pomocą MultiSubnetFailover.
• Klasyfikacja danych: Metadane wrażliwości dla kolumn klasyfikowanych.
• Typ danych wektorowych: Natywne wsparcie dla typu wektorowego .
• Transakcje rozproszone: Wsparcie dla transakcji XA poprzez Microsoft Distributed Transaction Coordinator (MSDTC).
• Narzędzia towarzyszące: sqlcmd i bcp, zainstalowane osobno.

Wprowadzenie

Instalowanie sterownika

Konfigurowanie i łączenie

Uwierzytelnianie i zabezpieczenie

Wysoka dostępność i odporność

Praca z danymi

Diagnozowanie i rozwiązywanie problemów

Informacje o wydaniu i poprawki błędów

Reference

Treści powiązane

• Referencja programisty ODBC: Specyfikacja API ODBC, którą ten sterownik implementuje, udokumentowana oddzielnie od sterownika.
• Funkcje natywnego klienta SQL Server: Zachowanie sterowników udokumentowane wyłącznie w treści natywnego klienta. Te artykuły dotyczą sterownika ODBC dla SQL Server, z wyjątkiem miejsc, gdzie opisują OLE DB.
• Narzędzie BCP: Narzędzie do kopiowania masowego, zainstalowane oddzielnie od sterownika.
• Narzędzie sqlcmd: Narzędzie zapytań wiersza poleceń, instalowane oddzielnie od sterownika.
• Macierz wsparcia funkcji sterowników
• Blog sterowników SQL Server