DSN と接続文字列のキーワードおよび属性

この記事では、接続文字列やDSNのキーワード、SQLSetConnectAttrおよびSQLGetConnectAttrの接続属性をSQL ServerのODBCドライバーで一覧にしています。

サポートされたDSNおよび接続文字列キーワードおよび接続属性

以下の表は、各プラットフォームで使用可能なキーワードと属性の一覧を示しています（L: Linux、M: macOS、W: Windows）。 キーワードまたは属性を選択すると、詳細が表示されます。

以下に、SQL Server Native Client で接続文字列キーワードを使用する、SQLSetConnectAttr、および SQLSetConnectAttr 関数 に記載されていない接続文字列キーワードと接続属性をいくつか示します。

説明

データソースの説明。

SQL_COPT_SS_ANSI_OEM

データの ANSI から OEM への変換を制御します。

SQL_COPT_SS_AUTOBEGINTXN

バージョン17.6以降、オートコミットがオフの状態で、ROLLBACKまたはCOMMIT後の自動BEGIN TRANSACTIONをこのオプションで制御できます。

SQL_COPT_SS_FALLBACK_CONNECT

SQL Serverのフォールバック接続の使用を制御します。 このオプションは現在サポートされていません。

新しい接続文字列キーワードと接続属性

接続文字列キーワードの統一

バージョン18.7からは、ODBCドライバ for SQL ServerがMicrosoft.Data.SqlClientデータプロバイダーのプロパティ名に対応する追加の接続文字列キーワードをサポートします。 このサポートにより、アプリケーションはキーワード名を変更することなく、Microsoft SQL Serverのデータプロバイダーやドライバ間で単一の接続文字列を使用できるようになります。

キーワードの別名

各エイリアスは、対応するODBCキーワードと同じオプションを設定します:

運転手はこれらのエイリアスに以下のルールを適用します。

• 大文字と小文字を区別しない: ドライバーは大文字と小文字に関係なくエイリアスを照合します。 たとえば、 multipleactiveresultsets は MultipleActiveResultSetsと同じように動作します。
• 最初に出現する方が勝ちます: エイリアスとそれに相当するODBCキーワードが同じオプションを設定します。 もし接続文字列に両方が含まれている場合、ドライバーは最初の値を使い、その後のオプションの値は無視します。
• 入力のみ: ドライバーはエイリアスを入力として受け入れます。 出力接続文字列を返す場合や設定をデータソース名(DSN)に書き込む際、同等のODBCキーワードを使用します。
• プラットフォーム対応:このドライバーはWindows、Linux、macOSでMultipleActiveResultSetsおよびWorkstationIDをサポートしています。 ドライバーはWindowsのみでFailoverPartnerとFailover_Partnerをサポートしています。

ConnectTimeout キーワード

ConnectTimeoutキーワードはSQL_ATTR_LOGIN_TIMEOUT接続属性と同じログインタイムアウトを設定します。 アプリケーションはSQLSetConnectAttrを呼び出す代わりに、接続文字列でタイムアウトを指定することができます。

アプリケーションが接続関数を呼び出す前に明示的にSQL_ATTR_LOGIN_TIMEOUTを設定した場合、接続属性がConnectTimeout 接続文字列値より優先されます。

• 単位とデフォルト: この値はログイン完了までの待機秒数を指定します。 既定値は 15 秒です。
• タイムアウトなし:0の値は運転手に無期限の待機を指示します。
• 最大値とクランプ: 最大値は 65534です。 負の値、 65534を超える値、またはサポートされる数値範囲を超える値を入力すると、ドライバーは 65534を使用します。 ドライバーが値をクランプし、それ以外は接続が正常に成功した場合、ドライバーは01S02をSQL_SUCCESS_WITH_INFO（オプション値が変更されました）警告付きで返します。
• 検証: ドライバーは空の値や数値でない値を拒否します。
• DSN サポート: Windows では、アプリケーションはデータ ソース名（DSN）に ConnectTimeout を保存したり取得したりできます。
• プラットフォーム対応:ドライバーはWindows、Linux、macOSでConnectTimeoutをサポートしています。

例

以下の接続文字列は統一キーワードの綴りを使用しています:

Driver={ODBC Driver 18 for SQL Server};Server=tcp:myserver.database.windows.net;Database=mydb;UID=myuser;PWD=mypassword;MultipleActiveResultSets=Yes;WorkstationID=app-node-01;ConnectTimeout=30;

前の接続文字列内のエイリアスは、元のODBCキーワードと同じオプションを以下の接続文字列で構成します:

Driver={ODBC Driver 18 for SQL Server};Server=tcp:myserver.database.windows.net;Database=mydb;UID=myuser;PWD=mypassword;MARS_Connection=Yes;WSID=app-node-01;

両方の文字列はMARSを有効にし、ワークステーションIDを app-node-01に設定します。 最初の文字列もログイン完了まで最大30秒待ちます。 ConnectTimeout 以前のバージョンには対応するものはありません。 以前のバージョンでログインタイムアウトを設定するには、SQL_ATTR_LOGIN_TIMEOUTでSQLSetConnectAttrに連絡してください。

認証 - SQL_COPT_SS_AUTHENTICATION

SQL Server に接続するときに使用する認証モードを設定します。 詳細情報については、「ODBC ドライバーでの Microsoft Entra ID の使用」をご覧ください。

ColumnEncryption - SQL_COPT_SS_COLUMN_ENCRYPTION

透過的な列の暗号化を制御します (Always Encrypted)。 詳しくは、「SQL Server 用 ODBC ドライバーと共に Always Encrypted を使用する」をご覧ください。

ConcatNullYieldsNull（NULL を連結する場合の動作設定） - SQL_COPT_SS_CONCAT_NULL

文字列を連結する際の NULL の ISO 処理の使用を制御します。 詳細については、SET CONCAT_NULL_YIELDS_NULLを参照してください。

Encrypt

接続時にネットワーク上で TLS 暗号化が使用されるかどうかを指定します。 バージョン17は yes と noを受け入れています。 バージョン18.0以降のバージョンでは、mandatoryをyesの同義語として、optionalをstrictnoの同義語として受け入れ、TDS 8.0暗号化を選択し、バージョン17に対応するものは存在しません。 デフォルト値はバージョン18.0以降では yes され、以前のバージョンでは no されています。

Encrypt の設定に関係なく、サーバー ログイン資格情報 (ユーザー名およびパスワード) は、常に暗号化されます。

Encrypt、TrustServerCertificate、サーバー側のForce Encryption設定によって、ネットワーク上で接続が暗号化されているかどうかが決まります。 次の表は、これらの設定の効果を示しています。

ODBC Driver 18 以降

ODBC Driver 17 以前のバージョン

TransparentNetworkIPResolution - SQL_COPT_SS_TNIR

ODBCドライバーのレガシーマルチIPフォールバックであるTransparent Network IP Resolution機能を制御します。 この設定はMultiSubnetFailover=Yes時の接続順序に影響を与えません。これはAzure SQL Database、Azure SQL Managed Instance、Microsoft FabricのSQLデータベース、可用性グループのリスナー、フェイルオーバークラスターインスタンスで推奨される設定です。 詳細については、「 ODBCドライバーでの透過的なネットワークIP解決の使用 」または「 高可用性および災害復旧」をご覧ください。

UseFMTONLY

SQL Server 2012 以降に接続するときのメタデータのSET FMTONLYの使用を制御します。

レプリケーション

ODBC Driver バージョン 17.8 以降でのレプリケーション ログインの使用を指定します。

RetryExec

構成可能な再試行ロジックは、バージョン 18.1 以降で使用できます。 これにより、構成可能な条件に基づいて、特定の ODBC 関数の呼び出しが自動的に再実行されます。 接続文字列でRetryExecキーワードとリトライルールのリストを使えば、この機能を有効にしてください。 各リトライルールは、エラーマッチ、リトライポリシー、クエリマッチの3つのコロン分離コンポーネントで構成されています。

クエリマッチは、特定の実行で使用するリトライルールを決定します。 これは、入ってくるコマンドテキスト(SQLExecDirect)または文オブジェクト内の準備済みコマンドテキスト(SQLExecute)と一致します。 複数のルールが一致する場合は、リストの最初のマッチングルールが使用されます。 この動作により、規則を一般性が上がる順にリストアップできます。 ルールが一致しない場合は再挑戦は適用されません。

実行中にエラーが発生し、該当する再試行ルールがある場合、そのエラーマッチが実行の再試行の有無を決定します。

RetryExecキーワードの値は、セミコロンで区切られたリトライルールのリストです。
RetryExec={rule1;rule2}

再試行ルールは次のようになります: <errormatch>:<retrypolicy>:<querymatch>

• エラーマッチ:カンマ区切られたエラーコードのリスト。 例えば、 1000,2000 を指定すると再試行したいエラーコードが表示されます。

• 再試行ポリシー:次の再試行までの遅延を指定します。 最初のパラメータはリトライ回数、2つ目のパラメータは遅延です。 例えば、3,10+7 は10秒から始まる3回の試行を意味し、以降の再試行のたびに7秒ずつ増えます。 +7を指定しなければ、その後の再試行は指数関数的に倍増します。

• クエリマッチ:マッチングしたいクエリを指定します。 何も指定しなければ、そのルールはすべてのクエリに適用されます。 SELECTを指定すると、SELECTで始まるすべてのクエリを指す。

接続文字列として使うために3つの成分を組み合わせる方法:

RetryExec={1000,2000:3,10+7:SELECT}

このルールは、SELECTで始まるクエリで誤りが1000・2000した場合、最初の遅延10秒で2回再試行し、その後の1回の試みごとに7秒を加えることを意味します。

使用例

40501,40540:4,5

誤り 40501 および 40540の場合は、最大4回まで再試行し、初期遅延は5秒、再試行の間は指数関数的に倍増します。 このルールはすべてのクエリに適用されます。

49919:2,10+:CREATE

CREATEで始まるクエリでエラー49919が発生した場合、最大でも2回だけやり直してください。最初は10秒後、次に20秒後です。

49918,40501,10928:5,10+5:SELECT c1

SELECT c1で始まるクエリでエラー49918、40501、10928がある場合は、最大5回まで再試行し、最初の再試行で10秒待ち、その後5秒待ち時間が増やされます。

以下の3つのルールを接続文字列でまとめて指定します。

RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}

最も一般的な(マッチオール)ルールを最後に置き、その前の2つのより具体的なルールがそれぞれのクエリにマッチできるようにします。

クライアント証明書

ループバック接続による認証証明書を指定します。 このオプションはLinuxのSQL Server on Linuxでのみ利用可能です。 オプションは次のとおりです。

証明書が PFX 形式で、 PFX 証明書内の秘密鍵がパスワード保護されている場合は、 password キーワードを含めてください。 PEMおよびDER形式の証明書については、ClientKey属性を含めてください。

ClientKey

ClientCertificate属性で指定されたPEMまたはDER証明書の秘密鍵のファイル位置を指定します。 形式:

秘密鍵ファイルがパスワード保護されている場合は、 password キーワードを含めてください。 パスワードに , 文字が含まれている場合は、各文字の直後に1文字追加 , 字を加えます。 例えば、パスワードがa,b,cされている場合、接続文字列内の逃げ出したパスワードはa,,b,,cされます。

証明書内のホスト名

暗号化交渉時にサーバーの証明書に期待されるホスト名を指定します。Addr、Address、Serverから派生したデフォルト値と異なる場合。 ServerCertificateオプションを使うとHostnameInCertificateオプションは無視されます。

IP アドレスの優先設定

バージョン18.1以降は、このオプションを使って接続の優先順位をつけるIPアドレスの種類を指定します。

選択肢は IPv4First、 IPv6First、 UsePlatformDefaultです。 UsePlatformDefault サーバー名を解決するためのシステムコールで提供されたアドレスの順番で接続します。 デフォルト値は IPv4Firstで、これは以前のバージョンの挙動に対応しています。

サーバー証明書

バージョン18.1からは、厳密暗号化モードでこのオプションを使います。 ServerCertificateキーワードを使って、SQL Server TLS/SSL証明書と照合する証明書ファイルへのパスを指定します。 マッチングは標準的な証明書検証(有効期限、ホスト名、信頼チェーンなど)の代わりに行われます。 受け入れられる証明書の形式は PEM、DER、CER です。 このオプションを指定すると、SQL Server証明書が提供されたServerCertificateが完全に一致しているかどうかを確認します。

SQL_COPT_SS_ACCESS_TOKEN

認証にはMicrosoft Entraのアクセストークンを使いましょう。 詳細情報については、「ODBC ドライバーでの Microsoft Entra ID の使用」をご覧ください。

SQL_COPT_SS_CEKEYSTOREDATA

読み込まれたキーストア プロバイダー ライブラリと通信します。 透過的な列の暗号化を制御します (Always Encrypted)。 この属性には既定値はありません。 詳しくは、「カスタム キーストア プロバイダー」をご覧ください。

SQL_COPT_SS_CEKEYSTOREPROVIDER

Always Encrypted 用のキーストア プロバイダー ライブラリを読み込むか、または読み込まれたキーストア プロバイダー ライブラリの名前を取得します。 詳しくは、「カスタム キーストア プロバイダー」をご覧ください。 この属性には既定値はありません。

SQL_COPT_SS_ENLIST_IN_XA

XA準拠のトランザクションプロセッサ(TP)でXAトランザクションを有効にするには、アプリケーションはSQL_COPT_SS_ENLIST_IN_XAとXACALLPARAMオブジェクトへのポインタを使ってSQLSetConnectAttrを呼び出す必要があります。 このオプションはWindows(17.3以降のバージョン)、Linux、macOSでサポートされています。

SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER);  // XACALLPARAM *param

XAトランザクションをODBC接続のみに関連付けたい場合は、SQLSetConnectAttrを呼び出す際にポインタの代わりにSQL_COPT_SS_ENLIST_IN_XAで、TRUEまたはFALSEを付けてください。 この設定は、Windows でのみ有効であり、クライアント アプリケーションで XA 操作を指定するために使用することはできません。

SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, (SQLPOINTER)TRUE, 0);

XA トランザクションについて詳しくは、「XA トランザクションの使用」をご覧ください。

SQL_COPT_SS_LONGASMAX

長いデータ型を最大データ型としてサーバーに送信します。

SQL_COPT_SS_SPID

接続のセッション ID を取得します。 このプロパティは、サーバーへの追加のラウンド トリップが発生しない点を除き、T-SQL @@SPID 変数と同じです。