構成可能な再試行ロジック (JDBC)

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

構成可能な再試行ロジック (CRL) は、制御するタイミング パラメーターを使用して、選択したエラー番号に基づいて、失敗したステートメントまたは最初の接続試行SQL Server自動的に再試行するルール ベースのメカニズムです。 CRL は、SQL Server用 Microsoft JDBC Driver 12.10 で導入されました。

CRL は、 アイドル状態の接続の回復性と connectRetryCount / connectRetryInterval プロパティとは別です。 アイドル状態の回復性は、中断された接続を透過的に回復し、 connectRetryCount は、一時的なエラーの組み込み一覧の固定スケジュールで初期認証を再試行します。 CRL を使用すると、再試行可能なエラー、回数、試行の間に待機する時間を決定できます。 3 つのメカニズムすべてを一緒に使用できます。

CRL が再試行する項目

CRL は、それぞれ独自の接続プロパティによって制御される 2 つの異なるシナリオを処理します。

ステートメントの場合、ドライバーは失敗したコマンドのみを再試行します。 ドライバーは現在のトランザクション状態をリセットしないため、デッドロックの犠牲になった場合 (1205) やロック タイムアウト (1222) など、セッションを引き続き使用できる状態のままにするエラーを前提にルールを設計してください。

接続の場合、CRL はドライバーの一時的な接続エラーの組み込みリストを拡張または置き換えます。 プレフィックスセマンティクスの+を参照してください。

CRL を有効にする

CRL には、次の 2 つのレイヤーがあります。

1. 接続再試行レイヤーは既定でオンになっています。 connectRetryCount > 0 限り (既定値は 1)、ドライバーは 組み込みの一時的な接続エラー一覧を再試行します。
2. カスタマイズ レイヤー (独自の retryExec と retryConn ルール) は、既定ではオフになっています。 両方のプロパティは、設定しない限り空の文字列です。 JDBC URL、 Properties オブジェクト、または SQLServerDataSourceを使用して設定できます。 ドライバーは、3 つのフォームすべてで省略可能な {...} ラッパーを削除します。

この記事のJavaスニペットでは、簡潔にするためにインポートとクラス ラッパーを省略します。

JDBC URL内

JDBC URL では区切り記号として{...}が使用されるため、各ルール (またはルールの一覧全体) を中かっこ (;) でラップする必要があります。

jdbc:sqlserver://server;databaseName=db;retryExec={1205,1222:3,2*2:select,update}
jdbc:sqlserver://server;databaseName=db;retryConn={+<customErrorNumber>}

Properties オブジェクトを使用する

Properties props = new Properties();
props.setProperty("user", "...");
props.setProperty("password", "...");
props.setProperty("retryExec", "1205,1222:3,2*2:select,update");
props.setProperty("retryConn", "+<customErrorNumber>");
Connection c = DriverManager.getConnection("jdbc:sqlserver://server;databaseName=db", props);

SQLServerDataSource あり

ISQLServerDataSource インターフェイスには、同じセッターが存在します。

SQLServerDataSource ds = new SQLServerDataSource();
ds.setServerName("server");
ds.setDatabaseName("db");
ds.setRetryExec("1205,1222:3,2*2:select,update");
ds.setRetryConn("+<customErrorNumber>");

ルールの構文

1 つのルールには、コロンで区切られたセクションが最大 3 つ含まれています。

<errorNumbers> : <retryTimings> : <queryFilter>

同じプロパティで複数のルールを使用するには、 ; で区切り、JDBC URL に配置するときに各ルールを {...} でラップします。

タイミング パラメーター

タイミング retryCount, initialRetryTime <op> retryChange を持つステートメント ルールの場合:

• retryCount: 最初の障害後にドライバーが行った追加試行回数。 0値を指定すると、再試行が無効になります。 負の値は無効です。
• initialRetryTime: 最初の再試行の前に待機する秒数。 既定値は 0 です。
• <op>: 演算子。 + または *できます。 既定値は + です。
• retryChange: 後続の待機時間を計算するために適用される量。 既定値は 2 です。 オペランドが * され、規則から retryChange を省略すると、ドライバーは retryChange = initialRetryTimeを設定します。

ドライバーは、解析時に試行の待機時間 i (0 ベース) を計算します。

タイミング文字列の例:

retryTimings セクションには、最大 1 つのコンマを含めることができます。 複数のコンマで R_invalidParameterNumber が発生します。

ステートメント再試行規則 (retryExec)

ステートメント ルールは、失敗したステートメントの実行を再試行します。 ステートメントが SQLServerException をスローした場合、ドライバは次の処理を行います:

1. 解析されたステートメント ルール セットで失敗したエラー番号を検索します。
2. ルールが存在し、現在の試行回数が retryCount未満の場合は、必要に応じて、最後に実行された SQL をルールの queryFilterと照合します。
3. すべてが一致する場合、ドライバーは waitTimes[retryAttempt] 秒間待機し ( queryTimeoutの場合は、「 queryTimeout と connectRetryCount との対話」を参照)、ステートメントを再実行します。
4. 一致するルールがない場合、ドライバーは例外を再度スローします。

書式 (ステートメント)

{errorNumber(s):retryCount[,initialRetryTime[<op>retryChange]][:queryFilter]}

ステートメント ルールには、timings セクションを含める 必要があります 。 retryCount は必須です。 エラー番号のみを含むルールは 接続 ルールとして解釈されるため、ステートメントでは常に少なくとも retryCountを指定します。

例 (ステートメント)

いくつかのエラー番号 (たとえば、 1205,1222) の一覧表示は省略形です。 ドライバーは、エラーごとに 1 つのエントリにルールを展開し、すべて同じタイミングとクエリ フィルターを共有します。

接続再試行規則 (retryConn)

接続規則は、既存の接続再試行ループで機能します。 このループは、connectRetryCount > 0 (既定値は 1) の場合にのみアクティブになります。 このループはすでに、組み込みの一時的な接続エラーの一覧に対して connectRetryInterval 秒間隔で再試行を行い、最大 connectRetryCount 回の追加試行を行います。全体は loginTimeout によって制限されています。

接続規則では、エラー番号セクションのみが提供されます。 タイミングやクエリ フィルターはありません。

{[+]errorNumber(s)}

• + を指定しない場合、設定されたルールは組み込みの一時エラー リストを置き換えます。 一覧表示したエラーのみが再試行されます。
• + ({+4060} など) を使用すると、構成済みの規則が組み込みリストに追加されます。 エラーとドライバーの既定値の両方が再試行されます。

置換または追加モードは、 retryConn 値全体に対してグローバルです。 その値のルールで +が省略されている場合、ドライバーは、その値のすべてのルールの置換モードに切り替わります。 たとえば、 retryConn={+4060};{40143} は組み込みリストに 4060 と 40143 を追加しません。 40143規則では+が省略されているため、組み込みリストは削除され、再試行されるのは 4060 と 40143 だけです。 両方を追加するには、 retryConn={+4060};{+40143} (または retryConn={+4060,40143}) を記述します。

接続ループでは、間隔調整と制限のために引き続き connectRetryInterval と connectRetryCount が使われます。 CRL ルールは、再試行の対象となる一連のエラーを拡張または置き換えます。

例（接続）

組み込みの一時的な接続エラーの一覧

接続再試行ループは、 connectRetryCount > 0限り、CRL 構成なしで、既に次のエラーを再試行します。 retryConn ルールに + とともにこれらのエラーのいずれかを記載しても、効果はありません (すでにカバーされています)。 この一覧にないエラーを追加する必要がある場合や、retryConnなしの置換フォームを使用してリストを完全に削除する必要がある場合は、+ルールを使用します。

ドライバーの正規リストは、TransientError 内の SQLServerError.java 列挙型です。 エラー メッセージ テキストはAzure SQL の一時的な接続エラーから取得されます。 接続再試行ループは最初の接続中にのみ発生するため、ステートメント レベルのエラー (デッドロックの対象 1205 やロック要求タイムアウト 1222 など) はこの一覧に含まれません。 これらのエラーを再試行するには、 retryExec 規則を使用します。

プロパティ ファイルからルールを読み込む

接続に retryExec または retryConn を設定しない場合、CRL はクラスパスのドライバー JAR の横 mssql-jdbc.properties という名前のファイルを探します。 このファイルでは、基本的な key=value 解析が使用されます。 retryExec=またはretryConn=で始まる行が取得されます。 値は、この記事で説明するのと同じ構文を使用し、複数の規則 ; 区切ります。

先頭に空白を付けず、正確なキー名 (retryExec と retryConn) を使用します。 ファイルは、完全なJavaプロパティ ファイルとして解析されません。 ドライバーは、各行でリテラル startsWith チェックを行います。そのため、次のようになります。

• #またはその他のretryExec/retryConn以外のプレフィックスで始まる行は無視されます。
• キーが retryExec または retryConn のみで始まる行 ( retryExec2=... など) は、一致するプロパティとして扱われ、解析エラーが発生する可能性があります。 カスタムバリアントは導入しないでください。

mssql-jdbc.properties例:

retryExec=1205:3,5+5;1222:2,2
retryConn=+4060,40143

ファイルが見つからない場合、CRL はFINE ロガーの下にcom.microsoft.sqlserver.jdbc.ConfigurableRetryLogic メッセージを記録し、規則なしで続行します。 検索に使用されるファイル パスは、そのログ メッセージに含まれます。

接続文字列の値が優先されます。 接続 retryExec または retryConn が空でない場合、ドライバーはそのプロパティのファイルを参照しません。

ルールの更新動作

CRL では、JVM 全体のルール セットが 1 つ保持されます。 構築後、ドライバーはルールを遅延読み込みで更新します:

• ドライバーは、ステートメントの実行中と接続の再試行中に更新の機会を評価します。
• 更新は実際には、前回の読み取りから 30 秒が経過した後にのみ行われます。
• ルールが最初に mssql-jdbc.propertiesから取得された場合、ドライバーは、ファイルの最終変更タイムスタンプを、前回の読み取り時に記録したタイムスタンプと比較します。 ファイルが変更されると、ドライバーによって再解析されます。
• 規則が最初に接続文字列から取得された場合、ドライバーは、以前に格納された接続文字列の値を再び実行します。

この動作は、 mssql-jdbc.properties に対する編集が、アプリケーションを再起動せずに約 30 秒以内に自動的に取得されることを意味します。

queryTimeout と connectRetryCount との対話

ステートメントの再試行と queryTimeout

ステートメント ルールが発生すると、ドライバーは次の待機時間を接続レベルの queryTimeout 値と比較します。

• queryTimeout >= 0 andtimeToWait > queryTimeout場合、ドライバーは再試行するのではなく、R_InvalidRetryIntervalを発生させます。 ドライバーは元のエラーを再スローしません。 構成エラーが発生します。
• queryTimeout接続プロパティの既定値は -1 であるため、既定では比較はスキップされ、待機は許可されます。
• queryTimeout=0が true であるため、設定してもこのチェックは無効0 >= 0。 いずれの timeToWait > 0 も R_InvalidRetryInterval を発生させます。

queryTimeoutを正の値に設定する場合は、initialRetryTime + (retryCount - 1) * retryChange (加法) またはinitialRetryTime * retryChange^(retryCount-1) (乗法) の値をその下に置きます。

接続の再試行と connectRetryCount と loginTimeout

retryConn 自体では、認証の再試行は有効になりません。 既存のプロパティは引き続き有効です:

• connectRetryCount (既定値は 1、範囲は 0 ~ 255) は、追加の認証試行回数です。 認証の再試行を無効にするには、 0 に設定します。 connectRetryCount = 0 の場合、最初の失敗時にドライバが例外をスローするため、retryConn は有効となりません。
• connectRetryInterval (既定では 10 秒、範囲 1 から 60) は試行間の待機です。 最初の再試行はすぐに実行されます。
• loginTimeout は、全体的なバインドです。 次の間隔が loginTimeoutを超えて経過時間をプッシュする場合、ドライバーは早期にあきらめる。

詳細については、「 接続の回復性 (JDBC)」を参照してください。

Examples

書き込み時に発生するデッドロックとロックタイムアウトに対処する

jdbc:sqlserver://server;databaseName=db;retryExec={1205,1222:4,2*2:insert,update,delete,merge}

デッドロックが発生した場合 (1205) またはロック タイムアウト (1222) の場合、書き込みステートメントに対してのみ、2 秒、4 秒、8 秒、16 秒のバックオフ間隔で最大 4 回まで再試行します。

オンライン操作でスキーマ作成を再実行する

retryExec={2714:2,1+1};{3702:2,1+1}

エラー 2714 (object already exists) と 3702 (cannot drop database currently in use) をそれぞれ 2 回再試行し、1 秒と 2 秒の待機を行います。

一時的なエラーの一覧にカスタム エラーを追加する

retryConn={+<customErrorNumber>}

組み込みリストにまだ含まれていないカスタム エラー番号を追加します。 組み込みのAzure SQL一時的なエラー (40197、40501、40613、49918、49919、49920 など) を追加すると、ドライバーが既に再試行しているため、何も変更されません。

プロパティ ファイルを使用して CRL を構成する

ドライバー JAR の横に mssql-jdbc.properties を配置します。

retryExec=1205:3,5+5:select,update
retryConn=+<customErrorNumber>

接続に retryExec または retryConn を設定しないでください。 ドライバーは、ファイルから規則を読み取り、各変更後に再読み込みします (30 秒ごとに 1 回チェックされます)。

CRL のトラブルシューティング

FINE ロガーのcom.microsoft.sqlserver.jdbc.ConfigurableRetryLogic (またはより細かい) ログ記録を有効にして、ファイル読み取りの試行と解析の決定を確認します。

com.microsoft.sqlserver.jdbc.ConfigurableRetryLogic.level=FINE

一般的な構成エラー:

ルールが起動しない場合の確認事項:

1. 例外の SQLServerError.getErrorNumber() は、実際にはルール内の番号と一致します。 SQL Serverは、コンテキスト (デッドロックとロック タイムアウトなど) に応じて、いくつかのエラーを異なる数にラップできます。
2. queryFilterを含むステートメント ルールの場合、実行した SQL の最初の空白区切りトークン (小文字) がフィルター 一覧に含まれます。 コメントと WITH CTE は、最初のトークンを変更します。
3. retryCount 再試行は 追加 の試行です。 最初の実行はカウントされません。
4. 接続規則の場合、 connectRetryCount は 0 より大きく、 loginTimeout は少なくとも 1 つの connectRetryIntervalの余地を残します。
5. ルールは適切な形状をしている。 ステートメントルールにはタイミングセクションが必要です。 接続ルールは不可です。

関連するコンテンツ

• 接続の回復性 (JDBC)
• JDBC ドライバーのタイムアウト プロパティについて
• 接続プロパティを設定する
• JDBC ドライバーに関する問題の診断