次の方法で共有


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

このページでは、ODBC Driver for SQL Server で使用可能な、接続文字列と DSN でのキーワード、および SQLSetConnectAttr と SQLGetConnectAttr に対する接続属性の一覧を示します。

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

各プラットフォームに使用できるキーワードと属性を次の表に示します (L:Linux、M: macOS、W: Windows)。 キーワードまたは属性を選択すると、詳細が表示されます。

DSN / 接続文字列のキーワード 接続属性 プラットフォーム
Addr LMW
アドレス LMW
AnsiNPW SQL_COPT_SS_ANSI_NPW LMW
APP LMW
ApplicationIntent SQL_COPT_SS_APPLICATION_INTENT LMW
AttachDBFileName SQL_COPT_SS_ATTACHDBFILENAME LMW
認証 SQL_COPT_SS_AUTHENTICATION LMW
AutoTranslate SQL_COPT_SS_TRANSLATE LMW
ClientCertificate LMW
ClientKey LMW
ColumnEncryption SQL_COPT_SS_COLUMN_ENCRYPTION LMW
ConnectRetryCount SQL_COPT_SS_CONNECT_RETRY_COUNT LMW
ConnectRetryInterval SQL_COPT_SS_CONNECT_RETRY_INTERVAL LMW
[データベース] SQL_ATTR_CURRENT_CATALOG LMW
説明 LMW
[ドライバー] LMW
DSN LMW
Encrypt SQL_COPT_SS_ENCRYPT LMW
Failover_Partner SQL_COPT_SS_FAILOVER_PARTNER W
FailoverPartnerSPN SQL_COPT_SS_FAILOVER_PARTNER_SPN W
FileDSN LMW
GetDataExtensions (v18.0 以降) SQL_COPT_SS_GETDATA_EXTENSIONS LMW
HostnameInCertificate (v18.0 以降) LMW
IpAddressPreference (v18.1 以降) LMW
KeepAlive (v17.4 以降。17.8 より前は DSN のみ) LMW
KeepAliveInterval (v17.4 以降。17.8 より前は DSN のみ) LMW
KeystoreAuthentication LMW
KeystorePrincipalId LMW
KeystoreSecret LMW
Language LMW
LongAsMax (v18.0 以降) SQL_COPT_SS_LONGASMAX LMW
MARS_Connection SQL_COPT_SS_MARS_ENABLED LMW
MultiSubnetFailover SQL_COPT_SS_MULTISUBNET_FAILOVER LMW
Net LMW
Network LMW
PWD LMW
QueryLog_On SQL_COPT_SS_PERF_QUERY W
QueryLogFile SQL_COPT_SS_PERF_QUERY_LOG W
QueryLogTIme SQL_COPT_SS_PERF_QUERY_INTERVAL W
QuotedId SQL_COPT_SS_QUOTED_IDENT LMW
Regional LMW
レプリケーション LMW
RetryExec (18.1 以降) LMW
SaveFile LMW
[サーバー] LMW
ServerCertificate (v18.1 以降) LMW
ServerSPN SQL_COPT_SS_SERVER_SPN LMW
StatsLog_On SQL_COPT_SS_PERF_DATA W
StatsLogFile SQL_COPT_SS_PERF_DATA_LOG W
TransparentNetworkIPResolution SQL_COPT_SS_TNIR LMW
Trusted_Connection SQL_COPT_SS_INTEGRATED_SECURITY LMW
TrustServerCertificate SQL_COPT_SS_TRUST_SERVER_CERTIFICATE LMW
UID LMW
UseFMTONLY LMW
WSID LMW
SQL_ATTR_ACCESS_MODE
(SQL_ACCESS_MODE)
LMW
SQL_ATTR_ASYNC_DBC_EVENT W
SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE W
SQL_ATTR_ASYNC_DBC_PCALLBACK W
SQL_ATTR_ASYNC_DBC_PCONTEXT W
SQL_ATTR_ASYNC_ENABLE W
SQL_ATTR_AUTO_IPD LMW
SQL_ATTR_AUTOCOMMIT
(SQL_AUTOCOMMIT)
LMW
SQL_ATTR_CONNECTION_DEAD LMW
SQL_ATTR_CONNECTION_TIMEOUT LMW
SQL_ATTR_DBC_INFO_TOKEN LMW
SQL_ATTR_LOGIN_TIMEOUT
(SQL_LOGIN_TIMEOUT)
LMW
SQL_ATTR_METADATA_ID LMW
SQL_ATTR_ODBC_CURSORS
(SQL_ODBC_CURSORS)
LMW
SQL_ATTR_PACKET_SIZE
(SQL_PACKET_SIZE)
LMW
SQL_ATTR_QUIET_MODE
(SQL_QUIET_MODE)
LMW
SQL_ATTR_RESET_CONNECTION
(SQL_COPT_SS_RESET_CONNECTION)
LMW
SQL_ATTR_TRACE
(SQL_OPT_TRACE)
LMW
SQL_ATTR_TRACEFILE
(SQL_OPT_TRACEFILE)
LMW
SQL_ATTR_TRANSLATE_LIB
(SQL_TRANSLATE_DLL)
LMW
SQL_ATTR_TRANSLATE_OPTION
(SQL_TRANSLATE_OPTION)
LMW
SQL_ATTR_TXN_ISOLATION
(SQL_TXN_ISOLATION)
LMW
SQL_COPT_SS_ACCESS_TOKEN LMW
SQL_COPT_SS_ANSI_OEM W
SQL_COPT_SS_AUTOBEGINTXN LMW
SQL_COPT_SS_BCP LMW
SQL_COPT_SS_BROWSE_CACHE_DATA LMW
SQL_COPT_SS_BROWSE_CONNECT LMW
SQL_COPT_SS_BROWSE_SERVER LMW
SQL_COPT_SS_CEKEYSTOREDATA LMW
SQL_COPT_SS_CEKEYSTOREPROVIDER LMW
SQL_COPT_SS_CLIENT_CONNECTION_ID LMW
SQL_COPT_SS_CONCAT_NULL LMW
SQL_COPT_SS_CONNECTION_DEAD LMW
SQL_COPT_SS_DATACLASSIFICATION_VERSION (v17.4.2 以降) LMW
SQL_COPT_SS_ENLIST_IN_DTC W
SQL_COPT_SS_ENLIST_IN_XA LMW
SQL_COPT_SS_FALLBACK_CONNECT LMW
SQL_COPT_SS_INTEGRATED_AUTHENTICATION_METHOD LMW
SQL_COPT_SS_MUTUALLY_AUTHENTICATED LMW
SQL_COPT_SS_OLDPWD LMW
SQL_COPT_SS_PERF_DATA_LOG_NOW W
SQL_COPT_SS_PRESERVE_CURSORS LMW
SQL_COPT_SS_SPID (v17.5 以降) LMW
SQL_COPT_SS_TXN_ISOLATION LMW
SQL_COPT_SS_USER_DATA LMW
SQL_COPT_SS_WARN_ON_CP_ERROR LMW

以下に、「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 の設定に関係なく、サーバー ログイン資格情報 (ユーザー名およびパスワード) は、常に暗号化されます。

EncryptTrustServerCertificate、およびサーバー側の 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