接続プロパティを設定する

JDBC ドライバーのダウンロード

接続文字列プロパティは、さまざまな方法で指定できます。

• DriverManager クラスを使用して接続する際、接続 URL に <name>=<value> のプロパティを設定します。 接続文字列の構文については、「接続 URL の構築」を参照してください。

• <name>=<value>プロパティとして、DriverManager クラスの Connect メソッドの Properties パラメーター。

• ドライバーのデータ ソースの適切な setter メソッドの値として指定できます。 次に例を示します。

  datasource.setServerName(value)
  datasource.setDatabaseName(value)
  

解説

• プロパティ名では大文字と小文字が区別されません。 ドライバーは、次の順序で重複するプロパティ名を解決します。

  1. api 引数 ( user や password
  2. プロパティ コレクション
  3. 接続文字列の最後のインスタンス

• プロパティ名には不明な値を使用できます。 JDBC ドライバーでは、大文字と小文字の区別は検証されません。

• シノニムを使用できます。 ドライバーは、重複するプロパティ名の場合と同様に、順番に解決します。

• Microsoft JDBC Driver for SQL Serverは、ANSI_DEFAULTS と IMPLICIT_TRANSACTIONS を除き、接続プロパティのサーバーの既定値を受け取ります。 Microsoft JDBC Driver for SQL Serverは、ANSI_DEFAULTS を ON に、IMPLICIT_TRANSACTIONS を OFF に自動的に設定します。

• 認証を ActiveDirectoryPassword [DEPRECATED] に設定する場合は、クラスパスに次のライブラリを含めます: microsoft-authentication-library-for-java。 Maven リポジトリで検索します。 ライブラリとその依存関係をダウンロードする最も簡単な方法は、Maven を使用することです。

  1. Maven をシステムにインストールします。
  2. ドライバーの GitHub ページに移動します。
  3. pom.xml ファイルをダウンロードします。
  4. 次の Maven コマンドを実行して、ライブラリとその依存関係をダウンロードします: mvn dependency:copy-dependencies。

プロパティ

以降のセクションでは、JDBC ドライバーで現在使用可能なすべての接続文字列プロパティについて説明します。

accessToken

• 型: String
• 既定: null

(バージョン 6.0 以降) このプロパティを使用し、アクセス トークンを使ってデータベースに接続します。 接続 URL を使用して accessToken を設定することはできません。

accessTokenCallbackClass

• 型: String
• 既定: null

(バージョン 12.4 以降)アクセス トークン コールバックで使用するコールバック実装クラスの名前。

applicationIntent

• 型: String
• 既定: ReadWrite

(バージョン 6.0 以降) サーバーに接続するためのアプリケーション ワークロードのタイプを宣言します。

設定可能な値は ReadOnly および ReadWrite です。

ディザスター リカバリーの詳細については、「高可用性、ディザスター リカバリーのための JDBC Driver のサポート」を参照してください。

applicationName

• 型: String [<=128 char]
• 既定: null

アプリケーション名。名前を指定しない場合は "Microsoft JDBC Driver for SQL Server" です。

この名前を使用して、さまざまなSQL Serverプロファイルおよびログ ツールで特定のアプリケーションを識別します。

authentication

• 型: String
• 既定: NotSpecified

(バージョン 6.0 以降) この省略可能なプロパティは、接続に使用する認証方法を示します。

使用できる値は、 ActiveDirectoryIntegrated、 ActiveDirectoryManagedIdentity (バージョン 12.2 以降)、 ActiveDirectoryMSI (バージョン 7.2 以降)、 ActiveDirectoryInteractive (バージョン 9.2 以降)、 ActiveDirectoryServicePrincipal (バージョン 9.2 以降)、 ActiveDirectoryPassword [DEPRECATED]、 SqlPassword、既定の NotSpecifiedです。

統合Windows 認証を使用して SQL に接続するには、ActiveDirectoryIntegrated (バージョン 6.0 以降) を使用します。

ActiveDirectoryManagedIdentity (バージョン 12.2 以降) または ActiveDirectoryMSI (バージョン 7.2 以降) を使用して、Azure リソース内から SQL に接続します。 たとえば、マネージド ID 認証を使用するAzure仮想マシン、App Service、Function App などです。

ActiveDirectoryManagedIdentityまたはActiveDirectoryMSI認証モードを使用する場合、ドライバーでサポートされるマネージド ID の 2 種類は次のとおりです。

• システムで割り当てられた管理された ID: 既定で accessToken を取得するために使用されます。

• User-Assigned マネージド ID: マネージド ID のクライアント ID が accessToken接続プロパティで指定されている場合に取得するために使用されます。

対話型認証フローを使用してデータベースに接続するには、 ActiveDirectoryInteractive を使用します。

ActiveDirectoryServicePrincipal (バージョン 9.2 以降) を使用して、サービス プリンシパル ID のクライアント ID とシークレットを使用してデータベースに接続します。 userName プロパティにクライアント ID を指定し、password プロパティ (10.2 以降) にシークレットを指定します。

ActiveDirectoryServicePrincipalCertificate (バージョン 12.4 以降) を使用して、サービス プリンシパル ID のクライアント ID と証明書を使用してデータベースに接続します。 userName プロパティにクライアント ID を指定し、clientCertificate プロパティの証明書へのパスを指定します。

その他のオプションについては、「 ActiveDirectoryServicePrincipalCertificate 認証モードを使用した接続」を参照してください。

ActiveDirectoryPassword [DEPRECATED] を使用して、Microsoft Entra プリンシパル名とパスワードを使用して SQL に接続します。

ActiveDirectoryPassword は非推奨です。

詳細については、「ActiveDirectoryPassword 認証モードを使用して接続する」を参照してください。

SqlPasswordを使用して、userName/userプロパティとpasswordプロパティを使用して SQL に接続します。

これらの認証方法が必要ない場合は、 NotSpecified を使用します。

認証プロパティを NotSpecified 以外の値に設定すると、ドライバーはトランスポート層セキュリティ (TLS) (以前は Secure Sockets Layer (SSL) と呼ばれ、既定では暗号化を使用します。

Microsoft Entra認証を構成する方法については、Azure SQL の 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 データベースにサーバーが見つからない)。

の使用の詳細については、「 Kerberos 統合認証を使用して SQL Serverを参照してください。

authenticationScheme=NTLMを使用する場合は、domain プロパティまたは domainName プロパティ、user または userName プロパティのWindows資格情報、および password プロパティを使用して、Windows ドメインを指定する必要があります。 これを行わないと、エラーが発生します (接続プロパティを指定する必要があります)。

bulkCopyForBatchInsertAllowEncryptedValueModifications

• 型: Boolean [true | false]
• 既定: false

(バージョン 12.10 以降) useBulkCopyForBatchInsert を true に設定する場合は、このオプションを true に設定して、データを復号化せずに、テーブルまたはデータベース間で暗号化されたデータを一括コピーできるようにします。

このプロパティの使用に関する詳細と警告については、allowEncryptedValueModificationsの オプションを参照してください。

bulkCopyForBatchInsertBatchSize

• 型: int
• 既定: 0

(バージョン 12.10 以降) useBulkCopyForBatchInsert を true に設定すると、このプロパティは、ドライバーがバッチ挿入操作から作成する一括コピー操作のバッチ サイズを指定します。

この設定の効果の詳細については、BatchSizeの オプションを参照してください。

bulkCopyForBatchInsertCheckConstraints

• 型: Boolean [true | false]
• 既定: false

(バージョン 12.10 以降) useBulkCopyForBatchInsert=trueを使用する場合は、このオプションを true に設定して、データの挿入中に check 制約を有効にします。 チェック制約を無効にするには、このオプションを false に設定します。

この設定の効果の詳細については、CheckConstraintsの オプションを参照してください。

bulkCopyForBatchInsertFireTriggers

• 型: Boolean [true | false]
• 既定: false

(バージョン 12.10 以降) useBulkCopyForBatchInsert=trueを使用する場合は、このオプションを true に設定して、データベースへの行の挿入中に挿入トリガーを起動できるようにします。 挿入トリガーを無効にするには、このオプションを false に設定します。

この設定の効果の詳細については、FireTriggersの オプションを参照してください。

bulkCopyForBatchInsertKeepIdentity

• 型: Boolean [true | false]
• 既定: false

(バージョン 12.10 以降) useBulkCopyForBatchInsert=trueを使用する場合は、このオプションを true に設定して、データの挿入中にソース ID 値を保持します。 このオプションを false に設定して、宛先によって ID 値を割り当てます。

この設定の効果の詳細については、KeepIdentityの オプションを参照してください。

bulkCopyForBatchInsertKeepNulls

• 型: Boolean [true | false]
• 既定: false

(バージョン 12.10 以降) useBulkCopyForBatchInsert=trueを使用する場合は、このオプションを true に設定して、既定値の設定に関係なく、ターゲット テーブル内の null 値を保持します。 このオプションを false に設定すると、宛先の既定値が null 値に置き換えられます。

この設定の効果の詳細については、KeepNullsの オプションを参照してください。

bulkCopyForBatchInsertTableLock

• 型: Boolean [true | false]
• 既定: false

(バージョン 12.10 以降) useBulkCopyForBatchInsert を true に設定した場合は、このオプションを true に設定して、一括コピー操作中に一括更新ロックを取得します。 行ロックを使用するには、このオプションを false に設定します。

この設定の効果の詳細については、TableLockの オプションを参照してください。

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 ファイルの秘密キーにアクセスするための省略可能なパスワード文字列を指定します。

詳細については、「ループバック シナリオにおけるクライアント証明書の認証」を参照してください。

列の暗号化設定

• 型: String [Enabled | Disabled]
• 既定: Disabled

(バージョン 6.0 以降)Always Encrypted (AE) 機能を使用するには、 Enabled に設定します。 AE を有効にすると、JDBC ドライバーによって、サーバーの暗号化されたデータベースの列に格納されている機密データの透過的な暗号化と暗号化解除が行われます。

Always Encrypted の詳細については、「 JDBC ドライバーで Always Encrypted を使用する」を参照してください。

concatNullYieldsNull

• 型: String [ON | OFF]
• 既定: ON

(バージョン 13.2 以降)このオプションを OFF に設定すると、ドライバーは、接続を確立するときにデータベース セッション変数 CONCAT_NULL_YIELDS_NULL を OFF に設定します。 結果として、null 値と文字列を連結すると、文字列自体が生成されます (null 値は空の文字列として扱われます)。

詳細については、「SET CONCAT_NULL_YIELDS_NULL」を参照してください。

connectRetryCount

• 型: int [0..255]
• 既定: 1

(バージョン 9.4 以降) 接続に障害が発生した場合の再接続試行回数。

connectRetryInterval

• 型: int [1..60]
• 既定: 10

(バージョン 9.4+) 接続再試行間の秒数。

データベース名、データベース

• 型: String [<=128 char]
• 既定: 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 オブジェクト全体がメモリに読み込まれます。

disableStatementPooling

• 型: Boolean [true | false]
• 既定: true

ステートメント プールを使用するかどうかを示すフラグ。

domainName、ドメイン

• 型: String
• 既定: null

(バージョン 7.4 以降)NTLM 認証を使用するときに認証するWindows ドメイン。

enablePrepareOnFirstPreparedStatementCall

• 型: Boolean [true | false]
• 既定: false

準備されたステートメントの最初の実行でtrueを呼び出して、準備されたステートメント ハンドルの作成を有効にするには、sp_prepexecに設定します。

準備されたステートメントの最初の実行を変更して、falseを呼び出し、ステートメントを準備しないようにするには、sp_executesqlに設定します。 2 回目の実行が行われると、sp_prepexec が呼び出され、準備されたステートメントのハンドルが設定されます。

enclaveAttestationProtocol

• 型: String
• 既定: null

(バージョン 8.2 以降) この省略可能なプロパティは、セキュア エンクレーブを使用する Always Encrypted に使用する構成証明プロトコルを示します。 現在、このフィールドでサポートされている値は、 HGS、 AAS、および NONE のみです (NONE はバージョン 11.2 以降でのみサポートされています)。

セキュリティで保護されたエンクレーブがある Always Encrypted の詳細については、 JDBC ドライバーでのセキュリティで保護されたエンクレーブでの Always Encrypted の使用を参照してください。

enclaveAttestationUrl

• 型: String
• 既定: null

(バージョン 8.2 以降) この省略可能なプロパティは、セキュリティで保護されたエンクレーブでの Always Encrypted に使用する構成証明サービスのエンドポイント URL を示します。

セキュリティで保護されたエンクレーブがある Always Encrypted の詳細については、 JDBC ドライバーでのセキュリティで保護されたエンクレーブでの Always Encrypted の使用を参照してください。

暗号化する

• 型: String
• 既定: null

true に設定すると、サーバーに証明書がインストールされている場合に、クライアントとサーバーの間で送信されるすべてのデータに対して SQL データベース エンジンが TLS 暗号化を使用するように指定します。 既定値はバージョン 10.2 以降で true され、9.4 以前では false 。

バージョン 6.0 以降では、既定で TLS 暗号化を使用する新しい接続設定 authentication があります。

このプロパティの詳細については、 authentication プロパティを参照してください。

バージョン 11.2.0 以降では、 encrypt が Boolean から string に変更され、プロパティが strict に設定されている場合に TDS 8.0 のサポートが可能になりました。

バージョン 10.2 での既定の変更は重大な変更です。 9.4 以前からアップグレードしていて、サーバーに有効な TLS 証明書がない場合は、 trustServerCertificate を true に設定するか、有効な証明書を指定します。

フェイルオーバーパートナー

• 型: String
• 既定: null

データベース ミラーリング構成で使用されるフェールオーバー サーバーの名前です。 このプロパティは、プリンシパル サーバーへの初期接続に失敗した場合に使用されます。 初期接続が行われた後は、このプロパティは無視されます。 databaseName プロパティと共に使用する必要があります。

Server 接続プロパティにVirtual Network名を指定した場合、データベース ミラーリングは使用できません。

ディザスター リカバリーの詳細については、「高可用性、ディザスター リカバリーのための JDBC Driver のサポート」を参照してください。

FIPS

• 型: Boolean [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 に設定されている場合、Microsoft JDBC Driver for SQL Serverは、接続 URL の serverName プロパティ値をホスト名として使用して、SQL Server TLS/SSL 証明書を検証します。

このプロパティは、 encrypt プロパティ、 authentication プロパティ、および trustServerCertificate プロパティと組み合わせて使用します。 接続で TLS 暗号化が使用され、 trustServerCertificate が false に設定されている場合、このプロパティは証明書の検証に影響します。 hostNameInCertificateに渡す値が、TLS 接続を成功させるためにサーバー証明書のサブジェクト代替名 (SAN) の共通名 (CN) または DNS 名と一致していることを確認します。

暗号化のサポートの詳細については、「暗号化のサポートについて」を参照してください。

Instancename

• 型: String [<=128 char]
• 既定: null

接続するデータベース インスタンスの名前。 このプロパティを指定しない場合は、既定のインスタンスに接続します。 instanceNameとポートの両方を指定する場合は、ポートの注意事項を参照してください。

Server 接続プロパティにVirtual Network名を指定した場合、instanceName 接続プロパティを使用することはできません。

ディザスター リカバリーの詳細については、「高可用性、ディザスター リカバリーのための JDBC Driver のサポート」を参照してください。

integratedSecurity

• 型: Boolean [true | false]
• 既定: false

true に設定すると、Windowsオペレーティングシステム上のSQL ServerがWindows資格情報を使用していることを示します。 true場合、JDBC ドライバーは、ユーザーがコンピューターまたはネットワークにサインインしたときに指定された資格情報をローカル コンピューターの資格情報キャッシュで検索します。

Kerberos 資格情報がSQL Serverによって使用されることを示すには、true (authenticationscheme=JavaKerberos を使用) に設定します。

Kerberos 認証の詳細については、「Kerberos 統合認証による SQL Server への接続」を参照してください。

NTLM 資格情報がSQL Serverによって使用されることを示すには、true (authenticationscheme=NTLM) に設定します。

false場合は、ユーザー名とパスワードを指定する必要があります。

ipaddresspreference

• 型: String [<=128 char]
• 既定: 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 プロパティも設定する必要があります。

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 に設定すると、サーバーによってトリガーが返されるものも含め、すべての更新回数が返されます。

lockTimeout

• 型: int
• 既定: -1

データベースがロック タイムアウトを報告するまでの待機時間 (ミリ秒)。 既定の動作では、無期限に待機します。 このプロパティの値を指定しない場合、この値は接続上のすべてのステートメントの既定値です。

または、 Statement.setQueryTimeout() を使用して、特定のステートメントのクエリ タイムアウトを設定します。 この値は、待機しないことを示す 0 に設定できます。

loginTimeout

• 型: int [0..65535]
• 既定値: 30 (バージョン 11.2 以降)、または 15 (バージョン 10.2 以前)

ドライバーがタイムアウトを通知して接続を失敗させるまでに待機する時間 (秒) です。 ゼロ値は、タイムアウトがデフォルトのシステム タイムアウトであることを示す。 この値は、30 秒 (バージョン 11.2 以降の既定値) または 15 秒 (バージョン 10.2 以前の既定値) のいずれかです。 0 以外の値は、ドライバーがタイムアウトを通知して接続を失敗させるまでに待機する時間 (秒) を示します。

Server 接続プロパティにVirtual Network名を指定する場合は、フェールオーバー接続が成功するのに十分な時間を確保するために、タイムアウト値を 3 分以上指定します。

ディザスター リカバリーの詳細については、「高可用性、ディザスター リカバリーのための JDBC Driver のサポート」を参照してください。

maxResultBuffer

• 型: String
• 既定: null

(バージョン 9.2 以降) maxResultBuffer を使用して、結果セットを読み取るときに読み取る最大バイト数を設定します。 この値を指定しない場合、ドライバーは結果セット全体を読み取ります。 サイズは、次の 2 つのスタイルで指定できます。

• バイト単位のサイズ (たとえば、 100、 150M、 300K、 400G)。
• 最大ヒープ メモリの割合 (たとえば、 10p、 15pct、 20percent)。

msiClientId

• 型: String
• 既定: null

(非推奨)(バージョン 7.2 以降)accessTokenまたはActiveDirectoryManagedIdentity認証モードを使用して接続を確立するためのActiveDirectoryMSIを取得するために使用されるマネージド ID (MSI) のクライアント ID。

multiSubnetFailover

• 型: Boolean [true | false]
• 既定: false

SQL Server可用性グループまたは SQL Server フェールオーバー クラスター インスタンスの可用性グループ リスナーに接続するには、常に multiSubnetFailover=true を指定します。 multiSubnetFailover=true は、アクティブなサーバーの検出と接続を高速化するようにドライバーを構成します。

設定可能な値は true および false です。

ディザスター リカバリーの詳細については、「高可用性、ディザスター リカバリーのための JDBC Driver のサポート」を参照してください。

multiSubnetFailover、getMultiSubnetFailover、setMultiSubnetFailover を使用して、接続プロパティにプログラムでアクセスできます。

packetSize

• 型: int [-1 | 0 | 512..32767]
• 既定: 8000

サーバーとの通信に使用されるネットワーク パケット サイズ (バイト単位)。 値 -1 は、サーバーの既定のパケット サイズが使用されることを示します。 値 0 は、最大値 32767 が使用されることを示します。 このプロパティを許容範囲外の値に設定すると、例外が発生します。

このプロパティの詳細については、SQLServerDataSource クラスの setPacketSize メソッドを参照してください。

パスワード

• 型: String [<=128 char]
• 既定: null

SQL ユーザーとパスワードを使用して接続する場合のデータベース パスワード。

プリンシパル名とパスワードを使用した Kerberos 接続の場合は、このプロパティを Kerberos プリンシパル のパスワードに設定します。

(バージョン 10.2 以降)authentication=ActiveDirectoryServicePrincipal、password プロパティは、Active Directory プリンシパルに使用するパスワードを識別します。

portNumber、port

• 型: int [0..65535]
• 既定: 1433

サーバーがリッスンしているポート。 接続文字列でポート番号を指定した場合、SQLbrowser への要求は行われません。 ポートと instanceNameの両方を指定すると、指定したポートに接続されます。 ただし、instanceName が確認され、それがポートと一致しない場合はエラーがスローされます。

prepareMethod

• 型: String [prepexec | prepare | scopeTempTablesToConnection | none]
• 既定: prepexec

(バージョン 11.2.0 以降)準備されたステートメントでドライバーが使用する基になる準備メソッドを指定します。

prepare メソッドとしてprepareを使用するには、sp_prepareに設定します。 この値に prepareMethod を設定することで、データベースに個別の初期トリップが発生し、実行計画でデータベースにおいて考慮すべき初期値なしでステートメントが準備されます。 prepare メソッドとしてprepexecを使用するには、sp_prepexecに設定します。 このメソッドは、準備アクションと最初の実行を組み合わせて、ラウンド トリップを減らします。 また、実行プランでデータベースが考慮できる初期パラメーター値もデータベースに提供されます。

(バージョン 13.4.0 以降)準備されたステートメントで作成された一時テーブルを、サーバー側の準備されたハンドルではなくリテラル パラメーターの置換を使用して接続にスコープを設定するには、 scopeTempTablesToConnection に設定します。 sql バッチ実行でリテラル パラメーターの置換を適用し、サーバー側の準備されたステートメント ハンドル (nonesp_prepexec / ) をバイパスするようにsp_prepareに設定します。

scopeTempTablesToConnectionとnoneに関する制限事項と免責事項:

これらの prepareMethod オプションは、一般的なパフォーマンスの使用ではなく、互換性と移行のシナリオを目的としています。

• サーバー側で準備されたステートメントはありません。SQL は常にバッチとして実行されます。
• プランを効果的に再利用するには、 FORCED_PARAMETERIZATION が必要です。
• パラメーターは、バインドされた型ではなくリテラルとしてインライン化されます。
• 数値の正確性とスケールは、サーバー側のパラメータバインディングとは異なる可能性があります。
• 日付と時刻の値は、ドライバーによって文字列として書式設定されます。
• 文字列パラメーターが大きいと、SQL のテキスト サイズとメモリ使用量が増加します。
• BLOB パラメーターと CLOB パラメーターは、メモリ使用量が多い、またはメモリ不足の状態を引き起こす可能性があります。
• SQL Serverは、SQL 解析時にパラメーター のデータ型を推論します。
• クエリ プランは、リテラル値の違いによって異なる場合があります。
• エラーは、バインド時ではなく実行時に検出されます。
• 実行される SQL にはリテラル値が含まれており、サーバー トレースとログに表示されます。

queryTimeout

• 型: int
• 既定: -1

クエリでタイムアウトが発生するまでに待機する秒数。 既定値は -1 です。これはタイムアウトが無期限であることを意味します。 この値を 0 に設定した場合も、無期限の待機を意味します。

quotedIdentifier

• 型: String [ON | OFF]
• 既定: ON

(バージョン 13.2 以降)このオプションを OFF に設定すると、ドライバーは、接続を確立するときにデータベース セッション変数 QUOTED_IDENTIFIER を OFF に設定します。 データベースは、二重引用符を文字リテラルの文字列区切り記号として扱います。識別子を二重引用符で囲むことはありません。

詳しくは、「SET QUOTED_IDENTIFIER」をご覧ください。

レルム

• 型: String
• 既定: null

(バージョン 9.4+) Kerberos 認証の領域。 この値を設定して、サーバーの領域からドライバーによって自動検出される、Kerberos 認証領域をオーバーライドします。

レプリケーション

• 型: Boolean [true | false]
• 既定: false

(バージョン 9.4+) 接続をレプリケーションに使用するかどうかがこの設定によりサーバーに通知されます。 有効にすると、NOT FOR REPLICATION オプションを使ったトリガーは、接続で起動されません。

レスポンスバッファリング

• 型: String [full | adaptive]
• 既定: adaptive

このプロパティを adaptive に設定すると、ドライバーは必要に応じて最小限のデータ量をバッファーします。 既定のモードは adaptiveです。

このプロパティを full に設定すると、ドライバーはステートメントの実行時にサーバーから結果セット全体を読み取ります。

Selectmethod

• 型: String [direct | cursor]
• 既定: direct

このプロパティを cursor に設定すると、ドライバーは、 TYPE_FORWARD_ONLY と CONCUR_READ_ONLY カーソルの接続で作成するクエリごとにデータベース カーソルを作成します。 通常、このプロパティは、アプリケーションがクライアント メモリに完全には収まらない大きな結果セットを生成する場合にのみ必要です。 このプロパティを cursor に設定すると、ドライバーはクライアント メモリ内の限られた数の結果セット行のみを保持します。

既定では、ドライバーはすべての結果セット行をクライアント メモリに保持します。 この既定の動作は、アプリケーションがすべての行を処理するときに最速のパフォーマンスを提供します。

sendStringParametersAsUnicode

• 型: Boolean [true | false]
• 既定: true

sendStringParametersAsUnicode プロパティを true に設定すると、ドライバーは文字列パラメーターを Unicode 形式でサーバーに送信します。

sendStringParametersAsUnicode プロパティを false に設定すると、ドライバーは Unicode ではなく ASCII や MBCS などの Unicode 以外の形式で文字列パラメーターをサーバーに送信します。

sendStringParametersAsUnicode プロパティの既定値は true です。

CHAR、VARCHAR、LONGVARCHAR JDBC データ型で最適なパフォーマンスを得るために、アプリケーションでは、sendStringParametersAsUnicode プロパティをfalseに設定し、setStringおよび setCharacterStream クラスのsetClob、、およびの非各国文字メソッドを使用する必要があります。

アプリケーションで sendStringParametersAsUnicode プロパティを false に設定し、非国内文字メソッドを使用してサーバー側の Unicode データ型 ( nchar、 nvarchar、 ntextなど) にアクセスする場合、データベース照合順序で非国内文字メソッドによって渡される String パラメーターの文字がサポートされていない場合、データが失われる可能性があります。

アプリケーションでは、setNString、setNCharacterStream、setNClob JDBC データ型に対して、SQLServerPreparedStatement クラスおよび SQLServerCallableStatement クラスクラスのNCHAR、NVARCHAR、およびLONGNVARCHARの各国語の文字メソッドを使用する必要があります。

この値を変更すると、データベースからの結果の並べ替えに影響する可能性があります。 並べ替えの違いは、Unicode と Unicode 以外の文字の並べ替え規則が異なるためです。

sendTemporalDataTypesAsStringForBulkCopy

• 型: Boolean [true | false]
• 既定: true

(バージョン 8.4 以降)この接続プロパティを false に設定すると、ドライバーはDATEとして送信するのではなく、DATETIME、DATETIME2、DATETIMEOFFSET、SMALLDATETIME、TIME、およびStringデータ型をそれぞれの型として送信します。

この接続プロパティを false に設定すると、ドライバーは各テンポラル データ型の既定の文字列リテラル形式を受け入れます。次に例を示します。

• DATE: YYYY-MM-DD
• DATETIME: 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:ss
• TIME: 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 されており、今後のリリースで変更される可能性があります。

Microsoft JDBC Driver for SQL Server がサーバーに送信する前に java.sql.Time 値をどのように構成するかについての詳細は、java.sql.Time 値の送信方法の構成を参照してください。

サーバー証明書, サーバー

• 型: String
• 既定: null

(バージョン 11.2.0 以降) サーバー証明書ファイルへのパス。 encryptを strict に設定すると、ドライバーはこの証明書を検証に使用します。 ドライバーは、PEM ファイル形式を使用する証明書ファイルをサポートしています。

serverName、server

• 型: String
• 既定: null

SQL Server が実行されているコンピューターまたは Azure SQL データベース。

可用性グループの仮想ネットワーク名を指定することもできます。

ディザスター リカバリーの詳細については、「高可用性、ディザスター リカバリーのための JDBC Driver のサポート」を参照してください。

serverNameAsACE

• 型: Boolean [true | false]
• 既定: false

(バージョン 6.0 以降)ドライバーが Unicode サーバー名を接続の ASCII 互換エンコード (Punycode) に変換する必要があることを示す true に設定します。 この設定が false場合、ドライバーは接続に指定されたサーバー名を使用します。

国際化機能の詳細については、「JDBC ドライバーの国際化機能」を参照してください。

serverPreparedStatementDiscardThreshold

• 型: int
• 既定: 10

(バージョン 6.2 以降)このプロパティを使用して、ドライバーがサーバー上の未処理のハンドルをクリーンアップする前に、接続ごとに未処理の準備されたステートメント破棄アクション (sp_unprepare) の数を制御します。

このプロパティを <= 1 に設定すると、準備されたステートメントが閉じた場合、ドライバーは直ちに準備解除アクションを実行します。 プロパティを > 1 に設定すると、ドライバーはこれらの呼び出しをまとめて処理し、sp_unprepare の呼び出し回数を減らしてオーバーヘッドを回避します。

serverSpn

• 型: String
• 既定: null

(バージョン 4.2 以降)この省略可能なプロパティを使用して、Java Kerberos 接続のサービス プリンシパル名 (SPN) を指定します。 authenticationSchemeと共に使用します。

SPN を指定するには、MSSQLSvc/fqdn:port@REALM という形式を使用します。fqdn は完全修飾ドメイン名、ポートはポート番号、REALM は大文字でSQL Serverの Kerberos 領域です。

Java Kerberos で を使用する方法の詳細については、「 Kerberos 統合認証を使用して SQL Serverを参照してください。

socketFactoryClass

• 型: String
• 既定: null

(バージョン 8.4 以降)既定のソケット ファクトリの代わりに使用するカスタム ソケット ファクトリのクラス名を指定します。

socketTimeout

• 型: int
• 既定: 0

ソケットの読み取りまたは受け入れでタイムアウトが発生するまでの待機時間 (ミリ秒)。 既定値は 0 です。これはタイムアウトが無期限であることを意味します。

statementPoolingCacheSize

• 型: 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」を参照してください。

transparentNetworkIPResolution

• 型: 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 実装の完全修飾クラス名。

trustManagerConstructorArg

• 型: 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 です。 serverNameに渡された値が、TLS/SSL 接続を成功させるために、サーバー証明書のサブジェクト代替名の共通名 (CN) または DNS 名と正確に一致していることを確認します。

暗号化のサポートの詳細については、「暗号化のサポートについて」を参照してください。

トラスト ストア

• 型: String
• 既定: null

証明書 trustStore ファイルへのパス (ファイル名を含む)。 trustStore ファイルには、クライアントが信頼する証明書の一覧が含まれています。

このプロパティを指定しない場合、または null に設定すると、ドライバーはトラスト マネージャー ファクトリの参照規則を使用して、使用する証明書ストアを決定します。

既定の SunX509 TrustManagerFactory は、次の検索順序で信頼できるマテリアルを検索しようとします。

1. javax.net.ssl.trustStore JVM システム・プロパティーで指定されたファイル。
2. <java-home>/lib/security/jssecacerts ファイル。
3. <java-home>/lib/security/cacerts ファイル。

SUNX509 TrustManager Interface の詳細については、Sun Microsystems の Web サイトにある SUNX509 TrustManager Interface に関するドキュメントを参照してください。

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 システム プロパティに格納しないようにする場合に必要です。

信頼ストアタイプ

• 型: String
• 既定: JKS

FIPS モードで使用する信頼ストアの種類を指定するには、このプロパティを設定します。

使用可能な値は、 PKCS12 または FIPS プロバイダーによって定義された型のいずれかです。

useBulkCopyForBatchInsert

• 型: Boolean [true | false]
• 既定: false

(バージョン 9.2 以降)この接続プロパティを有効にすると、ドライバーは、 java.sql.PreparedStatementを使用するバッチ挿入操作に一括コピー API を透過的に使用します。 この機能により、パフォーマンスが向上します。

この機能は、既定では無効化されています。 このプロパティを有効にするには、 true に設定します。

このプロパティの使用方法の詳細については、「 バッチ挿入操作に一括コピー 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 以降) サーバーからパラメーター メタデータのクエリを実行する別の方法が提供されます。 このプロパティを true に設定して、ドライバーがパラメーター メタデータのクエリを実行するときに SET FMTONLY ロジックを使用するように指定します。 この機能は既定ではオフになっています。SET FMTONLY は非推奨としてマークされているため、このプロパティを使用することは推奨されていません。 useFmtOnly は、 sp_describe_undeclared_parametersの既知の問題と制限事項の回避策としてのみ使用できます。

現在、この機能では、単一の SELECT/INSERT/UPDATE/DELETE クエリのみがサポートされています。 サポートされていないクエリまたは複数のクエリでこの機能を使用しようとすると、ドライバーはクエリの解析を試みますが、ほとんどの場合、例外が発生します。

このプロパティの詳細については、「useFmtOnlyを使用した ParameterMetaData の取得」を参照してください。

ユーザー名、ユーザー

• 型: String [<=128 char]
• 既定: null

SQLユーザーとパスワードを使用して接続する場合は、データベースユーザーとして接続します。

プリンシパル名とパスワードを使用した Kerberos 接続の場合は、このプロパティを Kerberos プリンシパル名に設定します。

(バージョン 10.2 以降)authentication=ActiveDirectoryServicePrincipalの場合、userName プロパティは有効なMicrosoft Entraセキュリティで保護されたクライアント ID を指定します。

vectorTypeSupport

• 型: String [v2 | v1 | off]
• 既定: v1

(バージョン 13.2 以降) off に設定すると、サーバーが JSON 形式の文字列データとしてベクター型を送信し、 v1 サーバーがベクター データとして FLOAT32 のベクター型を送信するように指定します。 既定値は v1 です。

(バージョン 13.4 以降) v2 に設定すると、 FLOAT32 ベクトルと FLOAT16 ベクターの両方でネイティブ ベクター型のサポートが有効になります。 FLOAT16 ベクトルは、ワイヤ上で IEEE-754 半精度シリアル化を使用し、Javaの Float[] 配列として公開されます。

詳細については、 JDBC ドライバーでのベクター・データ・タイプの使用を参照してください。

workstationID

• 型: String [<=128 char]
• 既定: <empty string>

ワークステーション ID。 この ID を使用して、さまざまなプロファイルおよびログ ツールで特定のワークステーションを識別します。

値を指定しない場合、既定値は <empty string> になります。

xopenStates

• 型: Boolean [true | false]
• 既定: false

ドライバーが例外で XOPEN 準拠の状態コードを返すように指定するには、 true に設定します。

既定では、SQL 99 の状態コードを返します。

関連するコンテンツ

• JDBC ドライバーによる SQL Server への接続
• FIPS モード