Драйвер Microsoft ODBC для SQL Server

Скачать драйвер ODBC

ODBC — это основной собственный интерфейс API для доступа к данным, предназначенный для приложений, написанных на языках C и C++ для SQL Server. Драйвер Microsoft ODBC для SQL Server подключается к SQL Server, База данных SQL Azure, Управляемый экземпляр SQL Azure, Azure Synapse Analytics и базе данных SQL в Microsoft Fabric. Для версий базы данных, поддерживаемых каждым драйвером, см. совместимость версий SQL.

К другим языкам, которые могут использовать ODBC, относятся COBOL, Perl, PHP и Python. ODBC широко используется в сценариях интеграции данных, и драйверы Microsoft для PHP для SQL Server построены на этом драйвере.

Утилиты sqlcmd и bcp работают с этим драйвером, но устанавливаются отдельно: mssql-tools18 пакет на Linux и macOS, а также утилиты командной строки Microsoft на Windows. Используйте sqlcmd для запуска операторов Transact-SQL (T-SQL), системных процедур и скриптов. Используйте bcp для массового копирования данных между экземпляром SQL Server и файлом данных, в любом направлении.

Выберите начальную точку

Производственные базовые показатели для Azure SQL

Используйте этот фрагмент в качестве отправной точки для рабочего Azure SQL подключения. Он загружает имя сервера и имя базы данных из конфигурации приложения, аутентифицируется с управляемой идентичностью так, чтобы секрет не отображался в строка подключения, и поддерживает шифрование Tabular Data Stream (TDS) 8.0 с полной валидацией сертификата. Задаёт тайм-аут для каждой попытки входа и повторяет попытки при временных ошибках с экспоненциальной задержкой и случайным разбросом.

В этом фрагменте кода на C++, приведённом в статье, для краткости опущены директивы include, выделение дескриптора и вспомогательная функция для логирования.

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, а не только через код возврата, поэтому классифицируйте ошибки, прежде чем повторять попытку. Ошибка аутентификации или конфигурации сразу же выходит из строя, вместо того чтобы потрачить весь бюджет на повторные попытки.

Дополнительные сведения о каждой части этой конфигурации см. в следующей статье:

Список временных ошибок Azure SQL см. в разделе коды ошибок временных сбоев.

Ключевые особенности

  • Кроссплатформенность: тот же API на Windows, Linux и macOS.
  • Аутентификация Microsoft Entra ID: Подключения без пароля с управляемой идентификацией, принципом сервиса, интерактивными и интегрированными потоками.
  • Строгое шифрование: подключения TDS 8.0 с полной валидацией сертификата в версиях 18 и позднее.
  • Always Encrypted: клиентское шифрование для конфиденциальных столбцов с поддержкой пользовательских поставщиков хранилищ ключей.
  • Устойчивость соединения: Прозрачное восстановление соединения, которое оторвалось во время простоя.
  • Высокая доступность: поддержка прослушивателя группы доступности с MultiSubnetFailover.
  • Классификация данных: Метаданные чувствительности для классифицированных столбцов.
  • Векторный тип данных: нативная поддержка векторного типа.
  • Распределённые транзакции: поддержка транзакций XA через координатор распределенных транзакций (Майкрософт) (MSDTC).
  • Сопутствующие инструменты: sqlcmd и bcp, устанавливаются отдельно.

Начало работы

Статья Description
Скачайте драйвер ODBC для SQL Server Установщики и пакеты для загрузки для всех поддерживаемых версий драйверов на всех трёх платформах.
Подключитесь к базе данных и отправьте к ней запрос на C++ Полный сэмпл на C++, который подключается, выполняет запрос и читает результаты, чтобы вы могли подтвердить свою настройку от конца до конца.
Жизненный цикл поддержки Какие версии драйверов всё ещё поддерживаются, и дата прекращения поддержки каждой из них.
Различия между мажорными версиями Что ломается при переходе с версии 17 на версию 18, начиная с изменения по умолчанию шифрования?

Установка драйвера

Статья Description
Системные требования, установка и файлы драйверов (Windows) Поддерживаемые версии Windows, командная строка установщика для тихого развертывания и место, где каждый файл драйвера попадает на диск.
Системные требования (Linux и macOS) Какие дистрибутивы Linux и релизы macOS поддерживают каждая версия драйверов, плюс совместимость версий SQL Server.
Установите драйвер ODBC на Linux Шаги менеджера пакетов для Alpine, Debian, Red Hat, SUSE, Ubuntu и Azure Linux, а также офлайн-установка и расположение файлов драйверов.
Установите драйвер ODBC на macOS Шаги для tap-репозитория и формулы Homebrew в macOS, включая инструкции по установке версий 18, 17 или 13.1.
Установите менеджер драйверов unixODBC (Linux и macOS) Установите или обновите unixODBC — менеджер драйверов, который загружает драйвер ODBC на Linux и macOS.

Настройка и подключение

Статья Description
Ключевые слова и атрибуты DSN и строки подключения Полный каталог ключевых слов строк подключения, записей DSN и атрибутов SQLSetConnectAttr с допустимыми значениями для каждого из них.
Ключевые слова для строк соединения и имена источников данных (Linux и macOS) Как odbc.ini и odbcinst.ini настроить DSN в Linux и macOS, а также параметры TLS и TCP keep-alive для этих платформ.
Администратор источников данных ODBC DSN (Windows) Все параметры на страницах мастера DSN в Windows при настройке источника данных через пользовательский интерфейс, а не с помощью строки подключения.
Пул соединений с учётом драйвера (Windows) Какие ключевые слова и атрибуты строка подключения помещают соединение в отдельный пул, а какие требуют дополнительного сброса.

Аутентифицировать и защитить

Статья Description
Используйте Microsoft Entra ID с драйвером ODBC Каждое Authentication значение ключевого слова — от управляемой идентичности и принципа сервиса до интерактивных и интегрированных, с необходимой каждой системой.
Используйте Always Encrypted с драйвером ODBC Шифруйте чувствительные столбцы в клиентском процессе, чтобы открытый текст никогда не доходил до сервера, с описанием API драйвера и его задокументированными ограничениями.
Классификация данных Считывать метки конфиденциальности, которые сервер назначает классифицированным столбцам, чтобы приложение могло применять собственную политику защиты данных.
Используйте интегрированную аутентификацию (Linux и macOS) Настройте Kerberos так, чтобы клиент Linux или macOS мог подключаться к учетным данным Windows вместо входа через SQL Server.

Высокий уровень доступности и устойчивость

Статья Description
Устойчивость подключения Как ConnectRetryCount и ConnectRetryInterval восстанавливают соединение, когда сервер разрывает его во время простоя, и какие IMCxx ошибки возвращает драйвер, когда восстановление невозможно.
Высокий уровень доступности и аварийное восстановление Подключайтесь через прослушиватель группы доступности и используйте MultiSubnetFailover, чтобы переключение при отказе не зависало из-за тайм-аута подсети.
Используйте прозрачное разрешение сетевых IP-адресов Как устаревший TransparentNetworkIPResolution запасной вариант упорядочивает попытки подключения по нескольким IP-адресам и почему MultiSubnetFailover он превосходит его.

Работа с данными

Статья Description
Векторный тип данных Привязать, отправить и получить тип vector, включая его нативное представление на C и поддержку пакетного копирования.
Используйте транзакции XA с DTC Зарегистрируйте SQL Server в распределённой транзакции через координатор распределенных транзакций (Майкрософт) на Windows, Linux или macOS.
Руководство по программированию (Linux и macOS) Какие функции драйвера поддерживают в Linux и macOS, а что нет, и чем отличается набор символов и обработка OpenSSL от Windows.

Диагностика и устранение неполадок

Статья Description
Устранение неполадок шифрования соединения Исправьте ошибки сертификата и шифрования, которые появляются в версии 18, потому что она шифрует по умолчанию.
Трассировка доступа к данным (Linux и macOS) Включите трассировку драйверов и зафиксируйте файл журнала, когда вам нужно увидеть, какие вызовы действительно совершает ваше приложение.
Известные проблемы (Linux и macOS) Подтверждённые дефекты и их обходные пути. Проверьте здесь, прежде чем подавать заявление в поддержку.
Часто задаваемые вопросы (Linux и macOS) Краткие ответы на вопросы, которые чаще всего возникают о драйвере на Linux и macOS.

Примечания к релизу и исправления ошибок

Статья Description
Заметки к релизу для Windows Новые функции, изменения поведения и исправления в каждом выпуске драйверов Windows.
Заметки к релизу для Linux и macOS Новые функции, изменения поведения и исправления в каждом выпуске драйверов Linux и macOS.
Заметки к релизу инструментов SQL Server Изменения в утилитах sqlcmd и bcp , которые устанавливаются отдельно от драйвера на Linux и macOS.

Ссылки

Статья Description
Драйвер ODBC на Windows Обзор версий по версиям того, что поддерживает драйвер в Windows, и индекс статей, специфичных для Windows.
Особенности драйвера ODBC в Windows В каком релизе появились все функции Windows, а также изменения в поведении, связанные с ней.

Связанные материалы

  • Last updated on