Lógica de repetição configurável (JDBC)

Baixar JDBC Driver

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 conexão com base nos números de erro do SQL Server que você escolher, com parâmetros de temporização que você controla. A CRL foi introduzida no Microsoft JDBC Driver 12.10 para SQL Server.

CRL é separada da resiliência de conexão inativa e das propriedades connectRetryCount / connectRetryInterval. A resiliência em inatividade recupera de forma transparente conexões interrompidas, e connectRetryCount tenta novamente a autenticação inicial em intervalos fixos para uma lista incorporada de erros transitórios. A CRL permite que você decida quais erros são repetíveis, quantas vezes e quanto tempo aguardar entre as tentativas. Você pode usar os três mecanismos juntos.

Quais novas tentativas de CRL

A CRL lida com dois cenários distintos, cada um controlado por sua própria propriedade de conexão:

Para instruções, o driver tenta novamente apenas o comando que falhou. O driver não reinicializa o estado atual da transação, portanto, defina suas regras considerando erros que mantêm a sessão utilizável, como vítima de deadlock (1205) ou tempo limite de bloqueio (1222).

Para conexões, a CRL complementa ou substitui a lista interna do driver de erros transitórios de conexão. Consulte as regras de nova tentativa de conexão para a semântica do prefixo +.

Habilitar CRL

A CRL tem duas camadas:

1. A camada de repetição de conexão é ativada por padrão: desde que connectRetryCount > 0 (o padrão é 1), o driver tenta novamente a lista interna de erros transitórios de conexão.
2. A camada de personalização (sua própria retryExec e retryConn regras) está desativada por padrão. Ambas as propriedades são cadeias de caracteres vazias, a menos que você as defina. Você pode defini-los por meio da URL JDBC, um Properties objeto ou um SQLServerDataSource. O driver remove os wrappers opcionais {...} em todas as três formas.

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

Na URL JDBC

Cada regra (ou toda a lista de regras) deve ser encapsulada em chaves ({...}) porque a URL 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 de regra

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

<errorNumbers> : <retryTimings> : <queryFilter>

Para usar várias regras na mesma propriedade, separe-as com ; e coloque cada regra entre {...} ao inseri-las em uma URL JDBC.

Parâmetros de tempo

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

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

O driver calcula o tempo de espera da tentativa i (indexada em 0) durante a análise:

Exemplos de cadeias de tempo:

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

Regras de nova tentativa da instrução (retryExec)

As regras de instrução tentam novamente a execução da instrução com falha. 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 de tentativas atual for menor do que retryCount, opcionalmente, verificará o ÚLTIMO SQL executado em relação ao da queryFilterregra.
3. Se tudo estiver de acordo, o driver aguardará waitTimes[retryAttempt] segundos (sujeito a queryTimeout; consulte Interação com queryTimeout e connectRetryCount) e executará a instrução novamente.
4. Se nenhuma regra corresponder, o driver lançará novamente a exceção.

Formato (declarações)

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

As regras de declaração devem incluir uma seção de temporização. retryCount é obrigatório. Uma regra que contém apenas um número de erro é interpretada como uma regra de conexão, portanto, em instruções, sempre forneça pelo menos retryCount.

Exemplos (instruções)

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

Regras de repetição de conexão (retryConn)

As regras de conexão funcionam com o loop existente de tentativas de reconexão. Esse loop só está ativo quando connectRetryCount > 0 (o padrão é 1). O loop já tenta novamente uma lista interna de erros transitórios de conexão com connectRetryInterval segundos de diferença, até connectRetryCount tentativas extras e é limitado por loginTimeout.

Uma regra de conexão fornece apenas uma seção de número de erro. Ele não tem intervalos ou filtro de consulta:

{[+]errorNumber(s)}

• Sem +, as regras configuradas substituem a lista de erros transitórios interna. Somente os erros listados são repetidos.
• Com + (por exemplo, {+4060}), as regras configuradas são adicionadas à lista interna. Tanto os seus erros quanto as configurações padrão do driver são tentados novamente.

O modo de substituir ou acrescentar é global para todo o valor retryConn. Se qualquer regra nesse valor omitir +, o driver passa para o modo de substituição para todas as regras nesse valor. Por exemplo, retryConn={+4060};{40143} não acrescenta 4060 e 40143 à lista interna. A regra 40143 omite +, portanto a lista interna é descartada e apenas 4060 e 40143 são tentadas novamente. Para acrescentar ambos, gravar retryConn={+4060};{+40143} (ou retryConn={+4060,40143}).

O loop de conexão continua usando connectRetryInterval e connectRetryCount para cadenciamento e delimitação. A regra de CRL expande ou substitui o conjunto de erros elegíveis para nova tentativa.

Exemplos (conexões)

Lista integrada de erros transitórios de conexão

O loop de nova tentativa de conexão já repete os seguintes erros sem qualquer configuração de CRL, contanto que connectRetryCount > 0. Listar qualquer desses erros em uma regra retryConn com + não tem efeito (eles já estão abordados). Use uma regra retryConn quando precisar adicionar um erro que não está nesta lista ou quando precisar descartar a lista por completo usando a forma sem + substituição.

A lista canônica do driver é a TransientError enum em SQLServerError.java. O texto da mensagem de erro vem de erros transitórios de conexão do SQL do Azure. Os erros no nível de instrução (como o erro 1205 de vítima de deadlock ou o erro 1222 de tempo limite de solicitação de bloqueio) não estão nesta lista, porque o loop de nova tentativa de conexão só é executado durante a conexão inicial. Para repetir esses erros, use uma retryExec regra.

Carregar regras de um arquivo de propriedades

Se você não definir retryExec ou retryConn na conexão, o CRL procurará um arquivo chamado mssql-jdbc.properties ao lado do JAR do driver no classpath. O arquivo usa análise sintática básica key=value. Linhas que começam com retryExec= ou retryConn= são identificadas. Os valores usam a mesma sintaxe descrita neste artigo, com ; separando várias regras.

Use nomes de chave exatos (retryExec e retryConn), sem espaço em branco à esquerda. O arquivo não é analisado como um arquivo de propriedades de Java completo. O driver faz uma verificação literal startsWith em cada linha, portanto:

• As linhas que começam com # ou qualquer outro nãoretryExec/retryConn prefixo são ignoradas.
• As linhas cuja chave só começa com retryExec ou retryConn (por exemplo, retryExec2=...) são tratadas como a propriedade correspondente e podem produzir erros de análise. Não introduza variantes personalizadas.

Exemplo mssql-jdbc.properties:

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

Se o arquivo não for encontrado, a CRL registrará uma mensagem FINE no logger com.microsoft.sqlserver.jdbc.ConfigurableRetryLogic e continuará sem regras. O caminho do arquivo usado para a pesquisa está incluído nessa mensagem de log.

Os valores da cadeia de conexão têm precedência. Se retryExec ou retryConn não estiverem vazios na conexão, o driver não consultará o arquivo para essa propriedade.

Comportamento de atualização de regra

A CRL mantém um único conjunto de regras em toda a JVM. Após a construção, o driver atualizará as regras lentamente:

• O driver avalia as oportunidades de atualização durante a execução da instrução e as novas tentativas de conexão.
• Uma atualização só ocorre após 30 segundos decorridos desde a leitura anterior.
• Se as regras vieram originalmente de mssql-jdbc.properties, o driver comparará o carimbo de data/hora da última modificação do arquivo com o carimbo de data/hora que ele registrou na leitura anterior. Se o arquivo foi alterado, o driver o analisa novamente.
• Se as regras vieram originalmente de uma string de conexão, o driver reaplica o valor da string de conexão armazenado anteriormente.

Esse comportamento significa que edições em mssql-jdbc.properties são detectadas automaticamente em cerca de 30 segundos, sem reiniciar o aplicativo.

Interação com queryTimeout e connectRetryCount

Novas tentativas de declaração e queryTimeout

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

• Se queryTimeout >= 0etimeToWait > queryTimeout, o driver vai gerar R_InvalidRetryInterval em vez de repetir a tentativa. O driver não lança novamente o erro original. Ele gera o erro de configuração.
• A queryTimeout propriedade de conexão usa -1como padrão, portanto, por padrão, a comparação é ignorada e qualquer espera é permitida.
• Definir queryTimeout=0não desabilita essa verificação, porque 0 >= 0 é verdadeiro. Qualquer timeToWait > 0 gera R_InvalidRetryInterval.

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

Tentativas de conexão e connectRetryCount e loginTimeout

retryConn por si só, não permite novas tentativas de autenticação. As propriedades existentes continuam responsáveis:

• connectRetryCount (padrão 1, intervalo de 0 a 255) é o número de tentativas de autenticação extras. Defina-o como 0 para desabilitar as tentativas de repetição de autenticação. retryConn não tem efeito quando connectRetryCount = 0, porque o driver lança uma exceção na primeira falha.
• connectRetryInterval (padrão de 10 segundos, intervalo de 1 a 60) é a espera entre tentativas. A primeira repetição é executada imediatamente.
• loginTimeout é o limite geral. O driver interrompe antecipadamente se o próximo intervalo fizer com que o tempo decorrido ultrapasse loginTimeout.

Para obter mais informações, consulte A resiliência de conexão (JDBC).

Exemplos

Lidar com impasses e limites de tempo de bloqueio durante gravações

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

Até quatro novas tentativas para deadlock victim (1205) ou tempo limite de bloqueio (1222), com intervalos de espera de 2, 4, 8 e 16 segundos, mas apenas para instruções de escrita.

Executar novamente a criação de esquema em operações online

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

Repete o erro 2714 (object already exists) e 3702 (cannot drop database currently in use) duas vezes cada, com esperas 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 interna. Se você acrescentar um erro interno SQL do Azure transitório, como 40197, 40501, 40613, 49918, 49919 ou 49920, nada mudará porque o driver já o tenta novamente.

Configurar CRL por meio de um arquivo de propriedades

Coloque mssql-jdbc.properties ao lado do arquivo JAR do driver:

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

Não defina retryExec ou retryConn na conexão. O driver lê as regras do arquivo e as relê após cada modificação (verificado uma vez a cada 30 segundos).

Solucionar problemas de CRL

Habilite o log FINE (ou mais detalhado) no logger com.microsoft.sqlserver.jdbc.ConfigurableRetryLogic para ver as tentativas de leitura de arquivos e as decisões de processamento:

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

Erros comuns de configuração:

Itens a verificar quando uma regra não é acionada:

1. A exceção SQLServerError.getErrorNumber() corresponde, na verdade, ao número em sua regra. SQL Server pode encapsular algumas falhas em números diferentes dependendo do contexto (por exemplo, deadlock versus tempo limite de bloqueio).
2. Para regras de instrução com um queryFilter, o primeiro token delimitado por espaço em branco do SQL que você executou (convertido para minúsculas) está na lista de filtros. Comentários e WITH CTEs alteram o primeiro token.
3. retryCount novas tentativas são tentativas adicionais. A primeira execução não conta.
4. Para as regras de conexão, connectRetryCount é maior do que 0 e loginTimeout permite pelo menos mais um connectRetryInterval.
5. A regra tem a forma certa. As regras de declaração precisam de uma seção de temporizações. As regras de conexão não devem.

Conteúdo relacionado

• Resiliência de conexão (JDBC)
• Noções básicas sobre as propriedades de tempo limite no driver JDBC
• Definir as propriedades de conexão
• Diagnosticando problemas com o JDBC Driver