Рекомендации по программированию

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

В этой статье описываются аспекты программирования приложений, использующих драйвер Microsoft ODBC для SQL Server в Linux или macOS. Некоторые ссылки указывают на материалы SQL Server Native Client. Эти страницы предоставляют исторический контекст API.

Выберите версию драйвера

Используйте Microsoft ODBC Driver 18 для SQL Server — текущую линейку драйверов — для новой разработки. Microsoft ODBC Driver 17 for SQL Server остаётся поддерживаемым для приложений, в которых он уже развернут, как описано в жизненном цикле поддержки. Драйвер ODBC 13, поставлявшийся с SQL Server 2017, имеет право на расширенную поддержку до 12 октября 2027 года только по расширенному соглашению о поддержке.

Укажите имя установленного драйвера в вашей строке подключения, заключённой в скобки:

Driver={ODBC Driver 18 for SQL Server}

Driver={ODBC Driver 17 for SQL Server}

В имени источника данных (DSN) в odbc.ini, используйте имя без фигурных скобок, например Driver = ODBC Driver 18 for SQL Server. Для синтаксиса DSN см. Ключевые слова строк соединения и имена источников данных (DSN).

Для параметров соединения, специфичных для версии, см. раздел «Основные различия в версиях». Для дат поддержки и совместимости операционных систем см. Жизненный цикл поддержки и системные требования.

Создайте приложение

Сведения о расположении файлов заголовков, порядке, командах компилятора, именах библиотек и примере на C++ см. в Разработка приложений C и C++ с драйвером ODBC и Подключение и выполнение запросов с помощью C++ и ODBC.

Приложение ODBC может использовать несколько активных наборов результатов (MARS) и другие специфические для SQL Server функции, добавляя msodbcsql.h после заголовков unixODBC (sql.h, sqlext.h, sqltypes.h, и sqlucode.h). Используйте те же символические имена для специфических для SQL Server элементов, что и в приложениях Windows ODBC.

Найти возможности драйвера

Начните с справочника программиста ODBC для стандартного интерфейса прикладного программирования (API). Затем используйте текущую документацию драйвера для поведения конкретного драйвера.

Обзор Microsoft ODBC Driver for SQL Server ссылается на документацию к драйверу. Следующие статьи SQL Server Native Client предоставляют контекст API для приложений, использующих этот драйвер на Linux и macOS:

Limitations

Следующие функции не были проверены на корректную работу в драйвере ODBC на Linux и macOS:

Неподдерживаемые функции

Следующие функции недоступны в драйвере ODBC на Linux и macOS:

  • Распределённые транзакции через атрибут SQL_ATTR_ENLIST_IN_DTC . Драйвер поддерживает транзакции XA через координатор распределенных транзакций (Майкрософт) (DTC). Для получения дополнительной информации см. Использование транзакций XA с DTC.

  • Зеркалирование базы данных.

  • FILESTREAM.

  • Профилирование производительности драйверов ODBC рассматривается в SQLSetConnectAttr, а также в следующих атрибутах подключения, связанных с производительностью:

    • SQL_COPT_SS_PERF_DATA
    • SQL_COPT_SS_PERF_DATA_LOG
    • SQL_COPT_SS_PERF_DATA_LOG_NOW
    • SQL_COPT_SS_PERF_QUERY
    • SQL_COPT_SS_PERF_QUERY_INTERVAL
    • SQL_COPT_SS_PERF_QUERY_LOG

  • SQLBrowseConnect до версии 17.2.

  • Типы интервалов C, такие как SQL_C_INTERVAL_YEAR_TO_MONTH, задокументированы в идентификаторах и дескрипторах типов данных.

  • Значение SQL_CUR_USE_ODBCатрибута SQL_ATTR_ODBC_CURSORS объекта SQLSetConnectAttr.

Обрабатывать символьные данные

В Linux и macOS используйте буферы UTF-16 SQLWCHAR с API широких символов ODBC вместо родного wchar_t типа. Интерфейс драйвера использует 16-битные кодовые единицы.

Кодировки символов

Для ODBC Driver 13 и 13.1 необходимо использовать UTF-8 для данных SQLCHAR. Эти версии не поддерживают никакие другие кодировки.

Начиная с драйвера ODBC 17, поддерживаемые наборы символов и кодировки данных SQLCHAR включают:

Примечание.

Из-за iconv различий между musl и glibc, многие из этих локалов не поддерживаются на Alpine Linux. Для получения дополнительной информации см. Функциональные различия от glibc.

Имя Описание
UTF-8 Unicode
CP437 MS-DOS латиница (США)
CP850 MS-DOS Латинская 1
CP874 Латиница/тайский
CP932 Японский (код Windows, страница 932)
CP936 Китайский (упрощенный), GBK
CP949 Корейский (кодовая страница Windows 949)
CP950 Китайский (традиционный), Big5
CP1250 Центральноевропейская
CP1251 Кириллица
CP1252 Западная Европа
CP1253 Греческий
CP1254 Турецкий
CP1255 Иврит
CP1256 Арабский
CP1257 Балтийская
CP1258 Вьетнамский
ISO-8859-1 Латиница-1
ISO-8859-2 Латиница-2
ISO-8859-3 Латиница-3
ISO-8859-4 Латиница-4
ISO-8859-5 Латиница/кириллица
ISO-8859-6 Латиница/арабский
ISO-8859-7 Латиница/греческий алфавит
ISO-8859-8 Иврит
ISO-8859-9 Турецкий
ISO-8859-13 Latin-7
ISO-8859-15 Латиница-9

Когда вы подключаетесь, драйвер определяет текущий локал процесса, в котором он загружен. Если локаль использует одну из указанных кодировок, драйвер использует эту кодировку для SQLCHAR данных с узкими символами. В противном случае по умолчанию используется UTF-8. Процессы по умолчанию начинаются в локали C, что приводит к тому, что драйвер по умолчанию использует UTF-8. Если приложению нужна одна из указанных кодировок, вызовите setlocale перед подключением. Укажите локаль явно или используйте пустую строку (например setlocale(LC_ALL, ""), ) для использования параметров локации среды.

В типичной среде Linux или macOS, где кодировка UTF-8, пользователи ODBC Driver 17, обновляющие с 13 или 13.1, не заметят различий. Приложения, использующие через setlocale перечисленное не-UTF-8 кодирование, должны использовать это кодирование для передачи данных к драйверу и обратно вместо UTF-8.

Для SQLWCHAR данных необходимо использовать UTF-16LE (с прямым порядком байтов).

Когда вы привязываете входные параметры с помощью SQLBindParameter, если вы задаёте узкий тип символа SQL, например SQL_VARCHAR, драйвер преобразует предоставленные данные из клиентского кодирования в серверное кодирование для этого параметра. Кодировка зависит от сопоставления; и это не всегда кодовая страница 1252. Выходные параметры драйвер преобразует из кодировки, указанной в сведениях о параметрах сортировки, связанных с данными, в кодировку клиента. Символы в исходном кодировании, которые не могут быть представлены в целевом кодировании, преобразуются в вопросительный знак (?).

Чтобы избежать потери данных при привязке входных параметров, укажите тип символа SQL-Unicode, например SQL_WVARCHAR. Драйвер преобразует кодировку клиента в UTF-16, который может представлять все символы Unicode. Целевой столбец или параметр также должны иметь тип Unicode (nchar, nvarchar или ntext) или тип с параметрами сортировки либо кодировкой, которые позволяют представить все исходные данные. Для выходных параметров укажите тип SQL Unicode и либо тип C Unicode (SQL_C_WCHAR), который заставляет драйвер возвращать данные как UTF-16, либо узкий тип C с клиентским кодированием, которое может представлять исходные данные. UTF-8 всегда может представлять эти данные.

Для получения дополнительной информации о параметрах сортировки и кодировках см. раздел «Параметры сортировки и поддержка Unicode».

Существуют различия в конвертации между версиями Windows и Linux или macOSiconv:

  • Для кодовой страницы 1255 байт 0xCA преобразуется в кодовую точку UTF-16 0x05BA в Windows, а в macOS и Linux — в 0x00CA в версиях libiconv ниже 1.15.
  • Библиотеки Linux iconv без редакции Big5/CP950 2003 года (BIG5-2003) некорректно конвертируют символы, добавленные в этой редакции.
  • Для кодовой страницы 932 (японский, Shift-JIS) декодирование символов, не определённых в стандарте кодирования, отличается. Например, байт 0x80 преобразуется в U+0080 на Windows и может стать U+30FB на Linux и macOS, в зависимости от версии iconv.

В драйверах ODBC 13 и 13.1 разделение многобайтовых символов UTF-8 или суррогатов UTF-16 между SQLPutData буферами приводит к повреждению данных. Используйте потоковые буферы, которые не заканчиваются частичным кодированием символов. Это ограничение было удалено в ODBC Driver 17.

Рекомендации по кодировке символов, преобразованию, привязке параметров и размеру буфера см. в разделе «Известные проблемы».

OpenSSL

Начиная с ODBC Driver 17.4, драйвер динамически загружает OpenSSL, что позволяет драйверу работать на системах с версией 1.0 или 1.1 без отдельных файлов драйвера. Начиная с версии 17.9, драйвер поддерживает OpenSSL 3.0 в дополнение к предыдущим версиям. Когда присутствует несколько версий OpenSSL, драйвер пытается загрузить поддерживаемую версию из путей поиска библиотек.

Версия драйвера Поддерживаемые версии OpenSSL
17.4–17.8 1.0, 1.1
Версии 17.9 и более поздние версии 17.x, а также все версии Driver 18 1.0, 1.1, 3.0

OpenSSL 4 не поддерживается. На macOS ссылка Homebrew openssl, ведущая на OpenSSL 4, может помешать драйверу загрузить OpenSSL, даже если установлен OpenSSL 3. Проверьте путь к библиотеке, а также установленные версии.

Примечание.

Потенциальный конфликт может возникнуть, если приложение, использующее драйвер, или один из его компонентов компонуется с другой версией OpenSSL или динамически загружает её. Если в системе есть несколько версий OpenSSL и приложение использует её, убедитесь, что версия, загруженная приложением, и драйвер не расходятся. Ошибки могут вызвать повреждение памяти и могут никак явно или последовательно не проявляться.

Alpine Linux

Размер стека по умолчанию для новых потоков в musl составляет 128 КБ, если только исполняемый файл не запрашивает большее значение по умолчанию. Поток может превысить этот предел при вызове драйвера. Свяжите ODBC-приложение на Alpine Linux с -Wl,-z,stack-size=<size_in_bytes>, чтобы запросить больший размер стека потока по умолчанию. Приложения, создающие потоки с явным размером стека, также должны выбирать подходящий размер для этих потоков.

Стек основного потока и стек по умолчанию для новых потоков — это не одна и та же настройка. В glibc системах по умолчанию для новых потоков обычно используется ограничение ресурсов стека процесса, с запасным вариантом, зависящим от архитектуры, когда этот лимит неограничен. Не предполагайте, что во всех системах Linux значение по умолчанию фиксировано и составляет 2 МБ.

Дополнительные примечания

Чтобы создать выделенное административное соединение (DAC) из ODBC-приложения, установите Server=tcp:<server>,<dac_port>Dedicated Administrator Connection=trueServer=tcp:<server>,<dac_port> в строке подключения. Используйте обнаруженный порт DAC, а не обычный порт подключения экземпляра. Например, если порт ЦАП равен 33000, установите Server=tcp:<server>,33000. Эти фрагменты строк соединения указывают только конечную точку, а не аутентификацию. Настраивайте аутентификацию и проверку серверных сертификатов отдельно.

Логин должен быть членом серверной роли sysadmin. Для удалённого доступа должна быть включена опция удалённых администраторских соединений сервера. Для получения требований к доступу, конфигурации сервера и процедур администрирования командной строки см. раздел Диагностическое соединение для администраторов баз данных. Для обнаружения портов см. порт DAC.

Менеджер драйверов unixODBC обрабатывает атрибуты инструкций, передаваемые через SQLSetConnectAttr, так же, как и менеджер драйверов Windows. Параметры инструкций ODBC 2.x, такие, как SQL_ATTR_QUERY_TIMEOUT и SQL_ATTR_MAX_ROWS, применяются к существующим и новым инструкциям в соединении. Атрибуты только операторов ODBC 3.x, такие SQL_ATTR_ROW_ARRAY_SIZE как и SQL_ATTR_PARAMSET_SIZE, возвращают SQLSTATE HY092. Атрибуты, определённые как на уровне соединения, так и на уровне инструкции, такие как SQL_ATTR_METADATA_ID, могут быть установлены на любом из этих уровней. Установка атрибутов, предназначенных только для операторов, на уровне соединения устарела в ODBC 3.x, поэтому вместо этого используйте вызов SQLSetStmtAttr. Для получения дополнительной информации см. функция SQLSetConnectAttr.

В высоко-многопоточных приложениях проверка дескрипторов unixODBC может стать узким местом производительности. Компиляция unixODBC с --enable-fastvalidate может повысить производительность. Однако эта опция может привести к сбоям приложений, передающих недействительные дескрипторы в API ODBC, вместо того чтобы возвращать SQL_INVALID_HANDLE.

Сведения об установке и настройке платформы см.:

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

  • Последнее обновление: