Lógica de nova tentativa configurável (JDBC)

Baixar driver JDBC

A lógica de repetição configurável (CRL) é um mecanismo baseado em regras que repete automaticamente instruções que falharam ou tentativas iniciais de ligação, com base nos números de erro do SQL Server que selecionar, com parâmetros de temporização definidos por si. O CRL foi introduzido no Microsoft JDBC Driver 12.10 para SQL Server.

O CRL é separado da resiliência da ligação inativa e das propriedadesconnectRetryCount / connectRetryInterval. A recuperação automática em inatividade restabelece de forma transparente ligações interrompidas e connectRetryCount repete a autenticação inicial a intervalos fixos para uma lista predefinida de erros transitórios. O CRL permite decidir que erros podem ser repetidos, quantas vezes e quanto tempo esperar entre tentativas. Podes usar os três mecanismos em conjunto.

O que o CRL retenta

O CRL lida com dois cenários distintos, cada um controlado pela sua própria propriedade de ligação:

Para instruções, o driver repete apenas o comando que falhou. O controlador não repõe o estado atual da transação, pelo que deves conceber as regras em função de erros que mantenham a sessão utilizável, como vítima de impasse (1205) ou tempo limite de bloqueio (1222).

Para ligações, o CRL complementa ou substitui a lista interna do controlador de erros transitórios de ligação. Consulte Regras de nova tentativa de ligação para a semântica do prefixo +.

Ativar CRL

O CRL tem duas camadas:

1. A camada de repetição da ligação está ativada por predefinição: enquanto connectRetryCount > 0 (a predefinição é 1), o controlador volta a tentar a ligação com base na lista integrada de erros transitórios de ligação.
2. A camada de personalização (as tuas próprias regras retryExec e retryConn) está desativada por defeito. Ambas as propriedades são cadeias vazias, a menos que as definas. Pode defini-los através do URL JDBC, de um Properties objeto ou de um SQLServerDataSource. O driver remove as embalagens opcionais {...} nas três formas.

Os trechos de Java neste artigo omitem as importações e as declarações de classe por razões de brevidade.

Na URL JDBC

Cada regra (ou toda a lista de regras) deve ser envolta entre colchetes ({...}) porque a URL do JDBC usa ; como separador:

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

Com um objeto 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);

Com SQLServerDataSource

Os mesmos setters existem na ISQLServerDataSource interface:

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

Sintaxe das regras

Uma única regra tem até três secções separadas por dois pontos:

<errorNumbers> : <retryTimings> : <queryFilter>

Para usar várias regras na mesma propriedade, separe-as com ; e envolva cada regra com {...} ao colocá-las num URL JDBC.

Parâmetros de temporização

Para uma regra de declaração com temporizações retryCount, initialRetryTime <op> retryChange:

• retryCount: O número de tentativas adicionais que o condutor faz após a primeira falha. Um valor de 0 desativa a nova tentativa. Valores negativos são inválidos.
• initialRetryTime: O número de segundos a esperar antes da primeira tentativa novamente. O valor predefinido é 0.
• <op>: O operador, que pode ser + ou *. O valor predefinido é +.
• retryChange: O montante aplicado para calcular os tempos de espera subsequentes. O valor predefinido é 2. Quando o operando é * e retryChange é omitido da regra, o driver define retryChange = initialRetryTime.

O controlador calcula o tempo de espera para a tentativa n.º i (com base em 0) durante a análise:

Exemplos de cadeias de temporização:

Uma retryTimings secção pode conter, no máximo, uma vírgula. Mais de uma vírgula gera R_invalidParameterNumber.

Regras de nova tentativa de instruções (retryExec)

As regras da declaração repetem a execução falhada da declaração. Quando uma instrução lança um SQLServerException, o driver:

1. Procura o número do erro que causou a falha no conjunto de regras da instrução analisada.
2. Se existir uma regra e a contagem atual de tentativas for inferior a retryCount, opcionalmente verifica o último SQL executado contra o queryFilter.
3. Se tudo corresponder, o controlador espera waitTimes[retryAttempt] segundos (sujeito a queryTimeout, veja Interação com queryTimeout e connectRetryCount) e executa novamente a instrução.
4. Se nenhuma regra corresponder, o condutor relança a exceção.

Formato (declarações)

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

As regras da instrução devem incluir uma secção de temporizações. retryCount é obrigatório. Uma regra que contém apenas um número de erro é interpretada como uma regra de conexão , pelo que para instruções fornecem sempre pelo menos retryCount.

Exemplos (afirmações)

Listar vários números de erro (por exemplo, 1205,1222) é uma forma abreviada. O controlador expande a regra para uma entrada por erro, partilhando todas a mesma temporização e o mesmo filtro da consulta.

Regras de nova tentativa de ligação (retryConn)

As regras de conexão funcionam com o ciclo existente de tentativas de ligação. Este ciclo só está ativo quando connectRetryCount > 0 (o padrão é 1). O loop já tenta novamente uma lista predefinida de erros de ligação transitórios, com intervalos de connectRetryInterval segundos, até connectRetryCount tentativas adicionais, e está limitado por loginTimeout.

Uma regra de ligação inclui apenas uma secção com o número de erro. Não tem tempos nem filtro de consultas:

{[+]errorNumber(s)}

• Sem +, as regras configuradas substituem a lista de erros transitórios incorporada. Só os erros que mencionas são tentados novamente.
• Com + (por exemplo, {+4060}), as regras configuradas são adicionadas à lista incorporada. Tanto as suas tentativas falhadas como as predefinições do controlador são novamente tentadas.

O modo de substituir ou acrescentar é global para todo o valor retryConn. Se alguma regra nesse valor omitir +, o controlador muda para o modo de substituição para todas as regras nesse valor. Por exemplo, retryConn={+4060};{40143} não acrescenta 4060 e 40143 à lista incorporada. A 40143 regra omite +, por isso a lista incorporada é eliminada e apenas 4060 e 40143 são retentados. Para acrescentar ambos, escreva retryConn={+4060};{+40143} (ou retryConn={+4060,40143}).

O loop de ligação continua a usar connectRetryInterval e connectRetryCount para ritmo e saltos de ritmo. A regra CRL expande ou substitui o conjunto de erros passíveis de nova tentativa.

Exemplos (ligações)

Lista de erros de ligação transitória incorporada

O loop connect-retry já tenta novamente os seguintes erros sem qualquer configuração CRL, desde que connectRetryCount > 0. Listar qualquer um destes erros numa regra retryConn com + não tem efeito (já estão abrangidos). Utilize a regra retryConn quando precisar de adicionar um erro que não consta desta lista, ou quando precisar de remover completamente a lista utilizando a forma no-+ replace.

A lista canónica do controlador é a TransientError enumeração que se encontra em SQLServerError.java. O texto da mensagem de erro provém de erros de ligação transitória do SQL do Azure. Erros ao nível da instrução (como deadlock victim 1205 ou lock-request timeout 1222) não estão nesta lista, porque o loop connect-retry só dispara durante a ligação inicial. Para tentar novamente esses erros, use uma retryExec regra.

Carregar regras de um ficheiro de propriedades

Se não definir retryExec ou retryConn na ligação, o CRL procura um ficheiro com o nome mssql-jdbc.properties junto do JAR do controlador no classpath. O ficheiro utiliza análise sintáctica básica key=value . Falas que começam com retryExec= ou retryConn= são captadas. Os valores utilizam a mesma sintaxe descrita neste artigo, separando ; múltiplas regras.

Use nomes de chaves exatos (retryExec e retryConn), sem espaço em branco inicial. O ficheiro não é analisado como um ficheiro completo de propriedades em Java. O condutor faz uma verificação literal startsWith em cada linha, por isso:

• As linhas que começam com # ou qualquer outro prefixo diferente de retryExec/retryConn são ignoradas.
• Linhas cuja chave começa apenas com retryExec ou retryConn (por exemplo, retryExec2=...) são tratadas como propriedade de correspondência e podem produzir erros de análise sintática. Não introduza variantes personalizadas.

Exemplo mssql-jdbc.properties:

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

Se o ficheiro estiver em falta, o CRL regista uma mensagem FINE no registador com.microsoft.sqlserver.jdbc.ConfigurableRetryLogic e continua sem regras. O caminho do ficheiro usado para a pesquisa está incluído nessa mensagem de registo.

Os valores das cadeias de ligação têm prioridade. Se retryExec ou retryConn não estiverem vazios na conexão, o controlador não consulta o ficheiro para essa propriedade.

Comportamento de atualização de regras

O CRL mantém um único conjunto de regras para toda a JVM. Após a construção, o condutor atualiza as regras de forma preguiçosa:

• O controlador avalia as oportunidades para atualização durante a execução da instrução e as novas tentativas de ligação.
• A atualização só acontece depois de 30 segundos desde a leitura anterior.
• Se as regras vieram originalmente de mssql-jdbc.properties, o driver compara a marca temporal da última modificação do ficheiro com a marca temporal que registou na leitura anterior. Se o ficheiro mudou, o condutor corrige-o.
• Se as regras vieram originalmente de uma cadeia de ligação, o driver reaplica o valor de connection-string previamente armazenado.

Este comportamento significa que as edições em mssql-jdbc.properties são detetadas automaticamente ao fim de cerca de 30 segundos, sem ser necessário reiniciar a aplicação.

Interação com QueryTimeout e connectRetryCount

Repetições de instruções e queryTimeout

Quando uma regra de instrução é acionada, o controlador compara o próximo tempo de espera com o valor de queryTimeout ao nível da ligação:

• Se queryTimeout >= 0etimeToWait > queryTimeout, o controlador gera R_InvalidRetryInterval em vez de tentar novamente. O driver não relança o erro original. Gera o erro de configuração.
• A propriedade de ligação queryTimeout tem como valor predefinido -1, pelo que, por predefinição, a comparação é ignorada e qualquer período de espera é permitido.
• A definição queryTimeout=0não desativa esta verificação, porque 0 >= 0 é verdadeira. Qualquer timeToWait > 0 aumenta R_InvalidRetryInterval.

Quando definir queryTimeout para um valor positivo, mantenha o valor initialRetryTime + (retryCount - 1) * retryChange (aditivo) ou initialRetryTime * retryChange^(retryCount-1) (multiplicativo) abaixo desse valor.

Repetições de tentativa de conexão e connectRetryCount e loginTimeout

retryConn não ativa, por si só, tentativas de autenticação. As propriedades existentes mantêm-se sob controlo:

• connectRetryCount (padrão 1, intervalo 0-255) é o número de tentativas adicionais de autenticação. Defina-o como 0 para desativar as tentativas de autenticação. retryConn não tem efeito quando connectRetryCount = 0, porque o driver gera um erro à primeira falha.
• connectRetryInterval (padrão 10 segundos, alcance 1-60) é a espera entre tentativas. A primeira nova tentativa é executada imediatamente.
• loginTimeout é o limite global. O controlador desiste antecipadamente se o intervalo seguinte fizer com que o tempo decorrido ultrapasse loginTimeout.

Para mais informações, consulte Resiliência de Ligação (JDBC).

Exemplos

Lidar com impasses e expiração do tempo de bloqueio durante as operações de escrita

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

Até quatro tentativas para vítima de deadlock (1205) ou tempo limite de bloqueio (1222), com backoff de 2, 4, 8 e 16 segundos, mas apenas para instruções de escrita.

Executar novamente a criação do esquema durante operações em linha

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

Tenta novamente o erro 2714 (object already exists) e 3702 (cannot drop database currently in use) duas vezes cada, com espera de 1 e 2 segundos.

Adicionar um erro personalizado à lista de erros transitórios

retryConn={+<customErrorNumber>}

Adiciona um número de erro personalizado que ainda não está na lista incorporada. Se adicionares um erro transitório SQL do Azure incorporado, como 40197, 40501, 40613, 49918, 49919 ou 49920, nada muda porque o driver já tenta novamente.

Configurar CRL através de um ficheiro de propriedades

Coloque mssql-jdbc.properties junto ao ficheiro JAR do controlador:

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

Não definas retryExec nem retryConn na ligação. O controlador lê as regras do ficheiro e volta a lê-lo após cada modificação (verificada a cada 30 segundos).

Resolver problemas de CRL

Ative o registo FINE (ou mais detalhado) no registador com.microsoft.sqlserver.jdbc.ConfigurableRetryLogic para ver as tentativas de leitura de ficheiros e as decisões de análise:

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

Erros comuns de configuração:

Coisas a verificar quando uma regra não funciona:

1. A exceção SQLServerError.getErrorNumber() corresponde mesmo ao número da tua regra. O SQL Server pode enrolar algumas falhas em números diferentes dependendo do contexto (por exemplo, deadlock vs. timeout de bloqueio).
2. Para regras de instruções com , queryFiltero primeiro token delimitado por espaço em branco do SQL que executou (em minúscula) está na lista de filtros. Comentários e WITH CTEs modificam o primeiro token.
3. retryCount Retentativas são tentativas adicionais . A primeira execução não conta.
4. Nas regras de ligação, connectRetryCount é superior a 0 e loginTimeout deixa espaço para, pelo menos, mais um connectRetryInterval.
5. A regra tem a forma certa. As regras de extrato devem incluir uma secção de temporizações. As regras de ligação não devem ser.

Conteúdo relacionado

• Resiliência da ligação (JDBC)
• Compreender as propriedades de tempo limite no driver JDBC
• Definir as propriedades de ligação
• Diagnóstico de problemas com o driver JDBC