接続プロパティの設定
接続文字列のプロパティは、さまざまな方法で指定できます。
DriverManager クラスを使用して接続するときは、接続 URL における "名前=値" 形式のプロパティとして指定できます。 接続文字列の構文については、「接続 URL の構築」を参照してください。
DriverManager クラスの Connect メソッドの Properties パラメーター の中で "名前=値" 形式のプロパティとして指定できます。
ドライバーのデータ ソースの適切な setter メソッドの値として指定できます。 次に例を示します。
datasource.setServerName(value) datasource.setDatabaseName(value)
解説
プロパティ名の大文字と小文字は区別されず、重複したプロパティ名は次の順序で解決されます。
- API 引数 (user、password など)
- プロパティ コレクション
- 接続文字列の最後のインスタンス
プロパティ名には不明な値が許可されています。JDBC ドライバーでは大文字と小文字の区別は検証されません。
シノニムを使用できます。これは、重複したプロパティ名と同じ順序で解決されます。
プロパティ
次の表は、JDBC ドライバーで現在使用できるすべての接続文字列プロパティを示しています。
| プロパティ Type Default |
説明 |
|---|---|
| accessToken String null |
(バージョン 6.0 以降) このプロパティを使用し、アクセス トークンを使ってデータベースに接続します。 accessToken は、接続 URL を使用して設定することはできません。 |
| accessTokenCallbackClass String null |
(バージョン 12.4 以降) アクセス トークン コールバックで使用するコールバック実装クラスの名前。 |
| applicationIntent String ReadWrite |
(バージョン 6.0 以降) サーバーに接続するためのアプリケーション ワークロードのタイプを宣言します。 有効値は、ReadOnly と ReadWrite です。 ディザスター リカバリーの詳細については、「高可用性、ディザスター リカバリーのための JDBC Driver のサポート」を参照してください。 |
| applicationName String [<=128 文字] null |
アプリケーション名、または名前が指定されていない場合は " Microsoft JDBC Driver for SQL Server" です。 個別のアプリケーションを識別するために、さまざまな SQL Server プロファイリング ツールおよびロギング ツールで使用されます。 |
| 認証 String NotSpecified |
(バージョン 6.0 以降) この省略可能なプロパティは、接続に使用する認証方法を示します。 指定できる値は、ActiveDirectoryIntegrated、ActiveDirectoryPassword、ActiveDirectoryManagedIdentity (バージョン 12.2 以降)、ActiveDirectoryMSI (バージョン 7.2 以降)、ActiveDirectoryInteractive (バージョン 9.2 以降)、ActiveDirectoryServicePrincipal (バージョン 9.2 以降)、SqlPassword、NotSpecified (既定値) です。 ActiveDirectoryIntegrated (バージョン 6.0 以降) を使用して、統合 Windows 認証を使用している SQL に接続します。 ActiveDirectoryPassword (バージョン 6.0 以降) を使用して、Microsoft Entra のプリンシパル名とパスワードを使用している SQL に接続します。 Azure リソース内から SQL に接続するには、ActiveDirectoryManagedIdentity (バージョン 12.2 以降) または ActiveDirectoryMSI (バージョン 7.2 以降) を使います。 たとえば、マネージド ID 認証を使用する Azure Virtual Machine、App Service、関数アプリなどです。 ActiveDirectoryManagedIdentity または ActiveDirectoryMSI 認証モードを使用するときに、ドライバーでサポートされるマネージド ID は、次の 2 種類です。 1.システム割り当てマネージド ID:accessToken を取得するために既定で使用されます。 2.ユーザー割り当てマネージド ID:マネージド ID のクライアント ID が msiClientId 接続プロパティで指定されている場合に、accessToken を取得するために使用されます。 対話型認証フローを使用してデータベースに接続するには、ActiveDirectoryInteractive を使用します。 サービス プリンシパル ID のクライアント ID とシークレットを使用してデータベースに接続するには、ActiveDirectoryServicePrincipal (バージョン 9.2 以降) を使用します。 userName プロパティにクライアント ID を指定し、password プロパティ (10.2 以降) でシークレットを指定します。 userName/user プロパティと password プロパティを使って SQL に接続するには、SqlPassword を使用します。 これらの認証方法がいずれも必要ない場合は、NotSpecified を使用します。 重要: 認証が ActiveDirectoryIntegrated に設定されている場合、mssql-jdbc_auth-<バージョン>-<arch>.dll (JDBC ドライバー パッケージで入手可能) と SQL Server 用 Microsoft Authentication Library (ADAL.DLL) の 2 つのライブラリをインストールする必要があります。 Microsoft Authentication Library は、Microsoft ODBC Driver for SQL Server または Microsoft OLE DB Driver for SQL Server からインストールできます。 JDBC ドライバーでは、ADAL.DLL のバージョン 1.0.2028.318 以降のみがサポートされます。 注: 認証プロパティが NotSpecified 以外の値に設定されている場合、ドライバーでは既定で TLS (トランスポート層セキュリティ) (以前の SSL (Secure Sockets Layer)) 暗号化が使用されます。 Microsoft Entra の認証に関する情報は、「Microsoft Entra の認証の使用」を参照してください。 |
| authenticationScheme String NativeAuthentication |
アプリケーションで使用する統合セキュリティの種類を示します。 指定できる値は JavaKerberos、NTLM (バージョン 7.4 以降)、および NativeAuthentication (既定値) です。 NativeAuthentication を指定すると、ドライバーによって Windows に mssql-jdbc_auth-<version>-<arch>.dll (mssql-jdbc_auth-8.2.2.x64.dll など) が読み込まれます。これは統合認証情報の取得に使用されます。 (読み込まれたネイティブ認証ライブラリは、ドライバー バージョン 6.0 - 7.4 を使用している場合は sqljdbc_auth.dll という名前になります。)authenticationScheme=JavaKerberos を使用する場合は、serverName プロパティまたは serverSpn プロパティで完全修飾ドメイン名 (FQDN) を指定する必要があります。 それ以外の場合は、エラーが発生します (Kerberos データベースにサーバーが見つからない)。 authenticationScheme=JavaKerberos の使用の詳細については、「Kerberos 統合認証による SQL Server への接続」を参照してください。 authenticationScheme=NTLM を使用する場合は、domain または domainName プロパティを使用して Windows ドメインを指定し、user または userName プロパティと password プロパティで Windows 資格情報を指定する必要があります。 これを行わないと、エラーが発生します (接続プロパティを指定する必要があります)。 |
| cacheBulkCopyMetadata boolean ["true" | "false"] false |
(バージョン 12.8 以降) useBulkCopyForBatchInsert=true を使用する場合、このプロパティを使用して、コピー先列のメタデータを接続レベルでキャッシュするかどうかをドライバーに通知します。 true に設定されている場合は、ドライバーがこの変更に対処する方法がないため、一括挿入間でコピー先が変更されていないことを確認します。 |
| calcBigDecimalPrecision boolean ["true" | "false"] false |
(バージョン 12.6 以降) 精度 (38) の最大値を使用するのではなく、ドライバーが BigDecimal 入力の精度を計算する必要があるかどうかを示すフラグ。 |
| cancelQueryTimeout INT -1 |
(バージョン 6.4 以降) このプロパティは、接続で設定されている queryTimeout を取り消す場合に使用できます。 サーバーへの TCP 接続が暗黙的に削除されると、クエリの実行はハングし、例外はスローされません。 このプロパティは、接続でも 'queryTimeout' が設定されている場合にのみ適用されます。 ドライバーは cancelQueryTimeout + queryTimeout を合計した秒数を待機してから、接続を中断し、チャネルを閉じます。 このプロパティの既定値は -1 で、動作は無期限の待機です。 |
| clientCertificate String null |
(バージョン 8.4 以降) クライアント証明書の認証に使用する証明書の場所を指定します。 JDBC ドライバーは、PFX、PEM、DER、CER ファイル拡張子をサポートしています。 詳細については、「ループバック シナリオにおけるクライアント証明書の認証」を参照してください。 |
| clientKey String null |
(バージョン 8.4 以降) clientCertificate 属性によって指定された PEM、DER、CER 証明書の秘密キーのファイルの場所を指定します。 詳細については、「ループバック シナリオにおけるクライアント証明書の認証」を参照してください。 |
| clientKeyPassword String null |
(バージョン 8.4 以降) clientKey ファイルの秘密キーにアクセスするために指定された省略可能なパスワード文字列。 詳細については、「ループバック シナリオにおけるクライアント証明書の認証」を参照してください。 |
| columnEncryptionSetting String ["Enabled" | "Disabled"] 無効 |
(バージョン 6.0 以降) Always Encrypted (AE) 機能を使用するには、"Enabled" に設定します。 AE を有効にすると、JDBC ドライバーによって、サーバーの暗号化されたデータベースの列に格納されている機密データの透過的な暗号化と暗号化解除が行われます。 Always Encrypted の詳細については、「JDBC ドライバーでの Always Encrypted の使用」を参照してください。 注: Always Encrypted は、SQL Server 2016 以降および Azure SQL Database で利用できます。 |
| connectRetryCount INT [0..255] 1 |
(バージョン 9.4 以降) 接続に障害が発生した場合の再接続試行回数。 |
| connectRetryInterval INT [1..60] 10 |
(バージョン 9.4+) 接続再試行間の秒数。 |
| databaseName, database String [<=128 文字] null |
接続するデータベース名です。 指定しない場合は、既定のデータベースへの接続が確立されます。 |
| datetimeParameterType String ["datetime" | "datetime2" | "datetimeoffset"] datetime2 |
(バージョン 12.2 以降) Java の日付/タイムスタンプ パラメーターに使用する SQL データ型。 SQL Server 2016 以降に接続し、従来の "datetime" 値を操作している場合、クライアントはプロパティを "datetime" に設定することで利点が得られる可能性があります。 この設定により、"datetime" 値と "datetime2" 値の間のサーバー側の変換の問題が軽減されます。 詳細については、「SQL Server 2016 以降での datetime から datetime2 への変換動作の変更への対応」を参照してください |
| delayLoadingLobs boolean ["true" | "false"] true |
ResultSet から取得されるすべての LOB オブジェクトをストリームするかどうかを示すフラグ。 このプロパティを "false" に設定すると、LOB オブジェクト全体がストリーミングなしでメモリに読み込まれます。 |
| domainName domain String null |
(バージョン 7.4 以降) NTLM 認証を使用する場合に認証を行う Windows ドメイン。 |
| disableStatementPooling boolean ["true" | "false"] true |
フラグは、ステートメント プーリングを使用する必要があるかどうかを示します。 |
| enablePrepareOnFirst... PreparedStatementCall boolean ["true" | "false"] false |
準備されたステートメントの最初の実行で sp_prepexec を呼び出すことによって、準備されたステートメントのハンドルの作成を有効にするには、"true" に設定します。 準備されたステートメントの最初の実行で sp_executesql を呼び出し、ステートメントを準備しないように変更するには、"false" に設定します。 2 回目の実行が行われると、sp_prepexec が呼び出され、準備されたステートメントのハンドルが設定されます。 |
| enclaveAttestationUrl String null |
(バージョン 8.2 以降) この省略可能なプロパティは、セキュリティで保護されたエンクレーブでの Always Encrypted に使用する構成証明サービスのエンドポイント URL を示します。 セキュリティで保護されたエンクレーブが設定された Always Encrypted の詳細については、「セキュア エンクレーブを使用する Always Encrypted」を参照してください。 |
| enclaveAttestationProtocol String null |
(バージョン 8.2 以降) この省略可能なプロパティは、セキュア エンクレーブを使用する Always Encrypted に使用する構成証明プロトコルを示します。 現在、このフィールドでサポートされている値は HGS、AAS、NONE のみです (NONE はバージョン 11.2 以降でのみサポートされています)。 セキュリティで保護されたエンクレーブが設定された Always Encrypted の詳細については、「セキュア エンクレーブを使用する Always Encrypted」を参照してください。 |
| encrypt String null |
サーバーに証明書がインストールされている場合に、クライアントとサーバー間で送信されるすべてのデータに対して SQL Server で TLS 暗号化が使用されるようにするには、"true" に設定します。 既定値はバージョン 10.2 では "true"、9.4 以前では "false" です。 バージョン 6.0 以降では、既定で TLS 暗号化を使う新しい接続設定 "authentication" があります。 このプロパティの詳細については、「authentication」プロパティを参照してください。 バージョン 11.2.0 以降では、encrypt がブール値から文字列に変更され、このプロパティが strict に設定されている場合に TDS 8.0 のサポートが可能になりました。 |
| failoverPartner String null |
データベース ミラーリング構成で使用されるフェールオーバー サーバーの名前です。 このプロパティは、プリンシパル サーバーへの初期接続に失敗した場合に使用されます。 初期接続が行われた後は、このプロパティは無視されます。 databaseName プロパティと一緒に使用する必要があります。 注: 接続文字列の中で failoverPartner プロパティを指定するときに、フェールオーバー パートナー インスタンスのサーバー インスタンスのポート番号を指定することはできません。 ただし、ドライバーにより、プリンシパル サーバー インスタンスの serverName、instanceName、portNumber の各プロパティ、およびフェールオーバー パートナー インスタンスの failoverPartner プロパティを同じ接続文字列の中で指定することはできます。 Server 接続プロパティの仮想ネットワーク名を指定した場合は、データベース ミラーリングを使用できません。 ディザスター リカバリーの詳細については、「高可用性、ディザスター リカバリーのための JDBC Driver のサポート」を参照してください |
fipsboolean ["true" | "false"] "false" |
FIPS 対応 Java 仮想マシン (JVM) の場合、このプロパティを true にする必要があります。 |
| fipsProvider String null |
JVM で構成される FIPS プロバイダー。 たとえば、BCFIPS、SunPKCS11-NSS など。 バージョン 6.4.0 で削除されました。 詳細については、GitHub の問題 460 を参照してください。 |
| gsscredential org.ietf.jgss.GSSCredential null |
(バージョン 6.2 以降) Kerberos の制約付き委任に使用されるユーザー資格情報を、このプロパティに渡すことができます。 integratedSecurity を true、JavaKerberos を authenticationScheme に指定してこの設定を使う必要があります。 |
| hostNameInCertificate String null |
SQL Server TLS/SSL 証明書の検証に使われるホスト名。 hostNameInCertificate オプションを使用すると、証明書で使用される名前が、serverName プロパティに渡される名前と一致しない場合にホスト名を指定できます。 ただし、一致する場合は、hostNameInCertificate オプションを使用しないでください。 hostNameInCertificate プロパティが指定されていないか null に設定されている場合、SQL Server 用 Microsoft JDBC Driver は、接続 URL の serverName プロパティ値をホスト名として使用して SQL Server の TLS/SSL 証明書を検証します。 注: 上の段落で説明したように、証明書の名前が serverName オプションで渡された名前と一致しないことを確認できない限り、hostNameInCertificate オプションを設定することはお勧めしません。 注: このプロパティは、encrypt/authentication プロパティおよび trustServerCertificate プロパティと組み合わせて使用されます。 このプロパティが証明書の検証に影響するのは、接続で TLS 暗号化が使用されていて、trustServerCertificate が "false" に設定されている場合です。 TLS 接続が成功するには、hostNameInCertificate に渡される値が、サーバー証明書に含まれるサブジェクトの別名 (SAN) の共通名 (CN) または DNS 名と一致している必要があります。 暗号化のサポートの詳細については、「暗号化のサポートについて」を参照してください。 |
| INSTANCENAME String [<=128 文字] null |
接続するデータベース インスタンスの名前。 指定しない場合は、既定のインスタンスへの接続が確立されます。 instanceName と port の両方を指定する場合については、port の注を参照してください。 Server 接続プロパティの仮想ネットワーク名を指定した場合は、instanceName 接続プロパティを使用できません。 ディザスター リカバリーの詳細については、「高可用性、ディザスター リカバリーのための JDBC ドライバーのサポート」を参照してください。 |
| integratedSecurity boolean ["true" | "false"] false |
Windows オペレーティング システムの SQL Server によって Windows 資格情報が使用されていることを示すには、"true" に設定します。 "true" の場合、ユーザーがコンピューターまたはネットワークにサインインするときに指定した資格情報が、JDBC ドライバーによって、ローカル コンピューターの資格情報のキャッシュで検索されます。 Kerberos 資格情報が SQL Server によって使用されていることを示すには、(authenticationscheme=JavaKerberos で) "true" に設定します。 Kerberos 認証の詳細については、「Kerberos 統合認証による SQL Server への接続」を参照してください。 NTLM 資格情報が SQL Server によって使用されていることを示すには、(authenticationscheme=NTLM で) "true" に設定します。 "false" の場合は、ユーザー名とパスワードを指定する必要があります。 |
| ipaddresspreference String [<=128 文字] IPv4First |
クライアント アプリケーションで使用される IP の優先順位。 IPV4First を指定すると、ドライバーは最初に IPv4 アドレスを走査します。 正常に接続できる IPv4 アドレスがない場合、ドライバーは続けて IPv6 アドレスを試します (存在する場合)。 IPV6First を指定すると、ドライバーは最初に IPv6 アドレスを走査します。 正常に接続できる IPv6 アドレスがない場合、ドライバーは続けて IPv4 アドレスを試します (存在する場合)。 UsePlatformDefault を指定すると、ドライバーは DNS 解決からの最初の順序ですべての IP アドレスを走査します。 |
| jaasConfigurationName String SQLJDBCDriver |
(バージョン 6.2 以降) SQL Server への各接続で、Kerberos 接続を確立するための独自の JAAS ログイン構成名を使用することができます。 このプロパティを使用して、構成エントリの名前を渡すことができます。 このプロパティは、Kerberos 構成ファイルを作成するときに使用することを目的としています。 既定では、ドライバーは名前 SQLJDBCDriver を検索します。外部構成が見つからない場合、ドライバーは IBM JVM 用に useDefaultCcache = true を、他の JVM 用に useTicketCache = true を設定します。 |
| keyStoreAuthentication String null |
(バージョン 6.0 以降) このプロパティによって、Always Encrypted で使用するキー ストアが示され、キー ストアに対する認証に使用される認証メカニズムが決定されます。 "keyStoreAuthentication=JavaKeyStorePassword" を設定すると、ドライバーによって Java キー ストアのシームレスな設定がサポートされます。 このプロパティを使用するには、Java キー ストアに対して keyStoreLocation および keyStoreSecret プロパティも設定する必要があります。 Always Encrypted の詳細については、「JDBC ドライバーでの Always Encrypted の使用」を参照してください。 Microsoft JDBC Driver 8.4 以降では、"keyStoreAuthentication=KeyVaultManagedIdentity" または "keyStoreAuthentication=KeyVaultClientSecret" を設定することにより、マネージド ID を使用して Azure Key Vault に対する認証を行うこともできます。 Always Encrypted の詳細については、「JDBC ドライバーでの Always Encrypted の使用」を参照してください。 |
| keyStoreLocation String null |
(バージョン 6.0 以降) keyStoreAuthentication=JavaKeyStorePassword の場合、keyStoreLocation プロパティによって、Always Encrypted データで使用される列マスター キーを格納する Java キーストア ファイルへのパスが特定されます。 パスにはキーストア ファイル名を含める必要があります。 Always Encrypted の詳細については、「JDBC ドライバーでの Always Encrypted の使用」を参照してください。 |
| keyStorePrincipalId String null |
(バージョン 8.4 以降) keyStoreAuthentication=KeyVaultManagedIdentity の場合、keyStorePrincipalId プロパティによって有効な Microsoft Entra アプリケーション クライアント ID を指定します。 Always Encrypted の詳細については、「JDBC ドライバーでの Always Encrypted の使用」を参照してください。 |
| keyStoreSecret String null |
(バージョン 6.0 以降) keyStoreAuthentication=JavaKeyStorePassword の場合、keyStoreSecret プロパティによって、キーストアとキーに使用するパスワードが識別されます。 Java キー ストアを使用する場合、キーストアとキー パスワードは同じである必要があります。 Always Encrypted の詳細については、「JDBC ドライバーでの Always Encrypted の使用」を参照してください。 |
| lastUpdateCount boolean ["true" | "false"] true |
"true" 値は、サーバーに渡される SQL ステートメントからの最後の更新回数のみを返します。 また、サーバー トリガーによって発生する可能性がある他の更新回数を無視するために、単一の SELECT、INSERT、または DELETE ステートメントでのみ使用されます。 このプロパティを "false" に設定すると、サーバーのトリガーにより返されるこの更新数を含む、すべての更新数が返されます。 注: このプロパティが適用されるのは、executeUpdate メソッドと一緒に使用された場合だけです。 その他のすべての execute メソッドは、すべての結果および更新数を返します。 このプロパティは、サーバーのトリガーにより返される更新数にのみ影響します。 トリガーの実行の一部として得られる結果セットまたはエラーには影響しません。 |
| lockTimeout INT -1 |
データベースがロック タイムアウトを通知するまでに待機する時間 (ミリ秒) です。既定では、無期限に待機します。 ユーザーがこのプロパティに対する値を指定していなかった場合、この値は接続上のすべてのステートメントに対する既定値になります。 または、特定のステートメントに対するクエリのタイムアウトは、Statement.setQueryTimeout() を使用して設定できることに注意してください。 この値は、待機しないことを示す 0 に設定できます。 |
| loginTimeout INT [0..65535] 30 (バージョン 11.2 以降) 15 (バージョン 10.2 以前) |
ドライバーがタイムアウトを通知して接続を失敗させるまでに待機する時間 (秒) です。 ゼロ値は、タイムアウトがデフォルトのシステム タイムアウトであることを示す。 この値は、30 秒 (バージョン 11.2 以降の既定値) または 15 秒 (バージョン 10.2 以降の既定値) のいずれかです。 0 以外の値は、ドライバーがタイムアウトを通知して接続を失敗させるまでに待機する時間 (秒) を示します。 Server 接続プロパティの仮想ネットワーク名を指定する場合は、フェールオーバー接続が成功するまで十分な時間がとれるように、3 分以上のタイムアウト値を指定する必要があります。 ディザスター リカバリーの詳細については、「高可用性、ディザスター リカバリーのための JDBC Driver のサポート」を参照してください。 |
| maxResultBuffer String null |
(バージョン 9.2 以降) maxResultBuffer を使用して、結果セットを読み取るときの最大バイト数を設定できます。 指定しない場合、結果セット全体が読み取られます。 サイズは、次の 2 つのスタイルで指定できます。 1. サイズ (バイト) (たとえば 100、150M、300K、400G)2. 最大ヒープ メモリ (%) ( 10p、15pct、20percent)。 |
| msiClientId String null |
(非推奨) (バージョン 7.2 以降) ActiveDirectoryManagedIdentity または ActiveDirectoryMSI 認証モードで接続を確立するための accessToken の取得に使われるマネージド ID (MSI) のクライアント ID。 |
| multiSubnetFailover Boolean false |
SQL Server 可用性グループまたは SQL Server フェールオーバー クラスター インスタンスの可用性グループ リスナーに接続する際には、必ず multiSubnetFailover=true を指定してください。 multiSubnetFailover=true を指定すると、(現在) アクティブなサーバーを迅速に検出して接続するように、ドライバーが構成されます。 可能な値は、true と false です。 ディザスター リカバリーの詳細については、「高可用性、ディザスター リカバリーのための JDBC ドライバーのサポート」を参照してください。 getPropertyInfo、getMultiSubnetFailover、setMultiSubnetFailover がある multiSubnetFailover 接続プロパティには、プログラムからアクセスできます。 注: Microsoft JDBC Driver 6.0 for SQL Server 以降、可用性グループ リスナーに接続するために、multiSubnetFailover を "true" に設定する必要がなくなりました。 既定で有効になっている新しいプロパティ transparentNetworkIPResolution により、(現在) アクティブなサーバーの検出と接続が提供されます。 |
| packetSize INT [-1 | 0 | 512..32767] 8000 |
サーバーとの通信に使用されるネットワーク パケット サイズ (バイト単位)。 値 -1 は、サーバーの既定のパケット サイズが使用されることを示します。 値 0 は、最大値 32767 が使用されることを示します。 このプロパティが許容範囲外の値に設定されている場合は、例外が発生します。 重要: 暗号化が有効の場合 (encrypt=true)、packetSize プロパティを使うことは推奨されません。 使用すると、接続エラーが発生する可能性があります。 このプロパティの詳細については、SQLServerDataSource クラスの setPacketSize メソッドを参照してください。 |
| password String [<=128 文字] null |
SQL ユーザーとパスワードで接続する場合のデータベース パスワード。 プリンシパル名とパスワードを使用した Kerberos 接続の場合、このプロパティは Kerberos プリンシパル パスワードに設定されます。 (バージョン 10.2 以降) authentication=ActiveDirectoryServicePrincipal の場合、password プロパティによって、Active Directory プリンシパルに使用するパスワードが特定されます。 |
| portNumber, port INT [0..65535] 1433 |
サーバーがリッスンしているポート。 ポート番号が接続文字列に指定されている場合は、SQLbrowser に対する要求は作成されません。 port と instanceName の両方が指定されている場合は、指定されたポートへの接続が確立されます。 ただし、instanceName の検証が行われ、ポートと一致しない場合はエラーがスローされます。 重要: SQLbrowser を使用するよりセキュリティが向上するため、常にポート番号を指定することをお勧めします。 |
| prepareMethod String prepexec |
(バージョン 11.2.0 以降) prepared ステートメントでドライバーによって使用される基になる prepare メソッドを指定します。 prepare に設定すると、prepare メソッドとして sp_prepare を使用します。 この値に prepareMethod を設定することで、データベースに個別の初期トリップが発生し、実行計画でデータベースにおいて考慮すべき初期値なしでステートメントが準備されます。 prepexec に設定すると、prepare メソッドとして sp_prepexec を使用します。 このメソッドは、準備アクションと最初の実行を組み合わせて、ラウンド トリップを減らします。 また、実行プランでデータベースにおいて考慮する可能性がある初期パラメーター値もデータベースに提供されます。 |
| queryTimeout INT -1 |
クエリでタイムアウトが発生するまでに待機する秒数。 既定値は -1 です。これはタイムアウトが無期限であることを意味します。 この値を 0 に設定した場合も、無期限の待機を意味します。 |
| realm String null |
(バージョン 9.4+) Kerberos 認証の領域。 この値を設定して、サーバーの領域からドライバーによって自動検出される、Kerberos 認証領域をオーバーライドします。 |
| レプリケーション boolean ["true" | "false"] false |
(バージョン 9.4+) 接続をレプリケーションに使用するかどうかがこの設定によりサーバーに通知されます。 有効にすると、NOT FOR REPLICATION オプションを使ったトリガーは、接続で起動されません。 |
| responseBuffering String ["full" | "adaptive"] adaptive |
このプロパティを "adaptive" に設定すると、必要に応じて最小限のデータがバッファリングされます。 既定のモードは "adaptive" です。 このプロパティが "full" に設定されている場合、ステートメントの実行時に結果セット全体がサーバーから読み取られます。 注: JDBC ドライバー バージョン 1.2 以降、既定のバッファーリング動作は "adaptive" になります。アプリケーションでバージョン 1.2 の既定の動作を維持したい場合は、接続プロパティで、または SQLServerStatement オブジェクトの setResponseBuffering メソッドを使って、responseBufferring プロパティを "full" に設定します。 |
| selectMethod String ["direct" | "cursor"] 直接 |
このプロパティが "cursor" に設定されている場合、TYPE_FORWARD_ONLY および CONCUR_READ_ONLY のカーソルに対して接続上で作成されるクエリごとに、データベース カーソルが作成されます。 このプロパティは、通常、クライアントのメモリ内に収まらない大きな結果セットをアプリケーションが生成する場合にのみ必要です。 このプロパティが "cursor" に設定されると、結果セットの行が限定された数だけクライアントのメモリに保持されます。 既定の動作では、すべての結果セットの行がクライアントのメモリに保持されます。 この動作により、アプリケーションがすべての行を処理する場合は、パフォーマンスが最も高くなります。 |
| sendStringParameters... AsUnicode boolean ["true" | "false"] true |
sendStringParametersAsUnicode プロパティが "true" に設定されている場合、文字列パラメーターは Unicode 形式でサーバーに送信されます。 sendStringParametersAsUnicode プロパティが "false" に設定されている場合、文字列パラメーターは、Unicode ではなく ASCII/MBCS などの Unicode 以外の形式でサーバーに送信されます。 sendStringParametersAsUnicode プロパティの既定値は "true" です。 注:sendStringParametersAsUnicode プロパティは、CHAR、VARCHAR、または LONGVARCHAR の各 JDBC 型のパラメーター値を送信するときにのみチェックされます。 JDBC 4.0 の新しい各国文字集合メソッドには、SQLServerPreparedStatement クラスと SQLServerCallableStatement クラスの setNString、setNCharacterStream、setNClob などのメソッドが含まれます。 これらのメソッドは、このプロパティの設定に関係なく、常に Unicode でサーバーにパラメーター値を送信します。 CHAR、VARCHAR、LONGVARCHAR などの JDBC データ型の使用に伴うパフォーマンスを最適に保つためには、アプリケーションで、sendStringParametersAsUnicode プロパティを "false" に設定し、National Character メソッド以外のメソッドである、SQLServerPreparedStatement クラスおよび SQLServerCallableStatement クラスの setString、setCharacterStream、および setClob を使用する必要があります。 アプリケーションで sendStringParametersAsUnicode プロパティが "false" に設定されていて、National Character メソッド以外のメソッドを使用してサーバー側の Unicode データ型 (nchar、nvarchar、ntext など) にアクセスする場合に、National Character メソッド以外のメソッドで渡される文字列パラメーターの文字がデータベース照合順序でサポートされていないときには、一部のデータが失われる可能性があります。 アプリケーションでは、NCHAR、NVARCHAR、LONGNVARCHAR の各 JDBC データ型に対して、SQLServerPreparedStatement クラスおよび SQLServerCallableStatement クラスの National Character メソッドである setNString、setNCharacterStream、および setNClob を使用する必要があります。 この値を変更すると、データベースからの結果の並べ替えに影響する可能性があります。 並べ替えの違いは、Unicode と Unicode 以外の文字の並べ替え規則が異なるためです。 |
| sendTemporalDataTypes... AsStringForBulkCopy boolean ["true" | "false"] true |
(バージョン 8.4 以降) この接続プロパティを "false" に設定すると、DATE、DATETIME、DATIMETIME2、DATETIMEOFFSET、SMALLDATETIME、TIME データ型は、文字列としてではなく、それぞれの型として送信されます。 この接続プロパティが "false" に設定されている場合、次の例のように、ドライバーによって各テンポラル データ型の既定の文字列リテラル形式のみが受け入れられます。 DATE: YYYY-MM-DDDATETIME: YYYY-MM-DD hh:mm:ss[.nnn]DATETIME2: YYYY-MM-DD hh:mm:ss[.nnnnnnn]DATETIMEOFFSET: YYYY-MM-DD hh:mm:ss[.nnnnnnn] [{+/-}hh:mm]SMALLDATETIME: YYYY-MM-DD hh:mm:ssTIME: hh:mm:ss[.nnnnnnn] |
| sendTimeAsDatetime boolean ["true" | "false"] true |
このプロパティは SQL Server JDBC Driver 3.0 で追加されました。 "true" に設定すると、java.sql.Time 値は SQL Server の datetime 値としてサーバーに送信されます。 "false" に設定すると、java.sql.Time 値は SQL Server の time 値としてサーバーに送信されます。 このプロパティの既定値は、現在は "true" ですが、将来のリリースで変更される可能性があります。 java.sql.Time 値をサーバーに送信する前に SQL Server 用 Microsoft JDBC Driver でその値を構成する方法の詳細については、「java.sql.Time の値をサーバーに送信する方法の構成」を参照してください。 |
| serverCertificate, server String null |
(バージョン 11.2.0 以降) サーバー証明書ファイルへのパス。 strict に設定された encrypt を使用する場合の検証に使用されます。 ドライバーは、PEM ファイル形式を使用して証明書ファイルをサポートします。 |
| serverName, server String null |
SQL Server が実行されているコンピューターまたは Azure SQL データベース。 可用性グループの仮想ネットワーク名を指定することもできます。 ディザスター リカバリーの詳細については、「高可用性、ディザスター リカバリーのための JDBC Driver のサポート」を参照してください。 |
| serverNameAsACE boolean ["true" | "false"] false |
(バージョン 6.0 以降) "true" に設定すると、ドライバーが Unicode のサーバー名を互換性のある ASCII エンコード (Punycode) に変換して接続する必要があることを示します。 この設定が false の場合、ドライバーは、提供されたサーバー名を使用して接続します。 国際化機能の詳細については、「JDBC ドライバーの国際化機能」を参照してください。 |
| serverPreparedStatement... DiscardThreshold Integer 10 |
(バージョン 6.2 以降) このプロパティを使用して、サーバー上の未処理のハンドルをクリーンアップするための呼び出しが実行される前に、1 つの接続に対して許される未処理の準備されたステートメント破棄アクション (sp_unprepare) の数を制御できます。 このプロパティを <= 1 に設定すると、準備解除アクションは、準備されたステートメントの終了時に直ちに実行されます。 プロパティが > 1 に設定される場合、これらの呼び出しは、sp_unprepare を頻繁に呼び出すことによるオーバーヘッドを回避するために、まとめてバッチ処理されます。 |
| serverSpn String null |
(バージョン 4.2 以降) このオプションのプロパティを使用して、Java Kerberos 接続のサービス プリンシパル名 (SPN) を指定できます。 これは、authenticationScheme と共に使用されます。 SPN を指定するには、"MSSQLSvc/fqdn:port@REALM" の形式を使用できます。ここで、fqdn は完全修飾ドメイン名、port はポート番号、REALM は大文字で表記された SQL Server の Kerberos 領域です。 注: クライアントの既定の領域 (Kerberos 構成で指定した領域) が SQL Server の Kerberos 領域と同じである場合は、@REALM は省略できます。 Java Kerberos での serverSpn の使用の詳細については、「Kerberos 統合認証による SQL Server への接続」を参照してください。 |
| socketFactoryClass String null |
(バージョン 8.4 以降) 既定のソケット ファクトリの代わりに使用するカスタム ソケット ファクトリのクラス名を指定します。 |
| socketTimeout INT 0 |
ソケットの読み取りまたは受け入れで、タイムアウトが発生する前に待機するミリ秒数。 既定値は 0 です。これはタイムアウトが無期限であることを意味します。 |
| statementPooling... CacheSize INT 0 |
(バージョン 6.4 以降) このプロパティを使用して、ドライバーで準備されたステートメント ハンドルのキャッシュを有効にすることができます。 このプロパティにより、ステートメント プールのキャッシュのサイズが定義されます。 このプロパティは、disableStatementPooling 接続プロパティ ("false" に設定する必要があります) と併用することだけができます。 disableStatementPooling を "true" または statementPoolingCacheSize を 0 に設定すると、準備されたステートメント ハンドルのキャッシュが無効になります。 |
| sslProtocol String TLS |
(バージョン 6.4 以降) このプロパティを使用して、セキュリティで保護された接続時に考慮する TLS プロトコルを指定できます。 次のいずれかの値になります。TLS、TLSv1、TLSv1.1、TLSv1.2。 Secure Sockets Layer プロトコルの詳細については、「SSLProtocol」を参照してください。 |
| transparentNetwork... IPResolution boolean ["true" | "false"] true |
(バージョン 6.0 以降) このプロパティを指定すると、(現在) アクティブなサーバーを迅速に検出して接続できます。 指定できる値は "true" と "false" です。 "true" は既定値です。 Microsoft JDBC Driver 6.0 for SQL Server より前のバージョンでは、Always On 可用性グループに接続していることを示すために、アプリケーションで "multiSubnetFailover=true" を含めるように接続文字列を設定する必要がありました。 multiSubnetFailover 接続キーワードを "true" に設定しないと、アプリケーションで Always On 可用性グループに接続中にタイムアウトが発生する可能性がありました。 バージョン 6.0 以降では、アプリケーションで multiSubnetFailover を true に設定する必要がなくなりました。 注: transparentNetworkIPResolution=true の場合、最初の接続試行では、タイムアウトとして 500 ミリ秒が使用されます。 その後の試行では、multiSubnetFailover プロパティで使用されているのと同じタイムアウト ロジックが使用されます。 |
| trustManagerClass String null |
(バージョン 6.4 以降) カスタム javax.net.ssl.TrustManager 実装の完全修飾クラス名。 |
| trustManager... ConstructorArg String null |
(バージョン 6.4 以降) TrustManager のコンストラクターに渡す省略可能な引数。 trustManagerClass プロパティが指定され、暗号化された接続が要求された場合、既定のシステム JVM キーストアベースの TrustManager の代わりに、カスタム TrustManager が使用されます。 |
| trustServerCertificate boolean ["true" | "false"] false |
ドライバーによってサーバーの TLS/SSL 証明書が検証されないようにするには、"true" に設定します。 "true" の場合、通信レイヤーが TLS で暗号化されていると、サーバーの TLS/SSL 証明書は自動的に信頼されます。 "false" の場合は、ドライバーによってサーバーの TLS/SSL 証明書が検証されます。 サーバー証明書の検証が失敗した場合は、ドライバーでエラーが発生して接続が終了します。 既定値は "false" です。 TLS/SSL 接続が成功するには、serverName に渡される値が、サーバー証明書に含まれるサブジェクトの別名の共通名 (CN) または DNS 名と厳密に一致している必要があります。 暗号化のサポートの詳細については、「暗号化のサポートについて」を参照してください。 注: このプロパティは、encrypt/authentication プロパティと組み合わせて使用されます。 このプロパティがサーバーの TLS/SSL 証明書の検証に影響するのは、接続で TLS 暗号化が使用される場合です。 |
| trustStore String null |
証明書の trustStore ファイルへのパス (ファイル名を含む) です。 trustStore ファイルには、クライアントが信頼する証明書の一覧が含まれています。 このプロパティが指定されていないか null に設定されている場合、ドライバーは、信頼マネージャー ファクトリの検索ルールに従って、使用する証明書ストアを決定します。 既定の SunX509 TrustManagerFactory では、次の順序で信頼済みマテリアルの検索が行われます。 JVM システム プロパティの "javax.net.ssl.trustStore" で指定されたファイル。 <java-home>/lib/security/jssecacerts ファイル。<java-home>/lib/security/cacerts ファイル。SUNX509 TrustManager Interface の詳細については、Sun Microsystems の Web サイトにある SUNX509 TrustManager Interface に関するドキュメントを参照してください。 注: このプロパティが証明書の trustStore の検索に影響するのは、接続で TLS 暗号化が使用され、trustServerCertificate プロパティが "false" に設定されている場合です。 |
| trustStorePassword String null |
trustStore データの整合性を確認するために使用するパスワードです。 trustStore プロパティは設定されているが trustStorePassword プロパティは設定されていない場合、trustStore の整合性は確認されません。 trustStore プロパティと trustStorePassword プロパティの両方が指定されていない場合、ドライバーでは、JVM システム プロパティの "javax.net.ssl.trustStore" と "javax.net.ssl.trustStorePassword" が使用されます。 "javax.net.ssl.trustStorePassword" システム プロパティが指定されていない場合、trustStore の整合性は確認されません。 ユーザーが trustStore プロパティを設定せず、trustStorePassword プロパティを設定した場合、JDBC ドライバーは 、"javax.net.ssl.trustStore" が信頼ストアとして指定するファイルを使用します。 さらに、ドライバーは、指定した trustStorePassword を使用して信頼ストアの整合性を確認します。 この設定は、クライアント アプリケーションでパスワードを JVM システム プロパティに格納しないようにする場合に必要です。 注: trustStorePassword プロパティが証明書の trustStore の検索に影響するのは、接続で TLS 接続が使用され、trustServerCertificate プロパティが "false" に設定されている場合です。 |
| trustStoreType String JKS |
FIPS モードで使用する信頼ストアの種類を指定するには、このプロパティを設定します。 指定できる値は、PKCS12 または FIPS プロバイダーによって定義された種類です。 |
| useBulkCopyFor... BatchInsert boolean ["true" | "false"] false |
(バージョン 9.2 以降) この接続プロパティを有効にすると、java.sql.PreparedStatement を使用してバッチ挿入操作を行うときに、一括コピー API を透過的に使用できます。 この機能を有効にすると、パフォーマンスが向上する可能性があります。 この機能は、既定では無効化されています。 この機能を有効にするには、このプロパティを "true" に設定します。 重要な注意事項: この機能は、完全にパラメーター化された INSERT クエリのみをサポートします。 INSERT クエリが他の SQL クエリによって結合された場合、または値にデータが含まれている場合、実行は基本的なバッチ挿入操作にフォールバックします。 このプロパティの使用方法の詳細については、「バッチ挿入操作に一括コピー API を使用する」を参照してください |
| useDefaultGSSCredential boolean ["true" | "false"] false |
(バージョン 12.6 以降) Kerberos 認証にネイティブ GSS-API を使用するために、ドライバーがユーザーの代わりに GSSCredential を作成する必要があるかどうかを示すフラグ。 |
| useDefaultJaasConfig boolean ["true" | "false"] false |
(バージョン 12.6 以降) システム レベルで JAAS を構成するライブラリと共にアプリケーションが存在する場合、このプロパティを true に設定すると、ドライバーは同じ構成を使用して Kerberos 認証を実行できます。 |
| useFmtOnly boolean ["true" | "false"] false |
(バージョン 7.4 以降) サーバーからパラメーター メタデータのクエリを実行する別の方法が提供されます。 パラメーター メタデータのクエリを実行するときに、ドライバーで SET FMTONLY ロジックを使用する必要があることを指定するには、このプロパティを "true" に設定します。 この機能は既定ではオフになっています。SET FMTONLY は非推奨としてマークされているため、このプロパティを使用することは推奨されていません。 useFmtOnly は、sp_describe_undeclared_parameters の既知の問題と制限の回避策としてのみ使用できます。現在、この機能では、単一の SELECT/INSERT/UPDATE/DELETE クエリのみがサポートされています。 サポートされていないクエリまたは複数のクエリでこの機能を使用しようとすると、ドライバーではクエリの解析が試行されますが、ほとんどの場合、例外が発生します。このプロパティの詳細については、「UseFmtOnly を使用した ParameterMetaData の取得」を参照してください。 |
| userName, user String [<=128 文字] null |
SQL ユーザーとパスワードが接続されている場合のデータベース ユーザー。 プリンシパル名とパスワードを使用した Kerberos 接続の場合、このプロパティは Kerberos プリンシパル名に設定されます。 (バージョン 10.2 以降) authentication=ActiveDirectoryServicePrincipal の場合は、userName プロパティによって、Azure Active Directory のセキュリティ保護された有効なクライアント ID が指定されます。 |
| workstationID String [<=128 文字] <empty string> |
ワークステーション ID。 個別のワークステーションを識別するために、さまざまなプロファイリング ツールおよびロギング ツールで使用されます。 何も指定しない場合、 <empty string> が使用されます。 |
| xopenStates boolean ["true" | "false"] false |
"true" に設定すると、ドライバーが XOPEN 互換の状態コードを例外で返します。 既定では、SQL 99 の状態コードを返します。 |
注意
SQL Server 用 Microsoft JDBC Driver は、ANSI_DEFAULTS および IMPLICIT_TRANSACTIONS 以外の接続プロパティのサーバー既定値を受け取ります。 SQL Server 用 Microsoft JDBC Driver によって、ANSI_DEFAULTS は ON に、IMPLICIT_TRANSACTIONS は OFF に自動的に設定されます。
重要
認証に ActiveDirectoryPassword が設定されている場合、次のライブラリがクラスパスに含められている必要があります: microsoft-authentication-library-for-java。 Maven リポジトリ で見つけることができます。 ライブラリとその依存関係をダウンロードする最も簡単な方法は、Maven を使用することです。
- システムに Maven をインストールします
- ドライバーの GitHub ページ へ移動します。
- pom.xml ファイルをダウンロードします。
- 次の Maven コマンドを実行して、ライブラリとその依存関係をダウンロードします:
mvn dependency:copy-dependencies