Início rápido: Conecte-se ao SQL Server com Java e Maven

Use o driver JDBC da Microsoft para SQL Server para conectar um aplicativo Java ao SQL Server, ao Banco de Dados SQL do Azure ou ao banco de dados SQL no Fabric. Esse quickstart usa o Maven para baixar dependências, lê configurações de conexão a partir de variáveis do ambiente e verifica um resultado de consulta parametrizado. Você não precisa do AdventureWorks nem de tabelas de exemplo.

Para o Banco de Dados SQL do Azure ou o SQL Database no Fabric, use a autenticação do Microsoft Entra ID sem armazenar uma senha no seu aplicativo. Durante o desenvolvimento local, faça login pelo navegador. Para uma aplicação hospedada no Azure, use uma identidade gerenciada.

Prerequisites

• Kit de Desenvolvimento Java (JDK) 21. Verifique sua instalação com java -version.
• Apache Maven. Corra mvn -version e confirme que Maven usa JDK 21.
• Um banco de dados e permissão para se conectar a ele. Escolha um banco de dados hospedado ou um contêiner do SQL Server em Escolha seu banco de dados. A consulta lê um valor calculado e não cria nem modifica objetos de banco de dados.
• Acesso em rede ao seu endpoint de banco de dados. Para SQL do Azure, configure o acesso à rede. Para o Fabric, siga Conectar-se ao seu banco de dados SQL. Para SQL Server, ative o Protocolo de Controle de Transmissão/Protocolo de Internet (TCP/IP) e use a porta configurada.
• Um certificado de servidor no qual seu runtime Java confia. A aplicação requer criptografia e valida o certificado do servidor. Para uma autoridade certificadora privada, siga as instruções em Confiar em uma autoridade certificadora privada.

Escolha seu banco de dados

Use um banco de dados existente ou crie um utilizando os seguintes guias. Um banco de dados vazio é suficiente.

Imagens de contêineres Linux do SQL Server requerem um host x86-64 suportado. Em um computador de desenvolvimento ARM64, execute esse aplicativo Java em um banco de dados hospedado ou em um contêiner em um host remoto suportado, em vez de depender da emulação de contêiner.

Um novo container pode usar um certificado no qual seu JDK não confia. Antes de executar este exemplo, configure um certificado de servidor e, para um emissor privado, configure o armazenamento de confiança Java. Mantenha a validação de certificados ativada para conexões de contêineres também.

Crie o projeto Maven

Crie um diretório com o nome jdbc-quickstart. Nesse diretório, crie pom.xml com o seguinte conteúdo. O Maven gerencia o caminho da classe; você não precisa baixar arquivos Java (JAR) manualmente.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>jdbc-quickstart</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.release>21</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.microsoft.sqlserver</groupId>
            <artifactId>mssql-jdbc</artifactId>
            <version>13.6.0.jre11</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-core-http-netty</artifactId>
            <version>1.16.6</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.18.4</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.14.0</version>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.5.0</version>
                <configuration>
                    <executable>${java.home}/bin/java</executable>
                    <arguments>
                        <argument>-classpath</argument>
                        <classpath />
                        <argument>Quickstart</argument>
                    </arguments>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

O artefato do driver jre11 funciona com o JDK 21. A dependência explícita azure-identity fornece as bibliotecas de autenticação necessárias para os modos Microsoft Entra neste quickstart; essas bibliotecas são dependências opcionais do driver e não são adicionadas automaticamente à sua aplicação.

Essas versões correspondem ao modelo de objetos de projeto Maven (POM) publicado no JDBC 13.6.0. A dependência azure-core-http-netty explícita mantém a versão de transporte selecionada por essa versão do driver.

Para atualizações de drivers, confira a página de download, as versões publicadas do Maven e a matriz de suporte ao Java. Quando você atualiza o driver, compare as dependências de autenticação com o POM publicado pelo driver. Consulte Dependências de recursos. Use versões de lançamento específicas em vez de intervalos de versões do Maven ou LATEST.

Configurar a conexão

Defina as variáveis de ambiente no mesmo terminal onde você roda o Maven. Substitua <server> e <database> com o nome do seu endpoint e banco de dados. Defina SQL_SERVER_NAME como apenas o nome do host, sem uma URL JDBC ou porta.

Se o valor do servidor copiado for tcp:<server>,1433, use apenas <server> para SQL_SERVER_NAME e defina SQL_PORT para 1433. Não inclua o tcp: prefixo ou ,1433 sufixo no nome do host.

SQL do Azure ou Fabric com autenticação Microsoft Entra

Para desenvolvimento local, use ActiveDirectoryInteractive. O driver abre um navegador para login e suporta autenticação multifator. Faça login com a identidade que tem acesso ao seu banco de dados. Não defina SQL_USER ou SQL_PASSWORD para este modo.

Para Banco de Dados SQL do Azure, substitua <server> pelo nome completo do host, como contoso.database.windows.net. Para o Fabric, copie o nome do host das configurações de conexão do banco de dados SQL; não construa a partir do nome do banco nem adicione um sufixo SQL do Azure. Fabric exige autenticação Microsoft Entra; não use o exemplo de autenticação SQL para Fabric.

$env:SQL_SERVER_NAME = "<server>"
$env:SQL_DATABASE_NAME = "<database>"
$env:SQL_PORT = "1433"
$env:SQL_AUTHENTICATION = "ActiveDirectoryInteractive"

export SQL_SERVER_NAME="<server>"
export SQL_DATABASE_NAME="<database>"
export SQL_PORT="1433"
export SQL_AUTHENTICATION="ActiveDirectoryInteractive"

Para uma aplicação headless hospedada em um recurso Azure com uma identidade gerenciada atribuída pelo sistema:

1. Ative a identidade gerenciada do recurso.
2. Peça ao seu administrador para conceder a essa identidade acesso ao banco de dados. Para SQL do Azure, crie um usuário de banco de dados para a identidade. No Fabric, siga os requisitos de autenticação e acesso do Fabric, incluindo as configurações de locatário aplicáveis às entidades de serviço.
3. Defina SQL_AUTHENTICATION como ActiveDirectoryManagedIdentity na configuração da aplicação do host. Mantenha as configurações do servidor, banco de dados e portas. O mesmo aplicativo Java roda sem navegador ou senha.

Identidade gerenciada requer um host Azure suportado; não substitui o login interativo na sua estação de trabalho. Para identidades atribuídas pelo usuário e outros modos de autenticação, veja Conectar usando autenticação Microsoft Entra.

SQL Server com autenticação SQL

Para um container SQL Server ou uma instância existente configurada para autenticação SQL, configure SQL_AUTHENTICATION e SqlPassword forneça um login SQL com acesso ao seu banco de dados. Não use uma conta de administrador de servidor para este exemplo. O prompt de senha do PowerShell requer PowerShell 7.1 ou posterior.

$env:SQL_SERVER_NAME = "<server>"
$env:SQL_DATABASE_NAME = "<database>"
$env:SQL_PORT = "1433"
$env:SQL_AUTHENTICATION = "SqlPassword"
$env:SQL_USER = "<user_id>"
$env:SQL_PASSWORD = Read-Host "SQL password" -MaskInput

export SQL_SERVER_NAME="<server>"
export SQL_DATABASE_NAME="<database>"
export SQL_PORT="1433"
export SQL_AUTHENTICATION="SqlPassword"
export SQL_USER="<user_id>"
read -r -s -p "SQL password: " SQL_PASSWORD
printf '\n'
export SQL_PASSWORD

Use a porta TCP da sua instância caso ela não seja 1433. Variáveis de ambiente mantêm as credenciais fora do código-fonte, mas não são um cofre de segredos. Não os registre em logs nem os envie para o controle de código-fonte. Não ative o log de depuração do Maven (-X) enquanto variáveis de senha estiverem definidas: o plugin de execução registra os valores das variáveis de ambiente do processo filho. Para aplicações implantadas, use as configurações de gerenciamento de segredos e conexão segura da sua plataforma.

Confie em uma autoridade privada certificadora

Pule essa seção se seu JDK já confia no emissor do certificado do servidor. Caso contrário, obtenha com seu administrador, por meio de um canal confiável, o certificado público e a impressão digital SHA-256 do certificado da autoridade certificadora (CA) emissora. Não confie em um certificado só porque o servidor o apresentou durante uma conexão falhada.

Defina SQL_SERVER_NAME para um nome DNS coberto pelo certificado do servidor e resolvível pelo seu computador. O aplicativo não sobrescreve hostNameInCertificate, então o driver valida o nome do servidor configurado. Adicionar uma CA confiável não resolve uma incompatibilidade entre nome de certificado.

Use o keytool da mesma instalação do JDK 21 que o Maven usa. Substitua <ca-certificate-file> pelo caminho do certificado de CA verificado, <jdk-home> pelo diretório desse JDK e <trust-store-file> por um novo caminho absoluto fora do seu projeto. Mantenha o armazenamento de confiança em um diretório que outros usuários sem privilégio não possam modificar. Pare se algum comando falhar.

1. Inspecione o certificado da CA e compare sua impressão digital SHA-256 com o valor fornecido pelo seu administrador.

   keytool -printcert -file "<ca-certificate-file>"
   

2. Crie um repositório de confiança dedicado ao PKCS12 copiando as raízes públicas do JDK. Não modifique o arquivo cacerts do JDK instalado nem sobrescreva um repositório de confiança existente.

   keytool -importkeystore -srckeystore "<jdk-home>/lib/security/cacerts" -destkeystore "<trust-store-file>" -deststoretype PKCS12
   

   Digite uma nova senha da loja de destino quando solicitado. Para a senha do repositório de origem, use o valor fornecido pelo fornecedor do JDK ou pelo administrador. Copiar as raízes públicas mantém a confiança para servidores que usam CAs públicas.

3. Adicione a CA verificada à loja dedicada.

   keytool -importcert -alias sql-server-ca -file "<ca-certificate-file>" -keystore "<trust-store-file>" -storetype PKCS12
   

   Digite a senha da loja de destino. Antes de confirmar a importação, verifique se a impressão digital exibida corresponde ao valor verificado.

Defina essas duas variáveis opcionais no terminal onde você roda o Maven. Use a senha da loja de destino que você acabou de criar. O prompt de senha do PowerShell requer PowerShell 7.1 ou posterior.

$env:SQL_TRUST_STORE = "<trust-store-file>"
$env:SQL_TRUST_STORE_PASSWORD = Read-Host "Trust-store password" -MaskInput

export SQL_TRUST_STORE="<trust-store-file>"
read -r -s -p "Trust-store password: " SQL_TRUST_STORE_PASSWORD
printf '\n'
export SQL_TRUST_STORE_PASSWORD

A aplicação Java lê essas variáveis e configura explicitamente seu armazenamento de confiança JDBC. Omita ambas as variáveis para usar a configuração padrão de trust da Máquina Virtual Java (JVM). Manter encrypt=true e trustServerCertificate=false.

O Maven inicia um processo Java separado para essa aplicação. Definir uma propriedade do Java Secure Socket Extension (JSSE), como javax.net.ssl.trustStore, com mvn -D... ou MAVEN_OPTS não configura esse processo filho. JAVA_TOOL_OPTIONS e JDK_JAVA_OPTIONS a acessam, mas a JVM exibe essas opções na inicialização. Não coloque senhas em nenhuma das variáveis. Use as variáveis de aplicação desta seção em vez disso. Para saber mais sobre configuração de trust, veja Configurar o cliente para criptografia.

Adicionar a aplicação Java

A partir do jdbc-quickstart diretório, crie o diretório fonte Java.

New-Item -ItemType Directory -Path src\main\java -Force | Out-Null

mkdir -p src/main/java

Salve a seguinte aplicação completa como Quickstart.java em src/main/java.

A consulta SELECT CAST(? AS int) + 1 AS answer Transact-SQL (T-SQL) aceita um parâmetro. setInt vincula o valor 41 separadamente do texto SQL. O resultado esperado é exatamente uma linha contendo 42.

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

import com.microsoft.sqlserver.jdbc.SQLServerDataSource;

public class Quickstart {
    public static void main(String[] args) throws SQLException {
        SQLServerDataSource dataSource = new SQLServerDataSource();
        dataSource.setServerName(required("SQL_SERVER_NAME"));
        dataSource.setDatabaseName(required("SQL_DATABASE_NAME"));
        dataSource.setPortNumber(Integer.parseInt(required("SQL_PORT")));
        dataSource.setEncrypt("true");
        dataSource.setTrustServerCertificate(false);
        dataSource.setLoginTimeout(30);

        String authentication = required("SQL_AUTHENTICATION");
        switch (authentication) {
            case "ActiveDirectoryInteractive":
            case "ActiveDirectoryManagedIdentity":
                break;
            case "SqlPassword":
                dataSource.setUser(required("SQL_USER"));
                dataSource.setPassword(required("SQL_PASSWORD"));
                break;
            default:
                throw new IllegalArgumentException(
                        "SQL_AUTHENTICATION must be ActiveDirectoryInteractive, "
                        + "ActiveDirectoryManagedIdentity, or SqlPassword.");
        }
        dataSource.setAuthentication(authentication);

        if (System.getenv("SQL_TRUST_STORE") != null
                || System.getenv("SQL_TRUST_STORE_PASSWORD") != null) {
            dataSource.setTrustStore(required("SQL_TRUST_STORE"));
            dataSource.setTrustStorePassword(required("SQL_TRUST_STORE_PASSWORD"));
            dataSource.setTrustStoreType("PKCS12");
        }

        String sql = "SELECT CAST(? AS int) + 1 AS answer";
        try (Connection connection = dataSource.getConnection();
             PreparedStatement statement = connection.prepareStatement(sql)) {
            statement.setInt(1, 41);
            statement.setQueryTimeout(30);
            try (ResultSet results = statement.executeQuery()) {
                if (!results.next() || results.getInt("answer") != 42 || results.next()) {
                    throw new SQLException("Expected exactly one row with answer = 42.");
                }
            }
        }
        System.out.println("Verified result: 42");
    }

    private static String required(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("Set environment variable " + name + ".");
        }
        return value;
    }
}

O aplicativo define os tempos de login e consulta para 30 segundos. A autenticação interativa possui um limite separado de espera de token descrito em Solução de Problemas na primeira execução. A aplicação fecha o conjunto de resultados, a instrução preparada e a conexão usando try-with-resources, inclusive quando ocorre uma exceção. Erros se propagam e fazem o processo sair com um status diferente de zero.

Execute e verifique

No diretório jdbc-quickstart, execute:

mvn -q compile exec:exec

O Maven baixa as dependências, compila a aplicação e inicia um processo Java separado. Para ActiveDirectoryInteractive, complete o login do navegador e retorne ao seu terminal.

Após a consulta ser bem-sucedida e a aplicação fechar os recursos, ela imprime:

Verified result: 42

Uma mensagem do navegador dizendo que a autenticação está completa não prova que a conexão ao banco de dados foi bem-sucedida. Verifique o resultado da aplicação e o status zero de saída: $LASTEXITCODE no PowerShell ou $? no Bash. A consulta não depende de nenhuma tabela existente nem deixa dados para serem limpos.

Se você usou autenticação SQL, remova SQL_PASSWORD do ambiente do terminal quando terminar. No PowerShell, execute Remove-Item Env:\SQL_PASSWORD. No Bash, corra unset SQL_PASSWORD.

Se você configurou um repositório de confiança de AC privada, remova também as variáveis de ambiente correspondentes. No PowerShell, execute Remove-Item Env:\SQL_TRUST_STORE, Env:\SQL_TRUST_STORE_PASSWORD. No Bash, corra unset SQL_TRUST_STORE SQL_TRUST_STORE_PASSWORD. Mantenha o depósito fiduciário apenas enquanto precisar.

Solucionar o problema da primeira execução

Para diagnósticos adicionais, veja Solução de problemas de conectividade.

Conteúdo relacionado

• Conectar-se usando a autenticação do Microsoft Entra
• Como usar uma instrução SQL com parâmetros
• Uso de chaves geradas automaticamente
• Resiliência de conexão
• Aplicativos de exemplo do JDBC Driver