Logica di ripetizione dei tentativi configurabile (JDBC)

Scaricare il driver JDBC

La logica di ripetizione configurabile (CRL) è un meccanismo basato su regole che ripete automaticamente le istruzioni non riuscite o i tentativi iniziali di connessione in base ai numeri di errore di SQL Server selezionati, con parametri di temporizzazione controllati dall’utente. CRL è stato introdotto in Microsoft JDBC Driver 12.10 per SQL Server.

CRL è separato dalla resilienza delle connessioni inattive e dalle proprietà connectRetryCount / connectRetryInterval. La resilienza inattiva recupera in modo trasparente le connessioni interrotte e connectRetryCount ritenta l'autenticazione iniziale in base a una pianificazione fissa per un elenco predefinito di errori temporanei. CRL consente di decidere quali errori sono riprovabili, quante volte e per quanto tempo attendere tra i tentativi. È possibile usare insieme tutti e tre i meccanismi.

Tentativi CRL

CRL gestisce due scenari distinti, ognuno controllato dalla propria proprietà di connessione:

Nel caso delle istruzioni, il driver ritenta solo il comando non riuscito. Il driver non reimposta lo stato corrente della transazione, quindi è opportuno progettare le regole tenendo conto degli errori che lasciano la sessione utilizzabile, ad esempio vittima del deadlock (1205) o timeout di lock (1222).

Per le connessioni, CRL aumenta o sostituisce l'elenco predefinito del driver di errori di connessione temporanei. Vedere Regole di ripetizione dei tentativi di connessione per la semantica del + prefisso.

Abilitare CRL

CRL ha due livelli:

1. Il livello di ripetizione dei tentativi di connessione è attivo per impostazione predefinita: purché connectRetryCount > 0 (il valore predefinito sia 1), il driver ritenta l'elenco degli errori di connessione temporanei predefiniti.
2. Il livello di personalizzazione (le tue regole retryExec e retryConn) è disattivato per impostazione predefinita. Entrambe le proprietà sono stringhe vuote, a meno che non vengano impostate. È possibile impostarli tramite l'URL JDBC, un Properties oggetto o un oggetto SQLServerDataSource. Il driver rimuove gli involucri facoltativi {...} in tutte e tre le forme.

I frammenti di codice Java in questo articolo omettono le istruzioni import e le dichiarazioni di classe per brevità.

Nell'URL JDBC

Ogni regola (o l'intero elenco di regole) deve essere racchiusa tra parentesi graffe ({...}) perché l'URL JDBC usa ; come separatore:

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

Con un oggetto 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);

Con SQLServerDataSource

Gli stessi setter esistono nell'interfaccia ISQLServerDataSource :

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

Sintassi delle regole

Una singola regola è composta da un massimo di tre sezioni separate da due punti:

<errorNumbers> : <retryTimings> : <queryFilter>

Per usare più regole nella stessa proprietà, separarle con ; e racchiudere ogni regola con {...} quando le si inserisce in un URL JDBC.

Parametri di temporizzazione

Per una regola di istruzione con intervalli retryCount, initialRetryTime <op> retryChange:

• retryCount: numero di tentativi aggiuntivi eseguiti dal driver dopo il primo errore. Il valore 0 disabilita la ripetizione dei tentativi. I valori negativi non sono validi.
• initialRetryTime: numero di secondi di attesa prima del primo tentativo. Il valore predefinito è 0.
• <op>: operatore, che può essere + o *. Il valore predefinito è +.
• retryChange: quantità applicata al calcolo dei tempi di attesa successivi. Il valore predefinito è 2. Quando l'operando è * e retryChange viene omesso dalla regola, il driver imposta retryChange = initialRetryTime.

Il driver calcola il tempo di attesa per il tentativo i (basato su 0) in fase di analisi:

Esempi di stringhe temporali:

Una retryTimings sezione può contenere al massimo una virgola. Più di una virgola genera R_invalidParameterNumber.

Regole di ripetizione dei tentativi di istruzione (retryExec)

Le regole delle istruzioni riprovano a eseguire un'istruzione non riuscita. Quando un'istruzione genera un SQLServerException, il driver:

1. Cerca il numero di errore non riuscito nel set di regole dell'istruzione analizzata.
2. Se esiste una regola e il numero corrente di tentativi è inferiore a retryCount, verifica facoltativamente l'ultima istruzione SQL eseguita rispetto a queryFilter della regola.
3. Se tutto corrisponde, il driver attende waitTimes[retryAttempt] secondi (soggetto a queryTimeout, vedere Interazione con queryTimeout e connectRetryCount) ed esegue nuovamente l'istruzione.
4. Se nessuna regola corrisponde, il driver rilancia l'eccezione.

Formato (istruzioni)

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

Le istruzioni devono includere una sezione delle temporizzazioni. retryCount è obbligatorio. Una regola che contiene solo un numero di errore viene interpretata come regola di connessione , quindi per le istruzioni specificano sempre almeno retryCount.

Esempi (istruzioni)

L'elenco di diversi numeri di errore (ad esempio, 1205,1222) è una forma abbreviata. Il driver espande la regola in una voce per ciascun errore, con tutte le voci che condividono la stessa temporizzazione e lo stesso filtro della query.

Regole di ripetizione dei tentativi di connessione (retryConn)

Le regole di connessione funzionano con il ciclo di ripetizione dei tentativi di connessione esistente. Questo ciclo è attivo solo quando connectRetryCount > 0 il valore predefinito è 1. Il ciclo ripete già i tentativi per una serie predefinita di errori di connessione transitori a intervalli di connectRetryInterval secondi, fino a un massimo di connectRetryCount tentativi aggiuntivi, con un limite definito da loginTimeout.

Una regola di connessione fornisce solo una sezione relativa al numero di errore. Non ha tempistiche né filtro di query:

{[+]errorNumber(s)}

• Senza +, le regole configurate sostituiscono l'elenco di errori temporanei predefiniti. Vengono ritentati solo gli errori elencati.
• Con + (ad esempio, {+4060}), le regole configurate vengono aggiunte all'elenco predefinito. Vengono ritentati sia gli errori che i valori predefiniti del driver.

La modalità di sostituzione o aggiunta è globale per l'intero valore retryConn. Se una regola in tale valore omette +, il driver passa alla modalità di sostituzione per tutte le regole in tale valore. Ad esempio, retryConn={+4060};{40143} non aggiunge 4060 e 40143 all'elenco predefinito. La 40143 regola omette +, quindi l'elenco predefinito viene eliminato e vengono ritentati solo 4060 e 40143. Per accodare entrambi, scrivere retryConn={+4060};{+40143} (o retryConn={+4060,40143}).

Il ciclo di connessione continua a usare connectRetryInterval e connectRetryCount per la temporizzazione e la delimitazione. La regola CRL espande o sostituisce il set di errori idonei per la ripetizione dei tentativi.

Esempi (connessioni)

Elenco di errori di connessione temporanei predefiniti

Il ciclo connect-retry ritenta già gli errori seguenti senza alcuna configurazione CRL, purché connectRetryCount > 0. Elencare uno di questi errori in una retryConn regola con + è un no-op (sono già coperti). Usa una retryConn regola quando devi aggiungere un errore che non è presente in questo elenco, oppure quando devi rimuovere del tutto l'elenco usando la forma no-+ replace.

L'elenco canonico del driver è TransientError enum in SQLServerError.java. Il testo del messaggio di errore proviene da Azure SQL errori di connessione temporanei. Gli errori a livello di istruzione (ad esempio deadlock victim 1205 o lock-request timeout 1222) non sono inclusi in questo elenco, perché il ciclo connect-retry viene attivato solo durante la connessione iniziale. Per ritentare tali errori, usare una retryExec regola.

Caricare regole da un file di proprietà

Se non si imposta retryExec o retryConn nella connessione, CRL cerca un file denominato mssql-jdbc.properties accanto al file JAR del driver nel classpath. Il file usa il parsing di base key=value. Linee che iniziano con retryExec= o retryConn= vengono prelevate. I valori usano la stessa sintassi descritta in questo articolo, con ; la separazione di più regole.

Usare nomi di chiave esatti (retryExec e retryConn), senza spazi vuoti iniziali. Il file non viene analizzato come file di proprietà completo Java. Il driver esegue un controllo letterale startsWith su ogni riga, quindi:

• Le righe che iniziano con # o qualsiasi altro prefisso non-retryExec/retryConn vengono ignorate.
• Le righe la cui chiave inizia solo con retryExec o retryConn (ad esempio, retryExec2=...) vengono considerate come la proprietà corrispondente e possono generare errori di analisi. Non introdurre varianti personalizzate.

Esempio mssql-jdbc.properties:

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

Se il file è mancante, CRL registra un FINE messaggio nel com.microsoft.sqlserver.jdbc.ConfigurableRetryLogic logger e continua senza regole. Il percorso del file usato per la ricerca è incluso nel messaggio di log.

I valori della stringa di connessione hanno la precedenza. Se retryExec o retryConn non sono vuoti sulla connessione, il driver non consulta il file per quella proprietà.

Comportamento di aggiornamento delle regole

CRL gestisce un unico insieme di regole valido per l’intera JVM. Dopo la costruzione, il driver aggiorna le regole solo quando necessario:

• Il driver valuta le possibilità di aggiornamento durante l'esecuzione dell'istruzione e durante i tentativi di riconnessione.
• Un aggiornamento viene effettivamente eseguito solo dopo 30 secondi trascorsi dalla lettura precedente.
• Se le regole provengono originariamente da mssql-jdbc.properties, il driver confronta il timestamp dell'ultima modifica del file con il timestamp registrato nella lettura precedente. Se il file è stato modificato, il driver lo analizza nuovamente.
• Se le regole provengono originariamente da un stringa di connessione, il driver riapplica il valore della stringa di connessione archiviato in precedenza.

Questo comportamento significa che le modifiche apportate a mssql-jdbc.properties vengono prelevate automaticamente entro circa 30 secondi senza riavviare l'applicazione.

Interazione con queryTimeout e connectRetryCount

Nuovi tentativi di istruzione e queryTimeout

Quando si attiva una regola di statement, il driver confronta il tempo di attesa successivo con il valore queryTimeout a livello di connessione:

• Se queryTimeout >= 0etimeToWait > queryTimeout, il driver genera R_InvalidRetryInterval invece di riprovare. Il driver non rigenera l'errore originale. Genera l'errore di configurazione.
• La proprietà di connessione queryTimeout è impostata per impostazione predefinita su -1, quindi per impostazione predefinita il confronto viene ignorato ed è consentita qualunque attesa.
• L'impostazione queryTimeout=0non disabilita questo controllo, perché 0 >= 0 è true. Ogni timeToWait > 0 solleva R_InvalidRetryInterval.

Quando si imposta queryTimeout su un valore positivo, mantenere il valore di initialRetryTime + (retryCount - 1) * retryChange (additivo) o di initialRetryTime * retryChange^(retryCount-1) (moltiplicativo) inferiore a tale valore.

Tentativi di connessione e connectRetryCount e loginTimeout

retryConn non abilita per sé i tentativi di autenticazione. Le impostazioni esistenti restano in vigore:

• connectRetryCount (valore predefinito 1, intervallo 0-255) è il numero di tentativi di autenticazione aggiuntivi. Impostarlo su 0 per disabilitare i tentativi di autenticazione. retryConn non ha alcun effetto quando connectRetryCount = 0, perché il driver genera il primo errore.
• connectRetryInterval (valore predefinito 10 secondi, intervallo da 1 a 60) è l'attesa tra i tentativi. Il primo tentativo viene eseguito immediatamente.
• loginTimeout è il limite complessivo. Il driver rinuncia in anticipo se l'intervallo successivo farebbe superare al tempo trascorso loginTimeout.

Per altre informazioni, vedere Resilienza della connessione (JDBC).

Examples

Gestire i deadlock e i timeout di lock durante le operazioni di scrittura

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

Fino a quattro nuovi tentativi in caso di vittima di deadlock (1205) o timeout di lock (1222), con intervalli di attesa progressivi di 2, 4, 8 e 16 secondi, ma solo per le istruzioni di scrittura.

Rieseguire la creazione dello schema nelle operazioni online

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

Ritenta l'errore 2714 (object already exists) e 3702 (cannot drop database currently in use) due volte ciascuno, con 1 e 2 secondi di attesa.

Aggiungere un errore personalizzato all'elenco degli errori temporanei

retryConn={+<customErrorNumber>}

Aggiunge un numero di errore personalizzato non già incluso nell'elenco predefinito. Se si aggiunge un errore predefinito Azure SQL temporaneo, ad esempio 40197, 40501, 40613, 49918, 49919 o 49920, nulla cambia perché il driver lo ritenta già.

Configurare CRL tramite un file di proprietà

Posizionare mssql-jdbc.properties accanto al file JAR del driver:

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

Non impostare retryExec o retryConn sulla connessione. Il driver legge le regole dal file e rilettura dopo ogni modifica (controllata una volta ogni 30 secondi).

Risolvere i problemi di CRL

Attiva il logging FINE (o più dettagliato) sul logger com.microsoft.sqlserver.jdbc.ConfigurableRetryLogic per visualizzare i tentativi di lettura dei file e le decisioni di parsing:

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

Errori di configurazione comuni:

Elementi da controllare quando una regola non viene attivata:

1. L'eccezione SQLServerError.getErrorNumber() corrisponde effettivamente al numero nella regola. SQL Server può ricondurre alcuni errori a numeri diversi a seconda del contesto, ad esempio deadlock o timeout di blocco.
2. Per le regole di istruzione con , queryFilteril primo token delimitato da spazi vuoti del codice SQL eseguito (in minuscolo) si trova nell'elenco di filtri. Commenti e WITH CTE modificano il primo token.
3. retryCount i nuovi tentativi sono tentativi aggiuntivi. La prima esecuzione non conta.
4. Per le regole di connessione, connectRetryCount è maggiore di 0 e loginTimeout lascia spazio per almeno un altro connectRetryInterval.
5. La regola ha la forma corretta. Le regole delle istruzioni richiedono una sezione delle temporizzazioni. Le regole di connessione non devono essere.

Contenuti correlati

• Resilienza della connessione (JDBC)
• Informazioni sulle proprietà di timeout nel driver JDBC
• Impostare le proprietà di connessione
• Diagnosi dei problemi relativi al driver JDBC