本記事では、Linux または macOS 上で Microsoft ODBC Driver for SQL Server を使用するアプリケーションにおけるプログラミング上の考慮事項について説明します。 一部のリンクはSQL Server Native Client に関するコンテンツを参照しています。 これらのページはAPIの歴史的背景を説明します。
ドライバーバージョンを選択する
新しい開発には、現行のドライバー系統である SQL Server 用 Microsoft ODBC Driver 18 を使用してください。 Microsoft ODBC Driver 17 for SQL Serverは、サポート ライフサイクルで説明されているとおり、既に導入しているアプリケーションに対して引き続きサポートされています。 SQL Server 2017に付属したODBCドライバー13は、2027年10月12日までの延長サポートの対象となりますが、これは延長サポート契約のもとに限られます。
接続文字列でインストール済みドライバー名を括弧で囲み込んで明記してください:
Driver={ODBC Driver 18 for SQL Server}
Driver={ODBC Driver 17 for SQL Server}
odbc.iniのデータソース名(DSN)では、波かっこなしの名前(例えばDriver = ODBC Driver 18 for SQL Server)を使います。 DSNの構文については、 接続文字列キーワードおよびデータソース名(DSN)を参照してください。
バージョンごとの接続設定については、メジャーバージョンの違いを参照してください。 サポート日およびオペレーティングシステムの互換性については、 サポートライフサイクル および システム要件を参照してください。
アプリケーションを構築する
ヘッダーの場所、順序、コンパイラ コマンド、ライブラリ名、C++ のサンプルについては、「ODBC ドライバーで C および C++ アプリケーションを開発」および「C++ と ODBC で接続してクエリを実行する」を参照してください。
ODBCアプリケーションは、unixODBCヘッダー(sqlext.h、sqltypes.h、sqlucode.h、msodbcsql.h)の後にsql.hを含めることで、MARS (Multiple Active Result Sets) やその他のSQL Server固有の機能を利用できます。 WindowsのODBCアプリケーションで使うのと同じSQL Server固有アイテムのシンボル名を使いましょう。
ドライバー機能を確認
標準アプリケーションプログラミングインターフェース(API)については、まず ODBCプログラマーズリファレンス を参照してください。 その後、現在のドライバーのドキュメントを使ってドライバー固有の動作を確認してください。
Microsoft ODBC Driver for SQL Serverの概要にはドライバーのドキュメントがリンクされています。 以下のSQL Serverネイティブクライアントの記事は、LinuxおよびmacOSでこのドライバーを使用するアプリケーションのためのAPIコンテキストを提供します。
- SQL Server との通信 (ODBC)
- 接続とクエリのタイムアウトのサポート
- カーソル
- 日付/時刻の改善 (ODBC)
- クエリ実行 (ODBC)
- エラーとメッセージの処理
- Kerberos 認証
- 大規模共通言語ランタイム(CLR)ユーザー定義型(ODBC)
- トランザクションの実行 (ODBC)。 LinuxやmacOSでの分散トランザクションには、DTC と共に XA トランザクションを使用してください。
- 処理結果 (ODBC)
- ストアド プロシージャの実行
- スパース カラムのサポート (ODBC)
- 検証を行わずに暗号化を使用する
- テーブル値パラメーター
- コマンドおよびデータAPI用のUTF-8およびUTF-16
- カタログ関数の利用
制限
以下の機能はLinuxおよびmacOSのODBCドライバーで正しく動作することが確認されていません:
- フェイルオーバークラスター接続。
- 透過ネットワークIP解決は ODBC Driver 17 より前。
- Linux および macOS の ODBC ドライバー Built-In 診断 (BID) トレーシング (ODBC ドライバー 17.3 より前)
サポートされていない機能
以下の機能はLinuxおよびmacOSのODBCドライバーでは利用できません。
SQL_ATTR_ENLIST_IN_DTC属性を通じた分散トランザクション。 このドライバはMicrosoft 分散トランザクション コーディネーター(DTC)を通じてXAトランザクションをサポートしています。 詳細については、DTC で XA トランザクションを使用するをご覧ください。データベース ミラーリング
FILESTREAM。
SQLSetConnectAttrで説明されているODBCドライバーのパフォーマンスのプロファイリング、および次のパフォーマンス関連の接続属性:
SQL_COPT_SS_PERF_DATASQL_COPT_SS_PERF_DATA_LOGSQL_COPT_SS_PERF_DATA_LOG_NOWSQL_COPT_SS_PERF_QUERYSQL_COPT_SS_PERF_QUERY_INTERVALSQL_COPT_SS_PERF_QUERY_LOG
SQLBrowseConnectバージョン 17.2 より前SQL_C_INTERVAL_YEAR_TO_MONTHのようなC interval 型は、データ型識別子およびディスクリプタで文書化されています。SQL_CUR_USE_ODBCのSQL_ATTR_ODBC_CURSORS属性のSQLSetConnectAttr値。
文字データの処理
LinuxおよびmacOSでは、ネイティブSQLWCHARタイプではなく、ODBCワイド文字API付きのUTF-16 wchar_tバッファを使用してください。 ドライバーインターフェースは16ビットコード単位を使用しています。
文字エンコーディング
ODBCドライバー13および13.1では、 SQLCHAR データにはUTF-8を使用する必要があります。 これらのバージョンは他のエンコーディングをサポートしていません。
ODBCドライバー17から、サポートされている文字セットおよび SQLCHAR データのエンコーディングには以下が含まれます:
注
glibcとiconvの違いmuslため、これらの多くのロケールは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 | ラテン-7 |
| ISO-8859-15 | ラテン-9 |
接続すると、ドライバーは読み込まれているプロセスの現在のロケールを検出します。 ロケールが記載されたエンコーディングのいずれかを使用している場合、ドライバーはそのエンコーディングを SQLCHAR (狭文字)データに使用します。 それ以外の場合は、デフォルトでUTF-8になります。 プロセスはデフォルトで C 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_VARCHARのような狭文字SQL型を指定した場合、ドライバーは提供されたデータをクライアントのエンコーディングからそのパラメータのサーバー側エンコーディングに変換します。 エンコーディングはコレーションに依存します。必ずしもコードページ1252ではありません。 出力パラメーターの場合、ドライバーでは、データに関連付けられている照合順序情報に指定されたエンコードからクライアントのエンコードに変換されます。 ソースエンコーディング内の、ターゲットエンコーディングで表現できない文字は、クエスチョンマーク (?) に変換されます。
入力パラメータをバインディングする際のデータ損失を避けるために、 SQL_WVARCHARのようなUnicodeのSQL文字型を指定します。 ドライバーはクライアントのエンコーディングをUTF-16に変換します。UTF-16は、すべてのUnicode文字を表現できます。 ターゲットの列やパラメータは、Unicode型(nchar、 nvarchar、 またはntext)か、すべての元のソースデータを表現できるコレーションやエンコーディングを持つ型でなければなりません。 出力パラメータとして、Unicode の SQL 型と、Unicode C 型 (SQL_C_WCHAR)（この場合、ドライバーはデータを UTF-16 として返します）、またはソースデータを表現できるクライアント エンコーディングを持つ狭い C 型のいずれかを指定します。 UTF-8は常にこのデータを表現できます。
照合やエンコーディングの詳細については、「 照合とUnicodeのサポート」を参照してください。
WindowsとLinuxやmacOSのiconvバージョン間には変換の違いがあります:
- コードページ1255では、バイト
0xCAがWindowsではUTF-16コードポイント0x05BAに変換され、macOSやLinuxでは、0x00CAのバージョンが1.15より前の場合はlibiconvに変換されます。 - Linux
BIG5-2003ライブラリは、2003年のBig5/CP950リビジョン（iconv）を使わない場合、そのリビジョンで追加された文字を正しく変換しません。 - コードページ932(日本語、Shift-JIS)では、符号化標準で定義されていない文字の復号が異なります。 例えば、Windowsではバイト
0x80がU+0080に変換され、LinuxやmacOSではiconvバージョンによってU+30FBになることがあります。
ODBCドライバー13および13.1では、UTF-8マルチバイト文字やUTF-16サロゲートを SQLPutData バッファ間で分割するとデータ破損が生じます。 部分的な文字エンコーディングで終わらないストリーミングバッファを使いましょう。 この制限はODBCドライバー17で撤廃されました。
文字エンコーディング、変換、パラメータバインディング、バッファサイズのガイダンスについては 既知の問題 を参照してください。
OpenSSL
ODBCドライバー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 3がインストールされていてもドライバーがOpenSSLを読み込めないことがあります。 ライブラリのパスとインストール済みのバージョンの両方を確認してください。
注
ドライバーを使用するアプリケーション、またはそのコンポーネントが、異なるバージョンのOpenSSLにリンクするか、動的に読み込むと、潜在的な競合が発生する可能性があります。 システム上に複数のOpenSSLバージョンが存在し、アプリケーションがそれを使用している場合は、アプリケーションによって読み込まれるバージョンとドライバーによって読み込まれるバージョンが一致するようにしてください。 エラーはメモリを破損させる可能性があり、明確または一貫した形で現れない場合もあります。
Alpine Linux
muslの新しいスレッドのデフォルトスタックサイズは128 KBで、実行ファイルがより大きいデフォルトスタックサイズを要求する場合を除きます。 スレッドはドライバーを呼び出す際にこの制限を超えることがあります。 Alpine Linux上のODBCアプリケーションを -Wl,-z,stack-size=<size_in_bytes> とリンクして、より大きなデフォルトスレッドスタックを要求できるようにします。 明示的なスタックサイズを指定して作成するスレッドを作成するアプリケーションは、それらのスレッドに適したサイズも選択しなければなりません。
メインスレッドのスタックと新しいスレッドのデフォルトスタックは同じ設定ではありません。
glibcシステムでは、新しいスレッドのデフォルトは通常、プロセスのスタックリソース制限に従い、その制限が無制限の場合はアーキテクチャ固有のフォールバックが適用されます。 Linuxシステム間で共通の固定された2 MBのデフォルトがあると想定しないでください。
その他のメモ
ODBCアプリケーションから専用管理者接続(DAC)を作成するには、接続文字列でServer=tcp:<server>,<dac_port>を設定してください。 インスタンスの通常の接続ポートではなく、発見されたDACポートを使ってください。 例えば、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付きでコンパイルすると、パフォーマンスが向上するかもしれません。 しかし、このオプションは無効なハンドルをODBC APIに渡すアプリケーションが SQL_INVALID_HANDLEを返す代わりにクラッシュする恐れがあります。
プラットフォームの設置および構成手順については、以下をご覧ください:
- LinuxにODBCドライバーをインストールしてください。
- macOSにODBCドライバーをインストールしてください。
- unixODBCドライバーマネージャーをインストールしてください。
- 接続文字列とDSNを設定しましょう。
- システム要件を確認する。