接続プロパティの設定
接続文字列のプロパティは、さまざまな方法で指定できます。
DriverManager クラスを使用して接続するときは、接続 URL における「名前=値」形式のプロパティとして指定できます。
DriverManager クラスの Connect メソッドの Properties パラメーターにおける「名前=値」形式のプロパティとして指定できます。
ドライバーのデータ ソースの適切な setter メソッドの値として指定できます。次に例を示します。
datasource.setServerName(value) datasource.setDatabaseName(value)
プロパティ名の大文字と小文字は区別されず、重複したプロパティ名は次の順序で解決されます。
- API 引数 (user、password など)
- プロパティ コレクション
- 接続文字列の最後のインスタンス
プロパティ名には不明な値を使用することもできます。JDBC ドライバーはこのような値の大文字と小文字の区別について検証しません。
シノニムを使用できます。これは、重複したプロパティ名と同じ順序で解決されます。
次の表は、JDBC ドライバーで現在使用できるすべての接続文字列プロパティを示しています。
| プロパティ | 種類 | 既定値 | 説明 |
|---|---|---|---|
applicationName |
String [128 文字以下] |
null |
アプリケーション名、または "Microsoft SQL Server JDBC Driver" (名前が指定されていない場合) です。個別のアプリケーションを識別するために、さまざまな SQL Server プロファイリング ツールおよびロギング ツールで使用されます。 |
databaseName、database |
String [128 文字以下] |
null |
接続するデータベース名です。指定しない場合は、既定のデータベースへの接続が確立されます。 |
disableStatementPooling |
boolean ["true"|"false"] |
true |
現在は、値 "true" のみがサポートされています。"false" に設定した場合は、例外が発生します。 |
encrypt |
boolean ["true"|"false"] |
false |
SQL Server で、サーバーに証明書がインストールされている場合に、クライアントとサーバーの間で送信されるすべてのデータに対して SSL (Secure Sockets Layer) 暗号化が使用されるようにするには、"true" に設定します。既定値は false です。 |
failoverPartner |
String |
null |
データベース ミラーリング構成で使用されるフェールオーバー サーバーの名前です。このプロパティは、プリンシパル サーバーへの初期接続に失敗した場合に使用されます。初期接続が行われた後は、このプロパティは無視されます。databaseName プロパティと組み合わせて使用する必要があります。 注意 接続文字列の中で failoverPartner プロパティを指定するときに、フェールオーバー パートナー インスタンスのサーバー インスタンスのポート番号を指定することはできません。ただし、プリンシパル サーバー インスタンスの serverName、instanceName、portNumber の各プロパティ、およびフェールオーバー パートナー インスタンスの failoverPartner プロパティを同じ接続文字列の中で指定することはできます。 |
hostNameInCertificate |
String |
null |
SQL Server の SSL 証明書の検証に使用されるホスト名です。 hostNameInCertificate プロパティが指定されていないか null に設定されている場合、Microsoft SQL Server JDBC Driver は、接続 URL の serverName プロパティ値をホスト名として使用して SQL Server の SSL 証明書を検証します。 注意 このプロパティは、encrypt プロパティおよび trustServerCertificate プロパティと組み合わせて使用されます。このプロパティが証明書の検証に影響するのは、encrypt プロパティが "true" に設定されていて、trustServerCertificate プロパティが "false" に設定されている場合だけです。 |
instanceName |
String [128 文字以下] |
null |
接続する SQL Server のインスタンス名です。指定しない場合は、既定のインスタンスへの接続が確立されます。instanceName と port の両方を指定する場合については、port の注を参照してください。 |
integratedSecurity |
boolean ["true"|"false"] |
false |
アプリケーションのユーザーを認証するために SQL Server によって Windows 資格情報が使用されることを示す場合は、"true" に設定します。"true" の場合、JDBC ドライバーは、コンピューターまたはネットワーク ログオン時に提供された資格情報を見つけるために、ローカル コンピューターの資格情報のキャッシュを検索します。"false" の場合は、ユーザー名とパスワードを指定する必要があります。 注意 この接続プロパティは、Microsoft Windows オペレーティング システムのみでサポートされています。 |
lastUpdateCount |
boolean ["true"|"false"] |
true |
値が "true" の場合、サーバーに渡された SQL ステートメントから最終的な更新数のみを返します。また、SELECT、INSERT、または DELETE ステートメントのいずれか 1 つで使用して、サーバーのトリガーにより追加された更新数を無視することができます。このプロパティを "false" に設定すると、サーバーのトリガーにより返される更新数を含む、すべての更新数が返されます。 注意 このプロパティが適用されるのは、executeUpdate メソッドと一緒に使用された場合だけです。その他のすべての execute メソッドは、すべての結果および更新数を返します。 このプロパティは、サーバーのトリガーにより返される更新数にのみ影響します。トリガーの実行の一部として得られる結果セットまたはエラーには影響しません。 |
lockTimeout |
int |
-1 |
データベースがロック タイムアウトを通知するまでに待機する時間 (ミリ秒) です。既定では、無期限に待機します。指定されている場合、この値は接続上のすべてのステートメントに対する既定値になります。特定のステートメントに対するタイムアウトは、 |
loginTimeout |
int [0..65535] |
15 |
ドライバーがタイムアウトを通知して接続を失敗させるまでに待機する時間 (秒) です。0 の値は、タイムアウトが既定のシステム タイムアウトであることを示します。既定のシステム タイムアウトは、既定では 15 秒に指定されています。0 以外の値は、ドライバーがタイムアウトを通知して接続を失敗させるまでに待機する時間 (秒) を示します。 |
packetSize |
int [-1| 0 | 512..32767] |
8000 |
SQL Server との通信に使用されるネットワーク パケット サイズです (バイトで指定します)。値が -1 の場合は、サーバーの既定のパケット サイズが使用されます。値が 0 の場合は、最大値 (32767) が使用されます。このプロパティが許容範囲外の値に設定されている場合は、例外が発生します。 注意 暗号化を有効 (encrypt=true) にしている場合に packetSize プロパティを使用することはお勧めしません。使用すると、接続エラーが発生する可能性があります。詳細については、SQLServerDataSource クラスの setPacketSize メソッドのトピックを参照してください。 |
password |
String [128 文字以下] |
null |
データベース パスワードです。 |
portNumber、port |
int [0..65535] |
1433 |
SQL Server が待機しているポートです。ポート番号が接続文字列に指定されている場合は、sqlbrowser に対する要求は作成されません。port と instanceName の両方が指定されている場合は、指定されたポートへの接続が確立されます。ただし、instanceName の検証が行われ、ポートと一致しない場合はエラーがスローされます。 注意 sqlbrowser を使用する場合よりもセキュリティが向上するため、常にポート番号を指定することをお勧めします。 |
responseBuffering |
String ["full"|"adaptive"] |
adaptive |
このプロパティを "adaptive" に設定すると、必要に応じて最小限のデータがバッファリングされます。既定のモードは "adaptive" です。 このプロパティが "full" に設定されている場合、ステートメントの実行時に結果セット全体がサーバーから読み取られます。 注意 JDBC ドライバーを Version 1.2 からアップグレードすると、既定のバッファリング動作が "adaptive" になります。アプリケーションで "responseBuffering" プロパティが設定されていない場合に Version 1.2 の既定の動作を維持するには、接続プロパティで、または SQLServerStatement オブジェクトの setResponseBuffering メソッドを使用して、responseBufferring プロパティを "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 プロパティがチェックされます。JDBC 4.0 の新しい National Character メソッドである、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 を使用する必要がある点に注意してください。 |
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 値としてサーバーに送信されます。 また、sendTimeAsDatetime は SQLServerDataSource.setSendTimeAsDatetime を使用してプログラムから変更することもできます。 今後のリリースでは、このプロパティの既定値が変更される可能性があります。 java.sql.Time 値をサーバーに送信する前に、SQL Server JDBC Driver でその値を構成する方法の詳細については、「java.sql.Time の値をサーバーに送信する方法の構成」を参照してください。 |
serverName、server |
String |
NULL |
SQL Server を実行しているコンピューターです。 |
user、userName |
String [128 文字以下] |
null |
データベース ユーザーです。 |
trustServerCertificate |
boolean ["true"|"false"] |
false |
Microsoft SQL Server JDBC Driver が SQL Server の SSL 証明書を検証しないようにするには "true" に設定します。 "true" の場合、通信レイヤーが SSL で暗号化されていれば SQL Server の SSL 証明書が自動的に信頼されます。 "false" の場合は、Microsoft SQL Server JDBC Driver がサーバーの SSL 証明書を検証します。サーバー証明書の検証が失敗した場合は、エラーが発生して接続が終了します。既定値は "false" です。 注意 このプロパティは、encrypt プロパティと組み合わせて使用されます。このプロパティがサーバーの SSL 証明書の検証に影響するのは、encrypt プロパティが "true" に設定されている場合だけです。 |
trustStore |
String |
null |
証明書の trustStore ファイルへのパス (ファイル名を含む) です。trustStore ファイルには、クライアントが信頼する証明書の一覧が含まれています。 このプロパティが指定されていないか null に設定されている場合、ドライバーは、信頼マネージャー ファクトリの検索ルールに従って、使用する証明書ストアを決定します。 既定の SunX509 TrustManagerFactory では、次の順序で信頼済みマテリアルの検索が行われます。
詳細については、Sun Microsystems の Web サイトで SunX509 TrustManager Interface についてのドキュメントを参照してください。 注意 このプロパティが証明書の trustStore の検索に影響するのは、encrypt プロパティが "true" に設定されていて、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 の検索に影響するのは、encrypt プロパティが "true" に設定されていて、trustServerCertificate プロパティが "false" に設定されている場合だけです。 |
workstationID |
String [128 文字以下] |
<空の文字列> |
ワークステーション ID です。個別のワークステーションを識別するために、さまざまな SQL Server プロファイリング ツールおよびロギング ツールで使用されます。何も指定しなかった場合は、<空の文字列> が使用されます。 |
xopenStates |
boolean ["true"|"false"] |
false |
"true" に設定すると、ドライバーが XOPEN 互換の状態コードを例外で返します。既定では、SQL 99 の状態コードを返します。 |
注意
SQL Server JDBC Driver は、ANSI_DEFAULTS および IMPLICIT_TRANSACTIONS 以外の接続プロパティのサーバー既定値を受け取ります。SQL Server JDBC Driver によって、ANSI_DEFAULTS は ON に、IMPLICIT_TRANSACTIONS は OFF に自動的に設定されます。