Konfigurerbar omprövningslogik (JDBC)

Ladda ned JDBC-drivrutin

Konfigurerbar omprövningslogik (CRL) är en regelbaserad mekanism som automatiskt försöker utföra misslyckade instruktioner eller inledande anslutningsförsök baserat på SQL Server felnummer som du väljer, med tidsparametrar som du styr. CRL introducerades i Microsoft JDBC Driver 12.10 för SQL Server.

CRL är separat från återställning för vilande anslutning och egenskaperna connectRetryCount / connectRetryInterval. Resiliens vid inaktivitet återställer brutna anslutningar transparent, och connectRetryCount försöker utföra den inledande autentiseringen igen med fasta intervall för fel i en inbyggd lista över tillfälliga fel. Med CRL kan du bestämma vilka fel som kan försökas igen, hur många gånger och hur länge du ska vänta mellan försöken. Du kan använda alla tre mekanismerna tillsammans.

Vilka återförsök för CRL

CRL hanterar två distinkta scenarier som var och en styrs av sin egen anslutningsegenskap:

För satser försöker drivrutinen bara köra om det kommando som misslyckades. Drivrutinen återställer inte det aktuella transaktionstillståndet, så utforma dina regler kring fel som lämnar sessionen användbar, till exempel dödlägesoffer (1205) eller tidsgräns för lås (1222).

För anslutningar utökar eller ersätter CRL drivrutinens inbyggda lista över tillfälliga anslutningsfel. Se Regler för anslutningsförsök för prefixets + semantik.

Aktivera CRL

CRL har två lager:

1. Skiktet för anslutningsförsök är aktiverat som standard: så länge connectRetryCount > 0 (standardvärdet är 1) försöker drivrutinen igen den inbyggda listan över tillfälliga anslutningsfel.
2. Anpassningsskiktet (dina egna retryExec regler) retryConn är inaktiverat som standard. Båda egenskaperna är tomma strängar om du inte anger dem. Du kan ange dem via JDBC-URL:en, ett Properties objekt eller en SQLServerDataSource. Drivrutinen tar bort de valfria omslutande taggarna {...} i alla tre formerna.

Java kodfragment i den här artikeln utelämnar importer och klassomslutningar för korthet.

I JDBC-URL:en

Varje regel (eller hela listan med regler) måste vara omsluten i klammerparenteser ({...}) eftersom JDBC-URL:en använder ; som avgränsare:

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

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

Med SQLServerDataSource

Samma setters finns i ISQLServerDataSource gränssnittet:

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

Regelsyntax

En enda regel har upp till tre kolonavgränsade avsnitt:

<errorNumbers> : <retryTimings> : <queryFilter>

Om du vill använda flera regler i samma egenskap separerar du dem med ; och omsluter varje regel med {...} när du placerar dem i en JDBC-URL.

Tidsparametrar

För en instruktionsregel med tidsinställningar retryCount, initialRetryTime <op> retryChange:

• retryCount: Antalet ytterligare försök som drivrutinen gör efter det första felet. Värdet 0 inaktiverar återförsök. Negativa värden är ogiltiga.
• initialRetryTime: Antalet sekunder att vänta innan det första återförsöket. Standardvärdet är 0.
• <op>: Operatorn, som kan vara + eller *. Standardvärdet är +.
• retryChange: Det belopp som tillämpas på beräkning av efterföljande väntetider. Standardvärdet är 2. När operanden är * och retryChange utelämnas i regeln anger drivrutinen retryChange = initialRetryTime.

Drivrutinen beräknar väntetiden för försök i (med början på 0) vid parsning:

Exempel på tidssträngar:

Ett retryTimings avsnitt kan innehålla högst ett kommatecken. Mer än ett kommatecken höjer R_invalidParameterNumber.

Återförsöksregler för instruktion (retryExec)

Satsregler försöker köra om misslyckad satskörning. När en sats utlöser en SQLServerException, gör drivrutinen följande:

1. Söker upp felnumret för felet i regeluppsättningen för den tolkade satsen.
2. Om det finns en regel och det aktuella antalet försök är mindre än retryCountkontrollerar du eventuellt den senast utförda SQL-filen mot regelns queryFilter.
3. Om allt stämmer väntar drivrutinen waitTimes[retryAttempt] sekunder (med förbehåll för queryTimeout, se Interaktion med queryTimeout och connectRetryCount) och kör sedan satsen igen.
4. Om ingen regel matchar, kommer drivrutinen att ändra undantaget.

Format (satser)

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

Instruktionsregler måste innehålla ett tidsavsnitt. retryCount är obligatoriskt. En regel som endast innehåller ett felnummer tolkas som en anslutningsregel, så ange alltid åtminstone retryCount för satser.

Exempel (påståenden)

Att visa flera felnummer (till exempel 1205,1222) är en förkortning. Drivrutinen utökar regeln till en post per fel, där alla har samma tidsinställning och frågefilter.

Regler för återförsök av anslutning (retryConn)

Anslutningsreglerna samverkar med den befintliga anslutnings- och återförsöksloopen. Den här loopen är bara aktiv när connectRetryCount > 0 (standardvärdet är 1). Slingan gör redan omförsök för en inbyggd lista med övergående anslutningsfel med connectRetryInterval sekunders mellanrum, upp till connectRetryCount extra försök, och avgränsas av loginTimeout.

En anslutningsregel tillhandahåller endast ett avsnitt med felnummer. Den har inga tidsinställningar eller frågefilter:

{[+]errorNumber(s)}

• Utan +ersätter de konfigurerade reglerna den inbyggda tillfälliga fellistan. Endast fel som du listar görs på nytt.
• Med + (till exempel {+4060}) läggs de konfigurerade reglerna till i den inbyggda listan. Både dina fel och standardinställningarna för drivrutinen görs på nytt.

Läget Ersätt eller lägg till är globalt för hela retryConn värdet. Om någon regel i det värdet utelämnar +växlar drivrutinen till ersättningsläge för alla regler i det värdet. Lägger till exempel retryConn={+4060};{40143} inte till 4060 och 40143 i den inbyggda listan. Regeln 40143 utelämnar +, så den inbyggda listan tas bort och endast 4060 och 40143 görs om. Om du vill infoga båda, skriv retryConn={+4060};{+40143} (eller retryConn={+4060,40143}).

Anslutningsslingan fortsätter att använda connectRetryInterval och connectRetryCount för takthållning och avgränsning. CRL-regeln expanderar eller ersätter den uppsättning fel som är berättigade till återförsök.

Exempel (anslutningar)

Inbyggd lista över tillfälliga anslutningsfel

Loopen för connect-retry gör redan nya försök vid följande fel utan någon CRL-konfiguration, så länge connectRetryCount > 0. Att ange något av dessa fel i en retryConn-regel med + är ingen åtgärd (de täcks redan). Använd en retryConn regel när du behöver lägga till ett fel som inte finns i den här listan, eller när du behöver ta bort listan helt genom att använda no-+ replace-formen.

Drivrutinens kanoniska lista är TransientError enum i SQLServerError.java. Felmeddelandetexten kommer från Azure SQL tillfälliga anslutningsfel. Fel på instruktionsnivå (till exempel deadlock victim 1205 eller timeout för låsbegäran 1222) finns inte i den här listan eftersom loopen för återförsök endast utlöses under den första anslutningen. För att försöka igen med dessa fel använder du en retryExec-regel.

Läsa in regler från en egenskapsfil

Om du inte anger retryExec eller retryConn på anslutningen letar CRL efter en fil med namnet mssql-jdbc.properties bredvid drivrutins-JAR:en på klassökvägen. Filen använder grundläggande key=value parsning. Rader som börjar med retryExec= eller retryConn= plockas upp. Värden har samma syntax som beskrivs i den här artikeln, där ; avgränsar flera regler.

Använd exakta nyckelnamn (retryExec och retryConn), utan inledande blanksteg. Filen parsas inte som en fullständig Java egenskapsfil. Drivrutinen gör en bokstavlig kontroll av startsWith på varje rad, så:

• Rader som börjar med # eller något annat prefix än retryExec/retryConn ignoreras.
• Rader vars nyckel bara börjar med retryExec eller retryConn (till exempel retryExec2=...) behandlas som matchande egenskap och kan generera parsningsfel. Introducera inte anpassade varianter.

Exempel mssql-jdbc.properties:

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

Om filen saknas, loggar CRL ett FINE-meddelande i loggaren com.microsoft.sqlserver.jdbc.ConfigurableRetryLogic och fortsätter utan regler. Den filsökväg som används för sökningen ingår i det loggmeddelandet.

Anslutningssträngsvärden har företräde. Om retryExec eller retryConn inte finns i anslutningen läser drivrutinen inte filen för den egenskapen.

Regeluppdateringsbeteende

CRL har en enda JVM-omfattande regeluppsättning. Efter konstruktionen uppdaterar drivrutinen reglerna först vid behov:

• Drivrutinen utvärderar uppdateringsmöjligheter under körning av instruktioner och återförsök av anslutningar.
• En uppdatering sker faktiskt bara efter att 30 sekunder har förflutit sedan föregående läsning.
• Om reglerna ursprungligen kom från mssql-jdbc.propertiesjämför drivrutinen filens senast ändrade tidsstämpel med tidsstämpeln som registrerades vid föregående läsning. Om filen har ändrats returnerar drivrutinen den.
• Om reglerna ursprungligen kom från en anslutningssträng tillämpar drivrutinen på nytt det tidigare lagrade värdet från anslutningssträngen.

Det här beteendet innebär att ändringar i mssql-jdbc.properties upptäcks automatiskt inom cirka 30 sekunder utan att programmet behöver startas om.

Interaktion med queryTimeout och connectRetryCount

Satser och omförsök queryTimeout

När en instruktionsregel utlöses jämför drivrutinen nästa väntetid med värdet på anslutningsnivå queryTimeout :

• Om queryTimeout >= 0ochtimeToWait > queryTimeout, utlöser drivrutinen R_InvalidRetryInterval i stället för att försöka igen. Drivrutinen kastar inte det ursprungliga felet vidare igen. Det ger ett konfigurationsfel.
• Anslutningsegenskapen queryTimeout har standardvärdet -1, så jämförelsen hoppas över som standard och all väntan tillåts.
• Inställningen queryTimeout=0 inaktiverar inte den här kontrollen eftersom 0 >= 0 den är sann. Varje timeToWait > 0 ökar R_InvalidRetryInterval.

När du anger queryTimeout ett positivt värde ska du hålla initialRetryTime + (retryCount - 1) * retryChange (additivt) eller initialRetryTime * retryChange^(retryCount-1) (multiplikativt) värde under det.

Återförsök av anslutningar och connectRetryCount och loginTimeout

retryConn aktiverar inte i sig omförsök för autentisering. De befintliga egenskaperna har fortfarande ansvaret:

• connectRetryCount (standard 1, intervall 0–255) är antalet extra autentiseringsförsök. Ställ in den på 0 för att inaktivera autentiseringsförsök. retryConn har ingen effekt när connectRetryCount = 0, eftersom drivrutinen genererar det första felet.
• connectRetryInterval (standardvärdet 10 sekunder, intervallet 1–60) är väntetiden mellan försöken. Det första återförsöket körs omedelbart.
• loginTimeout är den övergripande gränsen. Drivrutinen ger upp i förtid om nästa intervall skulle göra att den förflutna tiden överskrider loginTimeout.

Mer information finns i Anslutningsåterhämtning (JDBC).

Examples

Överleva dödlägen och låsa timeouter vid skrivningar

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

Upp till fyra återförsök för deadlock victim (1205) eller lock timeout (1222), med backoff på 2, 4, 8 och 16 sekunder, men bara för skrivinstruktioner.

Kör schemaskapandet igen under onlineåtgärder

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

Återförsöksfel 2714 (object already exists) och 3702 (cannot drop database currently in use) två gånger vardera, med 1 och 2 sekunders väntetid.

Lägga till ett anpassat fel i listan över tillfälliga fel

retryConn={+<customErrorNumber>}

Lägger till ett anpassat felnummer som inte redan finns i den inbyggda listan. Om du lägger till ett inbyggt Azure SQL tillfälligt fel, till exempel 40197, 40501, 40613, 49918, 49919 eller 49920, ändras ingenting eftersom drivrutinen redan försöker igen.

Konfigurera CRL via en egenskapsfil

Placera mssql-jdbc.properties bredvid drivrutins-JAR-filen:

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

Ställ inte in retryExec eller retryConn på anslutningen. Drivrutinen läser reglerna från filen och läser om efter varje ändring (kontrolleras en gång var 30:e sekund).

Felsöka CRL

Aktivera FINE (eller finare) loggning på loggaren com.microsoft.sqlserver.jdbc.ConfigurableRetryLogic för att se filläsningsförsök och parsningsbeslut:

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

Vanliga konfigurationsfel:

Saker att kontrollera när en regel inte utlöses:

1. SQLServerError.getErrorNumber() Undantaget matchar faktiskt numret i regeln. SQL Server kan rapportera vissa feltyper med olika nummer beroende på sammanhanget (till exempel dödläge jämfört med tidsgräns för lås).
2. För instruktionsregler med en queryFilterfinns den första blankstegsavgränsade token för den SQL som du körde (nedsänkt) i filterlistan. Kommentarer och WITH CTE:er ändrar den första token.
3. retryCount återförsök är ytterligare försök. Den första körningen räknas inte.
4. För anslutningsregler connectRetryCount är större än 0 och loginTimeout lämnar utrymme för minst en till connectRetryInterval.
5. Regeln har rätt form. Satsregler måste ha ett avsnitt för tidsinställningar. Anslutningsreglerna får inte vara det.

Relaterat innehåll

• Anslutningsresiliens (JDBC)
• Förstå timeout-egenskaper i JDBC-drivrutinen
• Ange anslutningsegenskaperna
• Diagnostisera problem med JDBC-drivrutinen