Konfigurierbare Wiederholungslogik (JDBC)

JDBC-Treiber herunterladen

Konfigurierbare Wiederholungslogik (Retry Logic, CRL) ist ein regelbasierter Mechanismus, mit dem fehlgeschlagene Anweisungen oder anfängliche Verbindungsversuche basierend auf SQL Server von Ihnen ausgewählten Fehlernummern automatisch erneut überprüft werden. Dabei handelt es sich um zeitbasierte Parameter, die Sie steuern. CRL wurde in Microsoft JDBC-Treiber 12.10 für SQL Server eingeführt.

CRL unterscheidet sich von der Resilienz der Leerlaufverbindung und den connectRetryCount / connectRetryInterval Eigenschaften. Die Leerlaufresilienz stellt fehlerhafte Verbindungen transparent wieder her und connectRetryCount wiederholt die anfängliche Authentifizierung in einem festen Zeitplan für eine integrierte Liste von vorübergehenden Fehlern. Mit CRL können Sie festlegen , welche Fehler erneut versucht werden können, wie oft und wie lange zwischen den Versuchen gewartet werden soll. Sie können alle drei Mechanismen zusammen verwenden.

CRL-Wiederholungen

CRL behandelt zwei unterschiedliche Szenarien, die jeweils durch ihre eigene Verbindungseigenschaft gesteuert werden:

Bei Anweisungen ruft der Treiber nur den fehlerhaften Befehl erneut auf. Der Treiber setzt den Status der aktuellen Transaktion nicht zurück. Gestalten Sie Ihre Regeln daher so, dass sie auf Fehler ausgelegt sind, nach denen die Sitzung weiterhin verwendbar bleibt, z. B. Deadlockopfer (1205) oder Sperrtimeout (1222).

Bei Verbindungen ergänzt oder ersetzt CRL die integrierte Liste des Treibers mit vorübergehenden Verbindungsfehlern. Informationen zur Präfixsemantik finden Sie unter "Wiederholungsregeln für die + Verbindung".

Aktivieren von CRL

CRL hat zwei Ebenen:

1. Die Verbindungs-Wiederholungsschicht ist standardmäßig aktiviert: Solange connectRetryCount > 0 (der Standardwert 1) ist, wiederholt der Treiber die integrierte Fehlerliste für vorübergehende Verbindung.
2. Die Anpassungsebene (Eigene retryExec und retryConn Regeln) ist standardmäßig deaktiviert. Beide Eigenschaften sind leere Zeichenfolgen, es sei denn, Sie legen sie fest. Sie können sie über die JDBC-URL, ein Properties-Objekt oder ein SQLServerDataSource-Objekt setzen. Der Fahrer entfernt die optionalen {...} Wrapper in allen drei Formen.

Java Codeausschnitte in diesem Artikel lassen Importe und Klassenwrapper aus Platzgründen weg.

In der JDBC-URL

Jede Regel (oder die gesamte Regelliste) muss in geschweifte Klammern gesetzt werden ({...}), da die JDBC-URL ; als Trennzeichen verwendet:

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

Mit einem Properties-Objekt

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);

Mit SQLServerDataSource

Die gleichen Setter sind auf der ISQLServerDataSource Schnittstelle vorhanden:

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

Syntax von Regeln

Eine einzelne Regel weist bis zu drei durch Doppelpunkt getrennte Abschnitte auf:

<errorNumbers> : <retryTimings> : <queryFilter>

Wenn Sie mehrere Regeln in derselben Eigenschaft verwenden möchten, trennen Sie sie mit ; und umschließen Sie beim Einfügen in eine JDBC-URL jede Regel mit {...}.

Zeitparameter

Für eine Aussageregel mit Zeitangaben retryCount, initialRetryTime <op> retryChange:

• retryCount: Die Anzahl der zusätzlichen Versuche, die der Treiber nach dem ersten Fehler vornimmt. Ein Wert von 0 deaktiviert die Wiederholung. Negative Werte sind ungültig.
• initialRetryTime: Die Anzahl der Sekunden, die vor dem ersten Wiederholungsversuch gewartet werden soll. Der Standardwert ist 0.
• <op>: Der Operator, der + oder * sein kann. Der Standardwert ist +.
• retryChange: Der betrag, der zum Berechnen der nachfolgenden Wartezeiten angewendet wurde. Der Standardwert ist 2. Wenn der Operand * ist und retryChange in der Regel weggelassen wird, setzt der Treiber retryChange = initialRetryTime.

Der Treiber berechnet die Wartezeit für den Versuch i (nullbasiert) beim Parsen:

Beispiele für Zeitzeichenfolgen:

Ein retryTimings Abschnitt kann höchstens ein Komma enthalten. Mehr als ein Komma führt zu R_invalidParameterNumber.

Wiederholungsregeln für Anweisungen (retryExec)

Anweisungsregeln wiederholen die Ausführung fehlgeschlagener Anweisungen. Wenn eine Anweisung eine(n) SQLServerException auslöst, führt der Treiber Folgendes aus:

1. Sucht im Regelsatz der geparsten Anweisung nach der Fehlernummer, die den Fehler verursacht hat.
2. Wenn eine Regel vorhanden ist und die aktuelle Anzahl der Versuche kleiner als retryCountist, überprüft optional die zuletzt ausgeführte SQL-Datei anhand der Regel queryFilter.
3. Wenn alles übereinstimmt, wartet der Treiber waitTimes[retryAttempt] Sekunden (vorbehaltlich queryTimeout, siehe Wechselwirkung mit queryTimeout und connectRetryCount) und führt die Anweisung erneut aus.
4. Wenn keine Regel übereinstimmt, gibt der Treiber die Ausnahme zurück.

Format (Anweisungen)

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

Anweisungsregeln müssen einen Abschnitt für Zeitangaben enthalten. retryCount ist obligatorisch. Eine Regel, die nur eine Fehlernummer enthält, wird als Verbindungsregel interpretiert, sodass anweisungen immer mindestens retryCountangeben.

Beispiele (Aussagen)

Das Auflisten mehrerer Fehlernummern (zum Beispiel 1205,1222) ist eine Kurzschreibweise. Der Treiber erweitert die Regel auf einen Eintrag pro Fehler, wobei alle die gleiche Anzeigedauer und denselben Abfragefilter verwenden.

Regeln für erneute Verbindungsversuche (retryConn)

Verbindungsregeln arbeiten mit der bestehenden Schleife für Verbindungswiederholungen zusammen. Diese Schleife ist nur aktiv, wenn connectRetryCount > 0 (der Standardwert ist 1). Die Schleife versucht bei einer integrierten Liste vorübergehender Verbindungsfehler bereits automatisch erneut, im Abstand von connectRetryInterval Sekunden, bis zu connectRetryCount weitere Male, und ist durch loginTimeout begrenzt.

Eine Verbindungsregel enthält nur einen Abschnitt mit Fehlernummern. Es gibt keine Zeitangaben oder Abfragefilter:

{[+]errorNumber(s)}

• Ohne +, ersetzen die konfigurierten Regeln die integrierte vorübergehende Fehlerliste. Nur Fehler, die Sie auflisten, werden wiederholt.
• Mit + (z. B {+4060}. ) werden die konfigurierten Regeln der integrierten Liste hinzugefügt . Sowohl Ihre Fehler als auch die Standardwerte des Treibers werden wiederholt.

Der Ersetzungs- oder Anfügemodus ist global für den gesamten retryConn Wert. Wenn in diesem Wert eine Regel + auslässt, schaltet der Treiber für alle in diesem Wert enthaltenen Regeln in den Ersetzungsmodus. Beispielsweise fügt retryConn={+4060};{40143} 4060 und 40143 der integrierten Liste nicht hinzu. Die Regel 40143 lässt + aus, sodass die integrierte Liste verworfen wird und nur 4060 und 40143 erneut versucht werden. Um beide anzuhängen, schreiben Sie retryConn={+4060};{+40143} (oder retryConn={+4060,40143}).

Die Verbindungsschleife verwendet weiterhin connectRetryInterval und connectRetryCount zur Taktung und Begrenzung. Die CRL-Regel erweitert oder ersetzt die Menge der Fehler, die für einen Wiederholungsversuch infrage kommen.

Beispiele (Verbindungen)

Integrierte Liste vorübergehender Verbindungsfehler

Die Verbindungs-Wiederholungsschleife wiederholt bereits die folgenden Fehler ohne CRL-Konfiguration, solange .connectRetryCount > 0 Die Auflistung eines dieser Fehler in einer retryConn-Regel mit + ist wirkungslos (da sie bereits abgedeckt sind). Verwenden Sie eine retryConn-Regel, wenn Sie einen Fehler hinzufügen müssen, der in dieser Liste nicht enthalten ist, oder wenn Sie die Liste vollständig verwerfen müssen, indem Sie das no-+-Ersetzen-Format verwenden.

Die kanonische Liste des Treibers ist die TransientError Enumeration in SQLServerError.java. Fehlermeldungstext stammt aus Azure SQL vorübergehenden Verbindungsfehlern. Fehler auf Anweisungsebene (z. B. Deadlock-Opfer 1205 oder Zeitüberschreitung der Sperranforderung 1222) stehen nicht in dieser Liste, da die Verbindungswiederholungsschleife nur beim initialen Verbindungsaufbau greift. Verwenden Sie eine retryExec Regel, um diese Fehler erneut zu versuchen.

Laden von Regeln aus einer Eigenschaftendatei

Wenn Sie auf der Verbindung retryExec oder retryConn nicht festlegen, sucht CRL auf dem Klassenpfad neben dem Treiber-JAR nach einer Datei namens mssql-jdbc.properties. Die Datei verwendet einfaches key=value Parsing. Zeilen, die mit retryExec= oder retryConn= beginnen, werden erfasst. Werte verwenden dieselbe Syntax, die in diesem Artikel beschrieben wird, und ; trennen mehrere Regeln.

Verwenden Sie genaue Schlüsselnamen (retryExec und retryConn), ohne führende Leerzeichen. Die Datei wird nicht als vollständige Java Eigenschaftendatei analysiert. Der Treiber prüft in jeder Zeile wörtlich auf startsWith, also:

• Zeilen, die mit # oder einem anderen Präfix als retryExec/retryConn beginnen, werden ignoriert.
• Zeilen, deren Schlüssel nur mit retryExec oder retryConn beginnen (zum Beispiel retryExec2=...), werden als entsprechende Eigenschaft behandelt und können Syntaxanalysefehler verursachen. Stellen Sie keine benutzerdefinierten Varianten vor.

Beispiel mssql-jdbc.properties:

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

Wenn die Datei fehlt, protokolliert die CRL im Logger com.microsoft.sqlserver.jdbc.ConfigurableRetryLogic eine Meldung FINE und fährt ohne Regeln fort. Der für die Suche verwendete Dateipfad ist in dieser Protokollmeldung enthalten.

Die Werte der Verbindungszeichenfolge haben Vorrang. Wenn retryExec oder retryConn in der Verbindung nicht leer sind, zieht der Treiber für diese Eigenschaft die Datei nicht heran.

Regelaktualisierungsverhalten

CRL verwaltet einen einzelnen, JVM-weiten Regelsatz. Nach dem Bau aktualisiert der Fahrer die Regeln lazily:

• Der Treiber bewertet Gelegenheiten zur Aktualisierung während der Ausführung der Anweisung und bei erneuten Verbindungsversuchen.
• Eine Aktualisierung erfolgt tatsächlich erst, nachdem seit dem vorherigen Lesevorgang 30 Sekunden vergangen sind.
• Wenn die Regeln ursprünglich von mssql-jdbc.properties kamen, vergleicht der Treiber den Zeitstempel der letzten Änderung der Datei mit dem Zeitstempel, den er beim vorherigen Lesen aufgezeichnet hat. Wenn sich die Datei geändert hat, analysiert der Treiber sie erneut.
• Wenn die Regeln ursprünglich aus einem Verbindungszeichenfolge stammen, wendet der Treiber den zuvor gespeicherten Verbindungszeichenfolgenwert erneut an.

Dieses Verhalten bedeutet, dass Änderungen an mssql-jdbc.properties innerhalb von etwa 30 Sekunden automatisch erkannt werden, ohne die Anwendung neu zu starten.

Interaktion mit queryTimeout und connectRetryCount

Anweisungswiederholungen und queryTimeout

Wenn eine Anweisungsregel ausgelöst wird, vergleicht der Treiber die nächste Wartezeit mit dem Wert auf Verbindungsebene queryTimeout :

• Wenn queryTimeout >= 0undtimeToWait > queryTimeout, löst der Treiber R_InvalidRetryInterval aus, anstatt es erneut zu versuchen. Der Treiber löst den ursprünglichen Fehler nicht erneut aus. Er löst den Konfigurationsfehler aus.
• Die queryTimeout-Verbindungseigenschaft ist standardmäßig auf -1 gesetzt, sodass der Vergleich standardmäßig übersprungen wird und jede Wartezeit zulässig ist.
• Die Einstellung queryTimeout=0 deaktiviert diese Überprüfung nicht , da 0 >= 0 "true" ist. Beliebige timeToWait > 0 erhöht R_InvalidRetryInterval.

Wenn Sie queryTimeout auf einen positiven Wert festlegen, halten Sie den initialRetryTime + (retryCount - 1) * retryChange-Wert (additiv) bzw. den initialRetryTime * retryChange^(retryCount-1)-Wert (multiplikativ) darunter.

Verbindungswiederholungen und connectRetryCount und loginTimeout

retryConn ermöglicht für sich genommen keine Wiederholungen der Authentifizierung. Die vorhandenen Eigenschaften bleiben zuständig:

• connectRetryCount (Standard 1, Bereich 0-255) ist die Anzahl zusätzlicher Authentifizierungsversuche. Setzen Sie es auf 0, um Authentifizierungswiederholungen zu deaktivieren. retryConn hat keine Auswirkung, wenn connectRetryCount = 0der Treiber den ersten Fehler auslöst.
• connectRetryInterval (Standard 10 Sekunden, Bereich 1-60) ist die Wartezeit zwischen versuchen. Der erste Wiederholungsversuch wird sofort ausgeführt.
• loginTimeout ist die Gesamtschranke. Der Treiber bricht frühzeitig ab, wenn durch das nächste Intervall die verstrichene Zeit über loginTimeout steigen würde.

Weitere Informationen finden Sie unter Verbindungsresilienz (JDBC).

Beispiele

Überleben von Deadlocks und Sperrtimeouts für Schreibvorgänge

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

Bis zu vier Wiederholungen für Deadlock-Opfer (1205) oder Sperrtimeout (1222), mit Backoff von 2, 4, 8 und 16 Sekunden, aber nur für Schreibanweisungen.

Schemaerstellung während des Onlinebetriebs erneut ausführen

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

Wiederholt Fehler 2714 (object already exists) und 3702 (cannot drop database currently in use) jeweils zweimal mit Wartezeiten von 1 bzw. 2 Sekunden.

Hinzufügen eines benutzerdefinierten Fehlers zur Liste vorübergehender Fehler

retryConn={+<customErrorNumber>}

Fügt eine benutzerdefinierte Fehlernummer hinzu, die noch nicht in der integrierten Liste enthalten ist. Wenn Sie einen integrierten Azure SQL vorübergehenden Fehler anfügen, z. B. 40197, 40501, 40613, 49918, 49919 oder 49920, ändert sich nichts, da der Treiber dies bereits erneut anzeigt.

Konfigurieren von CRL über eine Eigenschaftendatei

Platzieren Sie mssql-jdbc.properties neben dem Treiber-JAR:

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

Legen Sie für die Verbindung nicht retryExec oder retryConn fest. Der Treiber liest die Regeln aus der Datei ein und liest sie nach jeder Änderung erneut ein (wird alle 30 Sekunden überprüft).

Problembehandlung bei CRL

Aktivieren FINE (oder feiner) Protokollierung beim com.microsoft.sqlserver.jdbc.ConfigurableRetryLogic Logger, um Dateileseversuche und Analyseentscheidungen anzuzeigen:

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

Häufige Konfigurationsfehler:

Was zu prüfen ist, wenn eine Regel nicht ausgelöst wird:

1. Die Ausnahme SQLServerError.getErrorNumber() stimmt tatsächlich mit der Zahl in Ihrer Regel überein. SQL Server können einige Fehler je nach Kontext (z. B. Deadlock vs. Sperrtimeout) in verschiedene Zahlen umschließen.
2. Bei Statement-Regeln mit einem queryFilter befindet sich das erste durch Leerzeichen getrennte Token der ausgeführten SQL-Anweisung in Kleinbuchstaben in der Filterliste. Kommentare und WITH CTEs ändern das erste Token.
3. retryCount Wiederholungsversuche sind zusätzliche Versuche. Die erste Ausführung zählt nicht.
4. Bei Verbindungsregeln connectRetryCount ist es größer als 0 und loginTimeout lässt Platz für mindestens ein weiteres connectRetryInterval.
5. Die Regel hat die richtige Form. Regeln für Anweisungen benötigen einen Abschnitt für Zeitangaben. Verbindungsregeln dürfen nicht.

Verwandte Inhalte

• Verbindungsresilienz (JDBC)
• Grundlagen zu Timeout-Eigenschaften im JDBC-Treiber
• Festlegen der Verbindungseigenschaften
• Diagnostizieren von Problemen mit dem JDBC-Treiber