微軟 SQL Server 的 ODBC 驅動程式

下載 ODBC 驅動程式

ODBC 是以 C 及 C++ 撰寫之 SQL Server 應用程式的主要原生資料存取 API。 Microsoft ODBC 的 SQL Server 驅動程式可連接 SQL Server、Azure SQL Database、Azure SQL 受控執行個體、Azure Synapse Analytics 以及 Microsoft Fabric 中的 SQL 資料庫。 關於每個驅動版本所支援的資料庫版本，請參見 SQL 版本相容性。

可以使用 ODBC 的其他語言包括 COBOL、Perl、PHP 和 Python。 ODBC 廣泛應用於資料整合情境，Microsoft PHP for SQL Server 驅動程式即基於此驅動程式。

sqlcmd 和 bcp 公用程式可搭配此驅動程式使用，但需另外安裝：在 Linux 和 macOS 上為 mssql-tools18 套件，在 Windows 上為 Microsoft Command Line Utilities。 使用 sqlcmd 執行 Transact-SQL（T-SQL）語句、系統程序及腳本檔案。 使用 bcp 在 SQL Server 實例與資料檔案之間批量複製資料，無論雙向皆然。

選擇你的起點

• 要安裝驅動程式，請前往 Windows 的系統需求、安裝與驅動程式檔案，或在 Linux 安裝 ODBC 驅動程式，在 macOS 安裝 ODBC 驅動程式，然後安裝 unixODBC 驅動程式管理器。
• 要寫第一個應用程式，請先到 Connect to 並用 C++ 查詢資料庫，然後輸入 DSN 和 連接字串 關鍵字及屬性，選擇 連接字串 選項。 如果你的編譯器找不到標頭，或是你的建置無法連結，請用 ODBC 驅動程式進入 Develop C 和 C++ 應用程式。
• 若要使用無密碼驗證連線至 Azure SQL，請前往 搭配 ODBC 驅動程式使用 Microsoft Entra ID。
• 要讓現有應用程式對暫時性故障具備韌性，請參考 Connection 韌性 與 高可用性與災難復原。
• 要從版本 17 升級，請前往 主要版本差異 與 連線加密故障排除。
• 要診斷連線或查詢問題，請前往連線加密故障排除和已知問題（Linux 和 macOS）。

Azure SQL 的生產環境基準

請使用此片段作為生產導向 Azure SQL 連線的起點。 它從應用程式設定載入伺服器名稱與資料庫名稱，並以管理身份驗證，確保 連接字串 中不出現秘密，並啟用 Tabular Data Stream（TDS）8.0 加密及完整憑證驗證。 它會設定每次登入嘗試的逾時時間，並以指數退避和隨機抖動機制重試暫時性錯誤。

本文中的 C++ 摘要為簡潔起見，省略了 include、handle allocation 和 log helper。

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 並 ConnectRetryInterval 啟用 閒置連線韌性，透明地恢復閒置時斷線的連線。 它們不會重試初始連線，這也是為什麼這個片段同時實作應用程式層級的重試。 兩者都保留。

ODBC 會透過 SQLGetDiagRec 回報診斷資訊，而不是僅靠回傳碼，因此在重試前應先將失敗分類。 驗證或設定錯誤會立即失敗，而不會消耗整個重試預算。

關於此配置各部分的更多資訊，請參見：

• DSN 與連接字串關鍵字與屬性
• 使用 Microsoft Entra ID 搭配 ODBC 驅動程式
• 連線加密故障排除
• 連線韌性
• 高可用性與災難復原

關於 Azure SQL 暫態錯誤的目錄，請參見暫態故障錯誤碼。

主要功能

• 跨平台：Windows、Linux 和 macOS 使用相同的 API。
• Microsoft Entra ID 認證：無密碼連線，包含管理身份、服務主體、互動式及整合流程。
• 嚴格加密：在第 18 版及更新版本中，TDS 8.0 連線會採用完整的憑證驗證。
• 始終加密：用戶端加密以處理敏感欄位，並支援自訂金鑰儲存提供者。
• 連線復原能力：可透明地重新建立在閒置時中斷的連線。
• 高可用性：可用性群組監聽器支援。MultiSubnetFailover
• 資料分類：分類欄位的敏感性元資料。
• 向量資料型別：原生支援 向量 型別。
• 分散式交易：透過 Microsoft Distributed Transaction Coordinator（MSDTC）支援 XA 交易。
• 配套工具： sqlcmd 和 bcp，分別安裝。

開始

安裝驅動程式

設定和連線

認證與安全

高可用性與韌性

處理資料

診斷和疑難解答

發行說明與錯誤修正

Reference

提出功能要求

若要請求功能，請透過 SQL Server 回饋提交想法。

相關內容

• ODBC 程式設計師參考：本驅動程式實作的 ODBC API 規範，與驅動程式分開文件。
• SQL Server 原生客戶端功能：驅動程式行為僅記錄於原生客戶端內容中。 這些文章適用於 SQL Server 的 ODBC 驅動程式，除非描述 OLE DB。
• BCP 工具：批量複製工具，與驅動程式分開安裝。
• SQLcmd 工具：命令列查詢工具，與驅動程式分開安裝。
• 驅動程式功能支援矩陣
• SQL Server 驅動程式部落格