Driver JDBC da Microsoft para SQL Server

Baixar driver JDBC

O Microsoft Java Database Connectivity (JDBC) Driver para SQL Server é um driver JDBC Tipo 4 (Java puro, que comunica diretamente o protocolo TDS SQL Server, sem necessidade de bibliotecas nativas) que permite que qualquer aplicação ou servidor de aplicações Java se ligue a SQL Server, Base de Dados SQL do Azure, Azure SQL Managed Instance e base de dados SQL no Microsoft Fabric. Implementa as APIs padrão JDBC e trabalha com os principais servidores de aplicações Java, incluindo o IBM WebSphere e o SAP NetWeaver.

Escolhe o teu ponto de partida

• Para configurar um ambiente de desenvolvimento Java e executar a sua primeira consulta, comece pelo Passo 1: Configurar o ambiente de desenvolvimento, Passo 2: Criar uma base de dados SQL e Passo 3: Prova de conceito ligar a SQL usando Java.
• Para se ligar ao SQL do Azure com autenticação sem palavra-passe, comece por Connect usando autenticação Microsoft Entra e Construindo o URL da ligação.
• Para adicionar o driver a uma versão Maven, Gradle ou outra build, vá a Download Microsoft JDBC Driver for SQL Server.
• Para tornar uma aplicação existente resiliente a falhas transitórias, consulte Resiliência da ligação e Lógica de repetição configurável.
• Para diagnosticar um problema de ligação ou consulta, vá a Diagnosticar problemas com o driver JDBC e Solucionar problemas de conectividade.

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

Use este excerto como ponto de partida para uma ligação SQL do Azure orientada para produção. Carrega o nome do servidor e o nome da base de dados a partir da configuração da aplicação, como as definições da aplicação do Serviço de Aplicações do Azure, variáveis de ambiente ou um ficheiro de configuração, e define o resto das propriedades da ligação programaticamente. A configuração combina Segurança da Camada de Transporte (TLS), identidade gerida, novas tentativas de ligação em caso de falhas transitórias, recuperação rápida do grupo de failover, um tempo limite de início de sessão mais longo para abranger um failover após arranque a frio e lógica de repetição configurável (CRL) para instruções afetadas por limitação do SQL do Azure ou por failover a meio da consulta.

Para maior segurança e uma escalabilidade mais fácil, mantenha a informação de ligação fora do seu código. Em produção, armazene a informação de ligação no sistema de configuração da sua aplicação e use o Azure Key Vault para valores sensíveis e definições de ligação geridas centralmente. Para mais informações, veja Segurança de cadeias de ligação.

Os excertos em Java neste artigo omitem importações e wrappers de classe para maior 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 fragmento de código está otimizado para grupos de failover do Base de Dados SQL do Azure e o Azure SQL Managed Instance.

Defina multiSubnetFailover=true apenas quando estabelecer ligação ao listener de um grupo de failover, ao listener de um grupo de disponibilidade ou ao endpoint de uma instância de cluster de failover. A utilização desta propriedade em endpoints que não sejam listeners de alta disponibilidade (HA) pode prejudicar o desempenho e não é suportada. Para mais informações, consulte suporte do controlador JDBC para alta disponibilidade e recuperação após desastre.

O excerto não define retryConn porque o controlador já repete automaticamente a tentativa nos erros transitórios de ligação ao SQL do Azure mais comuns (incluindo 4060, 40197, 40501, 40613, 49918, 49919, 49920, 10928 e 10929) por predefinição, condicionado por connectRetryCount e connectRetryInterval. Para a lista completa, veja Lista de erros de ligação transitória incorporada. Adicione retryConn com +<errorNumber> apenas quando precisar de estender a lista com um erro que ainda não esteja abrangido, ou defina-o como <errorNumber> (sem + inicial) para o substituir. Se colocar o mesmo valor num URL JDBC, encapsule-o como retryConn={+<errorNumber>} ou retryConn={<errorNumber>}.

A retryExec propriedade tem duas partes, escritas como rule1;rule2 quando a defines programaticamente. Se colocar o mesmo valor numa URL JDBC, enrole cada regra em colchetes como {rule1};{rule2}:

• {1205,1222:3,5+5} repete vítimas de impasse (1205) e expirações do pedido de bloqueio (1222) três vezes, com um intervalo de espera linear de 5, 10 e 15 segundos. Para o 1205, o SQL Server reverte a transação antes que o driver deteça o erro, por isso é seguro reexecutar uma única instrução. Se a instrução que entrou em impasse fizesse parte de uma transação com várias instruções, as instruções anteriores também eram revertidas e o CRL não as volta a executar, por isso envolva toda a transação na sua própria lógica de repetição. 1222 deixa a transação aberta e a nova tentativa ao nível da instrução apenas reexecuta a instrução dentro da transação original; se também for necessário limitar a duração da transação, envolva a transação completa num ciclo de nova tentativa próprio.

• {40501,40613,40197,10928,10929,49918:4,5*2} repete as tentativas em caso de limitação da taxa no SQL do Azure, ativação pós-falha a meio da consulta e erros de limite de recursos, quatro vezes, com um intervalo de espera exponencial de 5, 10, 20 e 40 segundos. Estes erros constam da lista integrada de erros transitórios para o ciclo connect, mas retryExec é o que os deteta quando ocorrem a meio de uma consulta numa ligação já estabelecida. Os backoffs CRL são limitados por queryTimeout. Se definires queryTimeout como inferior ao tempo de espera planeado seguinte, o controlador desiste prematuramente e lança novamente. Escolhe um queryTimeout que seja pelo menos tão grande quanto o total das tuas esperas CRL mais o tempo de execução da instrução, ou aceita que os backoffs mais longos não vão disparar.

Para grupos de failover do Base de Dados SQL do Azure, réplicas com nome do Hyperscale e expansão horizontal de leitura, ou os listeners de grupos de disponibilidade Always On, defina applicationIntent=ReadOnly quando quiser ligar-se a um secundário legível. Para nuvens soberanas em que o Subject Alternative Name (SAN) do certificado não inclui o anfitrião ao qual se está a ligar, configure também hostNameInCertificate para corresponder (por exemplo, *.database.usgovcloudapi.net para o Azure Government).

Para mais informações sobre cada parte desta configuração, veja:

• Construir o URL de ligação
• Definir as propriedades de ligação
• Conectar usando a autenticação do Microsoft Entra
• Resiliência da ligação
• Lógica de repetição de tentativas configurável
• Suporte de driver JDBC para Alta Disponibilidade e recuperação em caso de desastres
• Compreender as propriedades de tempo limite no driver JDBC

Para o catálogo de erros transientes do SQL do Azure, veja Solucionar erros de ligação transitória.

Principais características

• JDBC baseado em normas: controlador de tipo 4. A build do JRE 11+ implementa o JDBC 4.2 mais os métodos de fronteira de pedido do JDBC 4.3 (beginRequest, endRequest) e Statement ajudantes de citação. As APIs de sharding do JDBC 4.3 (setShardingKey, a família createConnectionBuilder) lançam SQLFeatureNotSupportedException. A versão do JRE 8 implementa o JDBC 4.2. Para a análise por versão e a lista completa de métodos 4.3 suportados e não suportados, veja suporte à especificação Java e JDBC.
• Suporte a plataforma ampla: Funciona em qualquer plataforma com uma Máquina Virtual Java (JVM) suportada, incluindo Windows, Linux e macOS.
• Encriptado por predefinição: ligações TLS encriptadas, com encrypt=true por predefinição para os controladores atuais.
• Autenticação Microsoft Entra ID: Ligações sem palavra-passe com identidade gerida, principal de serviço, fluxos interativos e integrados, cadeia de credenciais predefinida e fluxos de token de acesso.
• Kerberos: Autenticação integrada para Active Directory no local.
• NTLM: Autenticação por desafio-resposta do Windows para cenários sem domínio ou legados.
• Always Encrypted: Encriptação 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 débito com a SQLServerBulkCopy API 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 opcionalmente configurável para instruções (retryExec) e uma lista personalizável de erros de conexão (retryConn).
• Suporte a tipos de dados SQL Server ricos: datatimeoffset, sql_variant, JSON, espaciais, vetoriais, parâmetros de tabela e tipos definidos pelo utilizador.

Introdução

Configurar e ligar

Authenticate

Secure

Trabalhar com dados

Tipos de dados

Transações e simultaneidade

Desempenho e fiabilidade

Diagnosticar e solucionar problemas

Tarefas relacionadas

Conteúdo relacionado

• Driver Microsoft JDBC para SQL Server no GitHub
• Controlador JDBC da Microsoft para SQL Server no Maven Central
• Notas de atualização para o driver Microsoft JDBC para SQL Server
• Encontrar informações adicionais sobre condutores JDBC
• Módulos de conexão para o Banco de Dados Microsoft SQL