Inicio rápido: Conéctate a SQL Server con Java y Maven

Utiliza el controlador Microsoft Java Database Connectivity (JDBC) para SQL Server para conectar una aplicación de Java a SQL Server, Azure SQL Database o una base de datos SQL en Fabric. Este inicio rápido utiliza Maven para descargar dependencias, lee la configuración de conexión de variables de entorno y verifica un resultado de consulta parametrizado. No necesitas AdventureWorks ni ninguna tabla de muestras.

Para Azure SQL Database o SQL Database en Fabric, utiliza la autenticación Microsoft Entra ID sin almacenar contraseña en tu aplicación. Durante el desarrollo local, inicia sesión a través de un navegador. Para una aplicación alojada en Azure, utiliza una identidad gestionada.

Prerequisites

• Kit de desarrollo Java (JDK) 21. Revisa tu instalación con java -version.
• Apache Maven. Corre mvn -version y confirma que Maven usa JDK 21.
• Una base de datos y permiso para conectarse a ella. Elige una base de datos alojada o un contenedor de SQL Server en Elige tu base de datos. La consulta lee un valor calculado y no crea ni modifica objetos de base de datos.
• Acceso en red a tu endpoint de base de datos. Para Azure SQL, configura el acceso a la red. Para Fabric, sigue las instrucciones de Conectarte a tu base de datos SQL. Para SQL Server, activa el Protocolo de Control de Transmisión/Protocolo de Internet (TCP/IP) y utiliza el puerto configurado.
• Un certificado de servidor en el que tu runtime Java confía. La aplicación requiere cifrado y valida el certificado del servidor. Para una entidad de certificación privada, consulta Confiar en una entidad de certificación privada.

Elección de la base de datos

Utiliza una base de datos existente o crea una utilizando las siguientes guías. Una base de datos vacía es suficiente.

Las imágenes de contenedor de SQL Server Linux requieren un host x86-64 compatible. En un ordenador de desarrollo ARM64, ejecuta esta aplicación Java sobre una base de datos alojada o un contenedor en un host remoto soportado en lugar de depender de la emulación de contenedores.

Un contenedor nuevo podría usar un certificado en el que tu JDK no confía. Antes de ejecutar este ejemplo, configura un certificado de servidor y, para un emisor privado, configura el almacén de confianza Java. Mantén activada la validación de certificados también para las conexiones de contenedores.

Crear el proyecto Maven

Cree un directorio llamado jdbc-quickstart. En ese directorio, crea pom.xml con el siguiente contenido. Maven gestiona la ruta de clase; no necesitas descargar archivos de archivo 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>

El artefacto del controlador jre11 funciona con JDK 21. La dependencia explícita azure-identity proporciona las librerías de autenticación necesarias para los modos Microsoft Entra en este inicio rápido; esas bibliotecas son dependencias opcionales del controlador y no se añaden automáticamente a tu aplicación.

Estas versiones coinciden con el modelo de objetos de proyecto (POM) publicado en JDBC 13.6.0. La dependencia explícita azure-core-http-netty conserva la versión de transporte seleccionada por esa versión del controlador.

Para actualizaciones de drivers, consulta la página de descarga, las versiones publicadas de Maven y la matriz de soporte en Java. Cuando actualices el controlador, compara las dependencias de autenticación con el POM publicado por el controlador. Véase Dependencias de características. Utiliza versiones explícitas en lugar de rangos de versiones de Maven o LATEST.

Configurar la conexión

Pon las variables de entorno en el mismo terminal donde ejecutas Maven. Sustituye <server> y <database> con el nombre de tu endpoint y base de datos. Configure SQL_SERVER_NAME solo con el nombre de host, sin una URL de JDBC ni un puerto.

Si el valor del servidor copiado es tcp:<server>,1433, use solo <server> para SQL_SERVER_NAME y establezca SQL_PORT en 1433. No incluyas el prefijo ,1433 ni el sufijo tcp: en el nombre de host.

Azure SQL o Fabric con autenticación Microsoft Entra

Para el desarrollo local, utiliza ActiveDirectoryInteractive. El controlador abre un navegador para iniciar sesión y soporta autenticación multifactor. Inicia sesión con la identidad que tiene acceso a tu base de datos. No configures SQL_USER ni SQL_PASSWORD para este modo.

Para Azure SQL Database, sustituye <server> por el nombre completo del host, como contoso.database.windows.net. Para Fabric, copia el nombre del host desde la configuración de conexión de la base de datos SQL; no lo construyas a partir del nombre de la base de datos ni añadas un sufijo Azure SQL. Fabric requiere autenticación Microsoft Entra; no uses el ejemplo de autenticación 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 una aplicación sin interfaz alojada en un recurso de Azure con una identidad gestionada asignada por el sistema:

1. Activa la identidad gestionada del recurso.
2. Pide a tu administrador que conceda a esa identidad acceso a la base de datos. Para Azure SQL, crea un usuario de base de datos para la identidad. En Fabric, sigue los requisitos de autenticación y acceso de Fabric, incluida la configuración del inquilino aplicable a las entidades de servicio.
3. Establezca SQL_AUTHENTICATION en ActiveDirectoryManagedIdentity en la configuración de la aplicación del host. Mantén la configuración del servidor, la base de datos y los puertos. La misma aplicación Java se ejecuta sin navegador ni contraseña.

La identidad gestionada requiere un host de Azure compatible; no sustituye el inicio de sesión interactivo en tu estación de trabajo. Para las identidades asignadas por el usuario y otros modos de autenticación, véase Conectar usando autenticación Microsoft Entra.

SQL Server con autenticación SQL

Para un contenedor de SQL Server o una instancia existente configurada para autenticación SQL, configura SQL_AUTHENTICATION y SqlPassword proporciona un inicio de sesión SQL con acceso a tu base de datos. No uses una cuenta de administrador de servidor para este ejemplo. La solicitud de PowerShell para la contraseña requiere PowerShell 7.1 o una versión 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

Usa el puerto TCP de tu instancia si no es 1433. Las variables de entorno mantienen las credenciales fuera del código fuente, pero no son un almacén secreto. No los registres ni los subas al control de versiones. No habilites el registro de depuración de Maven (-X) cuando haya variables de contraseña definidas: el complemento de ejecución registra los valores de entorno del proceso hijo. Para aplicaciones desplegadas, utiliza la gestión de secretos y la configuración de conexión segura de tu plataforma.

Confía en una autoridad privada certificadora

Salta esta sección si tu JDK ya confía en el emisor del certificado del servidor. De lo contrario, obtén de tu administrador, a través de un canal de confianza, el certificado público y la huella digital SHA-256 de la autoridad de certificación (CA) emisora. No confíes en un certificado solo porque el servidor lo haya mostrado durante una conexión fallida.

Configura SQL_SERVER_NAME con un nombre DNS incluido en el certificado del servidor y que se pueda resolver desde tu ordenador. La aplicación no anula hostNameInCertificate, así que el controlador valida el nombre del servidor configurado. Añadir una CA de confianza no soluciona una discrepancia entre el nombre del certificado.

Usa la keytool de la misma instalación de JDK 21 que utiliza Maven. Sustituye <ca-certificate-file> por la ruta del certificado de CA verificado, <jdk-home> por el directorio de ese JDK y <trust-store-file> por una nueva ruta absoluta fuera de tu proyecto. Mantén el almacén de confianza en un directorio que otros usuarios sin privilegio no puedan modificar. Detente si falla algún comando.

1. Inspecciona el certificado de la CA y compara su huella dactilar SHA-256 con el valor que te proporcionó tu administrador.

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

2. Crea un almacén fiduciario dedicado a PKCS12 copiando las raíces públicas del JDK. No modifiques el archivo cacerts del JDK instalado ni sobrescribas un almacén de confianza existente.

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

   Introduzca una nueva contraseña del almacén de destino cuando se le solicite. Para la contraseña source-store, utiliza el valor proporcionado por tu proveedor JDK o administrador. Copiar las raíces públicas mantiene la confianza para los servidores que usan CAs públicas.

3. Añade la CA verificada a la tienda dedicada.

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

   Introduce la contraseña de la tienda de destino. Antes de confirmar la importación, comprueba que la huella dactilar mostrada coincide con el valor verificado.

Pon estas dos variables opcionales en el terminal donde ejecutes Maven. Usa la contraseña de destino-tienda que acabas de crear. La solicitud de PowerShell para la contraseña requiere PowerShell 7.1 o una versión 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

La aplicación Java lee estas variables y configura explícitamente su almacén de confianza JDBC. Omite ambas variables para usar la configuración de confianza predeterminada de la Máquina Virtual Java (JVM). Conserva encrypt=true y trustServerCertificate=false.

Maven inicia un proceso Java separado para esta aplicación. Establecer una propiedad de Java Secure Socket Extension (JSSE), como javax.net.ssl.trustStore, con mvn -D... o MAVEN_OPTS no configura ese proceso hijo. JAVA_TOOL_OPTIONS y JDK_JAVA_OPTIONS llegan hasta ahí, pero la JVM muestra esas opciones al iniciarse. No pongas contraseñas en ninguna de las variables. Utiliza las variables de aplicación de esta sección en su lugar. Para más información sobre la configuración de la confianza, consulta Configurar el cliente para cifrado.

Añadir la aplicación Java

Desde el jdbc-quickstart directorio, crea el directorio fuente Java.

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

mkdir -p src/main/java

Guarde la siguiente aplicación completa como Quickstart.java en src/main/java.

La consulta SELECT CAST(? AS int) + 1 AS answer Transact-SQL (T-SQL) acepta un parámetro. setInt vincula el valor 41 por separado del texto SQL. El resultado esperado es exactamente una fila que contiene 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;
    }
}

La aplicación establece los tiempos de inicio de sesión y consulta en 30 segundos. La autenticación interactiva tiene un límite de espera de token separado descrito en Solución de problemas en la primera ejecución. La aplicación cierra el conjunto de resultados, la instrucción preparada y la conexión usando try-with-resources, incluyendo cuando ocurre una excepción. Los errores se propagan y hacen que el proceso termine con un estado distinto de cero.

Ejecuta y verifica

Desde el jdbc-quickstart directorio, ejecuta:

mvn -q compile exec:exec

Maven descarga las dependencias, compila la aplicación y inicia un proceso Java separado. Para ActiveDirectoryInteractive, completa la sesión del navegador y regresa a tu terminal.

Tras el éxito de la consulta y el cierre de los recursos por parte de la aplicación, se imprime:

Verified result: 42

Un mensaje del navegador que indica que la autenticación está completa no prueba que la conexión a la base de datos haya tenido éxito. Comprueba el resultado de la aplicación y el estado cero de salida: $LASTEXITCODE en PowerShell o $? en Bash. La consulta no depende de ninguna tabla existente ni deja datos que limpiar.

Si usaste autenticación SQL, elimina SQL_PASSWORD del entorno del terminal cuando termines. En PowerShell, ejecute Remove-Item Env:\SQL_PASSWORD. En Bash, corre unset SQL_PASSWORD.

Si configuraste un almacén fiduciario de CA privada, también elimina sus variables de entorno. En PowerShell, ejecute Remove-Item Env:\SQL_TRUST_STORE, Env:\SQL_TRUST_STORE_PASSWORD. En Bash, corre unset SQL_TRUST_STORE SQL_TRUST_STORE_PASSWORD. Mantén el almacén de confianza solo mientras lo necesites.

Solucionar el problema de la primera ejecución

Para diagnósticos adicionales, consulte Solución de problemas de conectividad.

Contenido relacionado

• Conéctate usando la autenticación de Microsoft Entra
• Uso de una instrucción SQL con parámetros
• Uso de claves generadas automáticamente
• Resistencia de conexión
• Aplicaciones de ejemplo del controlador JDBC