DSN と接続文字列のキーワードと属性
このページでは、ODBC Driver for SQL Server で使用可能な、接続文字列と DSN でのキーワード、および SQLSetConnectAttr と SQLGetConnectAttr に対する接続属性の一覧を示します。
サポートされる DSN/接続文字列のキーワードおよび接続属性
各プラットフォームに使用できるキーワードと属性を次の表に示します (L:Linux、M: macOS、W: Windows)。 キーワードまたは属性を選択すると、詳細が表示されます。
以下に、「SQL Server Native Client での接続文字列キーワードの使用」、「SQLSetConnectAttr」、「SQLSetConnectAttr 関数」に記載されていない接続文字列キーワードと接続属性をいくつか示します。
説明
データ ソースの説明に使用されます。
SQL_COPT_SS_ANSI_OEM
データの ANSI から OEM への変換を制御します。
| 属性値 | 説明 |
|---|---|
| SQL_AO_OFF | (既定値) 変換は行われません。 |
| SQL_AO_ON | 変換が完了しました。 |
SQL_COPT_SS_AUTOBEGINTXN
バージョン 17.6+ オートコミットがオフのとき、ROLLBACK または COMMIT の後、自動 BEGIN TRANSACTION が制御されます。
| 属性値 | 説明 |
|---|---|
| SQL_AUTOBEGINTXN_ON | (既定) ROLLBACK または COMMIT 後の自動 BEGIN TRANSACTION。 |
| SQL_AUTOBEGINTXN_OFF | ROLLBACK または COMMIT 後の自動 BEGIN TRANSACTION なし。 |
SQL_COPT_SS_FALLBACK_CONNECT
SQL Server のフォールバック接続の使用を制御します。 これはサポートされなくなりました。
| 属性値 | 説明 |
|---|---|
| SQL_FB_OFF | (既定値) フォールバック接続は無効です。 |
| SQL_FB_ON | フォールバック接続は有効です。 |
新しい接続文字列のキーワードおよび接続属性
認証 - SQL_COPT_SS_AUTHENTICATION
SQL Server に接続するときに使用する認証モードを設定します。 詳細については、Microsoft Entra ID の使用に関する記事を参照してください。
| キーワードの値 | 属性値 | 説明 |
|---|---|---|
| SQL_AU_NONE | (既定値) 設定されていません。 認証モードは、他の属性の組み合わせによって決まります。 | |
| SqlPassword | SQL_AU_PASSWORD | ユーザー名とパスワードを使用する SQL Server 認証。 |
| ActiveDirectoryIntegrated | SQL_AU_AD_INTEGRATED | Microsoft Entra 統合認証。 |
| ActiveDirectoryPassword | SQL_AU_AD_PASSWORD | Microsoft Entra パスワード認証。 |
| ActiveDirectoryInteractive | SQL_AU_AD_INTERACTIVE | Microsoft Entra 対話型認証。 |
| ActiveDirectoryMsi | SQL_AU_AD_MSI | Microsoft Entra マネージド ID 認証。 ユーザー割り当て ID の場合、UID はユーザー ID のオブジェクト ID に設定されます。 |
| ActiveDirectoryServicePrincipal | SQL_AU_AD_SPA | Microsoft Entra サービス プリンシパル認証。 UID は、サービス プリンシパルのクライアント ID に設定されます。 PWD はクライアント シークレットに設定されます。 |
| SQL_AU_RESET | 未設定。 すべての DSN または接続文字列の設定をオーバーライドします。 |
注意
Authentication キーワードまたは属性を使用するときは、接続文字列/DSN/接続属性で必要な値に対する Encrypt の設定を明示的に指定します。 詳しくは、「Using Connection String Keywords with SQL Server Native Client (SQL Server Native Client での接続文字列キーワードの使用)」をご覧ください。
ColumnEncryption - SQL_COPT_SS_COLUMN_ENCRYPTION
透過的な列の暗号化を制御します (Always Encrypted)。 詳しくは、Always Encrypted の使用 (ODBC) に関する記事をご覧ください。
| キーワードの値 | 属性値 | 説明 |
|---|---|---|
| Enabled | SQL_CE_ENABLED | Always Encrypted を有効にします。 |
| 無効 | SQL_CE_DISABLED | (既定値) Always Encrypted を無効にします。 |
| SQL_CE_RESULTSETONLY | 解読のみを有効にします (結果と戻り値)。 |
Encrypt
接続時にネットワーク上で TLS 暗号化が使用されるかどうかを指定します。 指定できる値は、yes/mandatory (18.0+)、no/optional (18.0+)、および strict (18.0+) です。 既定値は、バージョン 18.0+ では yes、以前のバージョンでは no です。
Encrypt の設定に関係なく、サーバー ログイン資格情報 (ユーザー名およびパスワード) は、常に暗号化されます。
Encrypt、TrustServerCertificate、およびサーバー側の Force Encryption 設定は、ネットワーク上で接続が暗号化されるかどうかに関わります。 次の表は、これらの設定の効果を示しています。
ODBC Driver 18 以降
| 暗号化の設定 | [Trust Server Certificate] | サーバーの強制的な暗号化 | 結果 |
|---|---|---|---|
| いいえ | 番号 | いいえ | サーバー証明書は確認されません。 クライアントとサーバー間で送信されるデータは暗号化されません。 |
| いいえ | 有効 | いいえ | サーバー証明書は確認されません。 クライアントとサーバー間で送信されるデータは暗号化されません。 |
| はい | いいえ | いいえ | サーバー証明書は確認されます。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
| はい | はい | いいえ | サーバー証明書は確認されません。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
| いいえ | 番号 | はい | サーバー証明書は確認されます。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
| いいえ | イエス | はい | サーバー証明書は確認されません。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
| はい | いいえ | はい | サーバー証明書は確認されます。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
| はい | イエス | はい | サーバー証明書は確認されません。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
| 高 | - | - | TrustServerCertificate は無視されます。 サーバー証明書は確認されます。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
Note
Strict は、TDS 8.0 接続をサポートするサーバーに対してのみ使用できます。
ODBC Driver 17 以前
| 暗号化の設定 | [Trust Server Certificate] | サーバーの強制的な暗号化 | 結果 |
|---|---|---|---|
| いいえ | 番号 | いいえ | サーバー証明書は確認されません。 クライアントとサーバー間で送信されるデータは暗号化されません。 |
| いいえ | 有効 | いいえ | サーバー証明書は確認されません。 クライアントとサーバー間で送信されるデータは暗号化されません。 |
| はい | いいえ | いいえ | サーバー証明書は確認されます。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
| はい | はい | いいえ | サーバー証明書は確認されません。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
| いいえ | 番号 | はい | サーバー証明書は確認されません。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
| いいえ | イエス | はい | サーバー証明書は確認されません。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
| はい | いいえ | はい | サーバー証明書は確認されます。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
| はい | イエス | はい | サーバー証明書は確認されません。 クライアントとサーバー間で送信されるデータは暗号化されます。 |
TransparentNetworkIPResolution - SQL_COPT_SS_TNIR
透過的ネットワーク IP 解決機能を制御します。この機能は、MultiSubnetFailover と対話して、より速い再接続の試行を可能にします。 詳しくは、「透過的なネットワーク IP の解決の使用」をご覧ください。
| キーワードの値 | 属性値 | 説明 |
|---|---|---|
| Enabled | SQL_IS_ON | (既定値) 透過的なネットワーク IP の解決を有効にします。 |
| 無効 | SQL_IS_OFF | 透過的なネットワーク IP の解決を無効にします。 |
UseFMTONLY
SQL Server 2012 以降に接続するときの、メタデータに対する SET FMTONLY の使用を制御します。
| キーワードの値 | 説明 |
|---|---|
| いいえ | (既定値) 使用可能な場合は、メタデータに sp_describe_first_result_set を使用します。 |
| はい | メタデータに SET FMTONLY を使用します。 |
レプリケーション
ODBC Driver バージョン 17.8 以降でのレプリケーション ログインの使用を指定します。
| キーワードの値 | 説明 |
|---|---|
| いいえ | (既定値) レプリケーション ログインは使用されません。 |
| はい | NOT FOR REPLICATION オプションを使用したトリガーは、接続で起動されません。 |
RetryExec
構成可能な再試行ロジックは、バージョン 18.1 以降で使用できます。 これにより、構成可能な条件に基づいて、特定の ODBC 関数の呼び出しが自動的に再実行されます。 この機能は、接続文字列で RetryExec キーワードと再試行ルールのリストを使うことにより有効にできます。 各再試行ルールは、エラー一致、再試行ポリシー、クエリ一致という 3 つのコンポーネントをコロンで区切って指定します。
クエリ一致は、特定の実行に使われる再試行ルールを決定し、受信コマンド テキスト (SQLExecDirect) またはステートメント オブジェクト (SQLExecute) 内の準備済みコマンドのテキストと照合されます。 複数のルールが一致する場合は、リストで最初に一致したルールが使われます。 このビヘイビアーにより、リストでは一般性が高くなる順序でルールを指定できます。 一致するルールがない場合、再試行は適用されません。
実行結果がエラーになり、該当する再試行ルールがある場合は、そのエラー一致を使って、実行を再試行する必要があるかどうかが決定されます。
RetryExec キーワードの値は、セミコロンで区切られた再試行ルールのリストです。
RetryExec={rule1;rule2}
再試行ルールは次のようになります: <errormatch>:<retrypolicy>:<querymatch>
エラー一致: エラー コードのコンマ区切りリスト。 たとえば、再試行するエラー コードを 1000,2000 のように指定します。
再試行ポリシー: 次の再試行までの遅延を指定します。 1 番目のパラメーターは再試行の回数で、2 番目のパラメーターは遅延です。 たとえば、3,10+7 と指定すると、10 秒から始めて、7 秒ずつ増やしながら 3 回再試行します。 +7 を指定しないと、以降の再試行のたびに指数関数的に倍増することになります。
クエリ一致: 照合するクエリを指定します。 何も指定しないと、すべてのクエリに適用されます。 SELECT を指定すると、SELECT で始まるすべてのクエリを意味します。
上の 3 つのコンポーネントをすべて組み合わせて接続文字列で使うと、次のようになります。
RetryExec={1000,2000:3,10+7:SELECT}
これは次のような意味になります: "エラー 1000 と 2000 の場合、SELECT で始まるクエリについて。 最初に 10 秒遅延した後、以降の試行ごとに 7 秒ずつ追加しながら、2 回再試行します"
使用例
40501,40540:4,5
エラー 40501 と 40540 の場合、最初に 5 秒遅延した後、再試行ごとに遅延を倍にしながら、最大 4 回再試行します。 このルールはすべてのクエリに適用されます。
49919:2,10+:CREATE
CREATE で始まるクエリでのエラー 49919 の場合、最初は 10 秒後、次に 20 秒後に、最大 2 回再試行します。
49918,40501,10928:5,10+5:SELECT c1
SELECT c1 で始まるクエリでのエラー 49918、40501、10928 の場合、最初の再試行まで 10 秒待った後、以降は 5 秒ずつ待機を増やしながら、最大で 5 回再試行します。
上の 3 つのルールは、接続文字列で次のようにまとめて指定できます。
RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}
最も一般的な (すべてに一致する) ルールが最後に配置され、それより具体的な 2 つのルールがそれぞれのクエリと一致できるように、その前に置かれます。
ClientCertificate
認証に使用する証明書を指定します。 オプションは次のとおりです。
| オプション値 | 説明 |
|---|---|
sha1:<hash_value> |
ODBC ドライバーでは、Windows 証明書ストア内の証明書の特定に SHA1 ハッシュが使用されます。 |
subject:<subject> |
ODBC ドライバーでは、Windows 証明書ストア内の証明書の特定にサブジェクトが使用されます。 |
file:<file_location>[,password:<password>] |
ODBC ドライバーでは、証明書ファイルが使用されます。 |
証明書が PFX 形式であり、PFX 証明書内の秘密キーがパスワードで保護されている場合は、password キーワードが必要です。 PEM および DER 形式の証明書の場合、ClientKey 属性が必要です
ClientKey
ClientCertificate 属性に指定された PEM または DER 証明書の秘密キーのファイルの場所を指定します。 形式:
| オプション値 | 説明 |
|---|---|
file:<file_location>[,password:<password>] |
秘密キー ファイルの場所を指定します。 |
秘密キー ファイルがパスワードで保護されている場合は、password キーワードが必要です。 パスワードに , 文字が含まれている場合は、その各文字の直後にもう 1 文字 , が追加されます。 たとえば、パスワードが a,b,c の場合、接続文字列に含まれるエスケープされたパスワードは a,,b,,c になります。
HostnameInCertificate
暗号化がネゴシエートされるときに、サーバーの証明書に予期されるホスト名 (Addr/Address/Server から得られる既定値と異なる場合) を指定します。 ServerCertificate オプションを使用している場合、HostnameInCertificate オプションは無視されます。
IpAddressPreference
バージョン 18.1 以降で使用できるこのオプションを使うと、ユーザーは接続で優先する IP アドレスの種類を指定できます。 使用可能なオプションは、"IpAddress= [ IPv4First | IPv6First | UsePlatformDefault]" です。UsePlatformDefault は、サーバー名を解決するためにシステム呼び出しによって提供される順序でアドレスに接続します。 既定値は IPv4First で、以前のバージョンの動作に対応します。
ServerCertificate
バージョン 18.1 以降で使用可能になったこのオプションは、厳格な暗号化モードで使用できます。 ServerCertificate キーワードは、SQL Server の TLS/SSL 証明書と照合する証明書ファイルへのパスを指定するために使われます。 照合は、標準の証明書検証 (有効期限、ホスト名、信頼チェーンなど) の代わりに行われます。有効な証明書形式は、PEM、DER、CER です。 指定した場合、SQL Server の証明書は、指定された ServerCertificate が完全に一致するかどうかを確認することでチェックされます。
SQL_COPT_SS_ACCESS_TOKEN
認証に Microsoft Entra アクセス トークンを使用できるようにします。 詳細については、Microsoft Entra ID の使用に関する記事を参照してください。
| 属性値 | 説明 |
|---|---|
| NULL | (既定値) アクセス トークンが提供されていません。 |
| ACCESSTOKEN* | アクセス トークンへのポインター。 |
SQL_COPT_SS_CEKEYSTOREDATA
読み込まれたキーストア プロバイダー ライブラリと通信します。 透過的な列の暗号化を制御します (Always Encrypted)。 この属性には既定値はありません。 詳しくは、「カスタム キーストア プロバイダー」をご覧ください。
| 属性値 | 説明 |
|---|---|
| CEKEYSTOREDATA * | キーストア プロバイダー ライブラリ用の通信データ構造 |
SQL_COPT_SS_CEKEYSTOREPROVIDER
Always Encrypted 用のキーストア プロバイダー ライブラリを読み込むか、または読み込まれたキーストア プロバイダー ライブラリの名前を取得します。 詳しくは、「カスタム キーストア プロバイダー」をご覧ください。 この属性には既定値はありません。
| 属性値 | 説明 |
|---|---|
| char * | キーストア プロバイダー ライブラリへのパス |
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);
| 値 | 説明 | プラットフォーム |
|---|---|---|
| XACALLPARAM object* | XACALLPARAM オブジェクトを指すポインター。 |
Windows、Linux、macOS |
| TRUE | XA トランザクションを ODBC 接続に関連付けます。 関連するすべてのデータベース アクティビティは、XA トランザクションの保護下で実行されます。 | Windows |
| FALSE | トランザクションと ODBC 接続の関連付けを解除します。 | Windows |
XA トランザクションについて詳しくは、「XA トランザクションの使用」をご覧ください。
SQL_COPT_SS_LONGASMAX
long 型のデータを max 型のデータとしてサーバーに送信できるようにします。
| 属性値 | 説明 |
|---|---|
| いいえ | (既定値) 送信時に long 型を max 型に変換しません。 |
| はい | 送信時にデータを long 型から max 型に変換します。 |
SQL_COPT_SS_SPID
接続のサーバー プロセス ID を取得します。 このプロパティは、サーバーへの追加のラウンド トリップが発生しない点を除き、T-SQL @@SPID 変数と同じです。
| 属性値 | 説明 |
|---|---|
| DWORD | SPID |