Microsoft JDBC Driver para SQL Server

Baixar o JDBC Driver

O driver JDBC (Conectividade de Banco de Dados Microsoft Java) para SQL Server é um driver JDBC tipo 4 (Java puro, fala diretamente do protocolo TDS SQL Server, sem bibliotecas nativas necessárias) que permite que qualquer Java aplicativo ou servidor de aplicativos se conecte ao SQL Server, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure e banco de dados SQL no Microsoft Fabric. Ele implementa as APIs JDBC padrão e funciona com os principais servidores de aplicativos Java, incluindo IBM WebSphere e SAP NetWeaver.

Escolha o ponto de partida

• Para configurar um ambiente de desenvolvimento Java e executar sua primeira consulta, comece com a Etapa 1: Configurar o ambiente de desenvolvimento, etapa 2: criar um banco de dados SQL e a Etapa 3: Prova de conceito conectando-se ao SQL usando Java.
• Para se conectar ao SQL do Azure com autenticação sem senha, comece com Conectar-se usando a autenticação do Microsoft Entra e Criar a URL de conexão.
• Para adicionar o driver a um Maven, Gradle ou outra compilação, acesse Baixar Microsoft JDBC Driver para SQL Server.
• Para tornar um aplicativo existente resiliente a falhas transitórias, vá para resiliência de conexão e lógica de repetição configurável.
• Para diagnosticar um problema de conexão ou consulta, acesse Diagnosticar problemas com o driver JDBC e solucionar problemas de conectividade.

Linha de base de produção para SQL do Azure

Use esse snippet como ponto de partida para uma conexão de SQL do Azure orientada à produção. O sistema carrega o nome do servidor e o nome do banco de dados da configuração do aplicativo, como as configurações do aplicativo do Serviço de Aplicativo do Azure, as variáveis de ambiente ou um arquivo de configuração, e define programaticamente o restante das propriedades da conexão. A configuração combina Transport Layer Security (TLS), identidade gerenciada, novas tentativas de conexão em falhas transitórias, recuperação rápida do grupo de failover, um tempo limite de login mais longo para cobrir um failover de inicialização a frio e lógica configurável de repetição (CRL) para instruções SQL que sofrem limitação no SQL do Azure ou failover no meio da consulta.

Para maior segurança e expansão mais fácil, mantenha as informações de conexão fora do código. Em produção, armazene informações de conexão no sistema de configuração do aplicativo e use Azure Key Vault para valores confidenciais e configurações de conexão gerenciadas centralmente. Para obter mais informações, consulte Proteção de cadeias de conexão.

Neste artigo, os trechos de código Java omitem importações e declarações de classe para fins de brevidade.

// Load endpoint details from application configuration. In Azure App Service,
// these can come from app settings or Key Vault-backed settings.
String serverName = System.getenv("SQL_SERVER_NAME");
String databaseName = System.getenv("SQL_DATABASE_NAME");
String port = System.getenv().getOrDefault("SQL_PORT", "1433");

if (serverName == null || databaseName == null) {
    throw new IllegalStateException(
            "Set SQL_SERVER_NAME and SQL_DATABASE_NAME in your application configuration.");
}

String url = "jdbc:sqlserver://" + serverName + ":" + port;

Properties props = new Properties();
props.setProperty("databaseName", databaseName);
props.setProperty("encrypt", "true");
props.setProperty("trustServerCertificate", "false");
props.setProperty("authentication", "ActiveDirectoryManagedIdentity");
props.setProperty("loginTimeout", "120");         // 90 is the minimum floor for this retry profile; 120 leaves practical failover margin
props.setProperty("connectRetryCount", "5");     // retry transient connection failures up to 5 times (default 1)
props.setProperty("connectRetryInterval", "15"); // 15 seconds between connection retries (default 10)
props.setProperty("multiSubnetFailover", "true"); // recommended for any Azure SQL HA listener
// props.setProperty("applicationIntent", "ReadOnly"); // uncomment to route to a readable secondary
// Retry deadlocks and lock timeouts, plus Azure SQL throttling and mid-query failover.
props.setProperty("retryExec", "1205,1222:3,5+5;40501,40613,40197,10928,10929,49918:4,5*2");

try (Connection conn = DriverManager.getConnection(url, props);
     Statement stmt = conn.createStatement();
     ResultSet rs = stmt.executeQuery("SELECT 1")) {
    while (rs.next()) {
        System.out.println(rs.getInt(1));
    }
}

Este trecho de código foi ajustado para grupos de failover do Banco de Dados SQL do Azure e para o Instância Gerenciada de SQL do Azure.

Defina multiSubnetFailover=true somente quando você se conectar a um ouvinte de grupo de failover, ouvinte de grupo de disponibilidade ou ponto de extremidade da instância do cluster de failover. O uso dessa propriedade em relação a pontos de extremidade que não são ouvintes de alta disponibilidade (HA) pode prejudicar o desempenho e não tem suporte. Para obter mais informações, consulte o suporte ao driver JDBC para alta disponibilidade e recuperação de desastre.

O snippet não define retryConn porque o driver já faz novas tentativas automaticamente para os erros transitórios de conexão mais comuns do SQL do Azure (incluindo 4060, 40197, 40501, 40613, 49918, 49919, 49920, 10928 e 10929) por padrão, condicionado por connectRetryCount e connectRetryInterval. Para obter a lista completa, consulte a lista de erros de conexão transitória interna. Adicione retryConn com +<errorNumber> somente quando precisar estender a lista com um erro que ainda não esteja coberto, ou defina-o como <errorNumber> (sem + no início) para substituí-lo. Se você colocar o mesmo valor em uma URL JDBC, embrulhe-o como retryConn={+<errorNumber>} ou retryConn={<errorNumber>}.

A retryExec propriedade tem duas partes, escritas como rule1;rule2 quando você a define programaticamente. Se você inserir o mesmo valor em uma URL JDBC, coloque cada regra entre chaves, como em {rule1};{rule2}:

• {1205,1222:3,5+5} tenta novamente três vezes em caso de vítimas de deadlock (1205) e tempos limite de solicitação de bloqueio (1222), com um recuo linear de 5, 10 e 15 segundos. Para 1205, SQL Server reverte a transação antes que o driver veja o erro, portanto, executar novamente uma única instrução é seguro. Se a instrução que entrou em deadlock fazia parte de uma transação com múltiplas instruções, as instruções anteriores também foram revertidas, e a CRL não as reexecuta; portanto, coloque toda a transação em seu próprio loop de nova tentativa. 1222 deixa a transação aberta, e a nova tentativa no nível da instrução apenas reexecuta a instrução dentro da transação original; se você também precisar limitar a duração da transação, coloque a transação inteira em seu próprio loop de nova tentativa.

• {40501,40613,40197,10928,10929,49918:4,5*2} tenta novamente quatro vezes em caso de limitação de taxa do SQL do Azure, failover no meio da consulta e erros de limite de recursos, com um recuo exponencial de 5, 10, 20 e 40 segundos. Esses erros estão na lista interna de erros transitórios do loop connect, mas retryExec é quem os captura quando ocorrem no meio de uma consulta em uma conexão já estabelecida. Os intervalos de espera da CRL são limitados por queryTimeout. Se você definir queryTimeout abaixo da próxima espera planejada, o driver desiste antes e a relança. Escolha um queryTimeout que seja pelo menos tão grande quanto o total de esperas de CRL mais o runtime da instrução ou aceite que as retiradas mais longas não serão disparadas.

Para grupos de failover do Banco de Dados SQL do Azure, réplicas nomeadas do Hyperscale e scale-out de leitura, ou ouvintes de grupos de disponibilidade Always On, defina applicationIntent=ReadOnly quando quiser ser direcionado a uma réplica secundária legível. Para nuvens soberanas em que o SAN (Nome Alternativo do Assunto do certificado) não inclui o host ao qual você está se conectando, também defina hostNameInCertificate para corresponder a ele (por exemplo, *.database.usgovcloudapi.net para o Azure Governamental).

Para obter mais informações sobre cada parte dessa configuração, consulte:

• Construindo a URL de conexão
• Definir as propriedades de conexão
• Conectar-se usando a autenticação do Microsoft Entra
• Resiliência de conexão
• Lógica de repetição configurável
• Suporte a JDBC Driver para alta disponibilidade e recuperação de desastre
• Noções básicas sobre as propriedades de tempo limite no driver JDBC

Para o catálogo de erros transitórios do SQL do Azure, consulte Solucionar problemas de erros de conexão transitórios.

Características principais

• JDBC baseado em padrões: driver tipo 4. O build do JRE 11+ implementa o JDBC 4.2, além dos métodos de limite de solicitação do JDBC 4.3 (beginRequest, endRequest) e dos auxiliares de aspas Statement. As APIs de sharding do JDBC 4.3 (setShardingKey, a família createConnectionBuilder) lançam SQLFeatureNotSupportedException. O build do JRE 8 implementa o JDBC 4.2. Para obter a divisão por versão e a lista completa de métodos 4.3 compatíveis e sem suporte, consulte Java e suporte à especificação JDBC.
• Suporte à plataforma ampla: é executado em qualquer plataforma com uma JVM (Máquina Virtual) Java com suporte, incluindo Windows, Linux e macOS.
• Criptografado por padrão: conexões criptografadas com TLS, com encrypt=true como padrão para drivers atuais.
• Autenticação do Microsoft Entra ID: conexões sem senha com identidade gerenciada, entidade de serviço e fluxos interativo, integrado, de cadeia de credenciais padrão e de token de acesso.
• Kerberos: autenticação integrada para Active Directory local.
• NTLM: autenticação de desafio/resposta do Windows para cenários sem domínio ou herdados.
• Always Encrypted: criptografia do lado do cliente para colunas sensíveis, com enclaves seguros opcionais para operações no local.
• Cópia em massa: inserções de alto desempenho com a API SQLServerBulkCopy e desempenho de inserção em lote para executeBatch.
• Resiliência da conexão: novas tentativas de conexão integradas para erros transitórios, além de lógica de repetição configurável e opcional para instruções (retryExec) e uma lista de erros de conexão personalizável (retryConn).
• Amplo suporte a tipos de dados do SQL Server: datetimeoffset, sql_variant, JSON, dados espaciais, vetores, parâmetros com valor de tabela e tipos definidos pelo usuário.

Introdução

Configuração e conexão

Authenticate

Secure

Trabalhar com dados

Tipos de dados

Transações e simultaneidade

Desempenho e confiabilidade

Diagnosticar e solucionar problemas

Tarefas relacionadas

Conteúdo relacionado

• Driver JDBC da Microsoft para SQL Server no GitHub
• Microsoft JDBC Driver for SQL Server no Maven Central
• Notas de versão do Microsoft JDBC Driver para SQL Server
• Informações adicionais sobre o driver JDBC
• módulos de conexão para o Banco de Dados SQL da Microsoft