Microsoft JDBC Driver para SQL Server

Descargar controlador JDBC

El controlador de conectividad de bases de datos Microsoft Java (JDBC) para SQL Server es un controlador JDBC Tipo 4 (Java puro, comunica directamente el protocolo TDS SQL Server, sin necesidad de bibliotecas nativas) que permite que cualquier aplicación o servidor de aplicaciones Java se conecte al Microsoft SQL Motor de base de datos en Azure SQL Database, SQL database en Fabric, Azure SQL Managed Instance y en todas las versiones y ediciones compatibles de SQL Server (incluyendo Express Editions). Implementa las API de JDBC estándar y funciona con servidores de aplicaciones de Java importantes, como IBM WebSphere y SAP NetWeaver.

Elija el punto de partida.

• Para configurar un entorno de desarrollo de Java y ejecutar la primera consulta, comience con paso 1: Configurar el entorno de desarrollo, Paso 2: Crear una base de datos SQL y Paso 3: Prueba de concepto que se conecta a SQL mediante Java.
• Para conectarse a Azure SQL con autenticación sin contraseña, comience con Conectarse mediante autenticación de Microsoft Entra y Creación de la URL de conexión.
• Para agregar el controlador a maven, Gradle u otra compilación, vaya a Descargar Microsoft controlador JDBC para SQL Server.
• Para que una aplicación existente sea resistente a errores transitorios, vaya a Resistencia de conexión y Lógica de reintento configurable.
• Para diagnosticar un problema de conexión o consulta, vaya a Diagnóstico de problemas con el controlador JDBC y Solución de problemas de conectividad.

Línea base de producción para Azure SQL

Use este fragmento de código como punto de partida para una conexión Azure SQL orientada a producción. Carga el nombre del servidor y el nombre de la base de datos a partir de la configuración de la aplicación, como la configuración de aplicaciones de Azure App Service, las variables de entorno o un archivo de configuración, y establece mediante programación el resto de las propiedades de conexión. La configuración combina el protocolo TLS (Transport Layer Security), la identidad administrada, los reintentos de conexión ante errores transitorios, la recuperación rápida de grupos de conmutación por error, un tiempo de espera de inicio de sesión más prolongado para cubrir una conmutación por error en arranque en frío y una lógica de reintentos configurable (CRL) para las instrucciones que se ven afectadas por la limitación de Azure SQL o por una conmutación por error durante la consulta.

Para una mayor seguridad y escalabilidad horizontal más sencilla, mantenga la información de conexión fuera del código. En producción, almacene la información de conexión en el sistema de configuración de la aplicación y use Azure Key Vault para los valores confidenciales y la configuración de conexión administrada centralmente. Para obtener más información, consulte Protección de cadenas de conexión.

Los fragmentos de código de Java de este artículo omiten las importaciones y los contenedores de clases para mayor brevedad.

// 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á optimizado para grupos de conmutación por error de Azure SQL Database y Azure SQL Managed Instance.

Establece multiSubnetFailover=true únicamente cuando te conectes a un listener de un grupo de conmutación por error, a un listener de un grupo de disponibilidad o a un punto de conexión de una instancia de clúster de conmutación por error. El uso de esta propiedad con puntos de conexión que no sean listeners de alta disponibilidad (HA) puede afectar negativamente al rendimiento y no está admitido. Para obtener más información, consulte Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres.

El fragmento de código no establece retryConn porque el controlador ya reintenta los errores de conexión transitorios más comunes de Azure SQL (incluidos 4060, 40197, 40501, 40613, 49918, 49919, 49920, 10928 y 10929) de forma predeterminada, controlados por connectRetryCount y connectRetryInterval. Para obtener la lista completa, consulte Lista de errores de conexión transitorios integrados. Añada retryConn con +<errorNumber> solo cuando necesite ampliar la lista con un error que no esté ya contemplado, o establézcalo en <errorNumber> (sin + al principio) para reemplazarlo. Si coloca el mismo valor en una dirección URL de JDBC, encapsula como retryConn={+<errorNumber>} o retryConn={<errorNumber>}.

La retryExec propiedad tiene dos partes, escritas como rule1;rule2 cuando se establece mediante programación. Si coloca el mismo valor en una dirección URL de JDBC, encapsula cada regla entre llaves como {rule1};{rule2}:

• {1205,1222:3,5+5} reintenta tres veces los casos de interbloqueo (1205) y los tiempos de espera de solicitud de bloqueo (1222) con un retroceso lineal de 5, 10 y 15 segundos. Para 1205, SQL Server revierte la transacción antes de que el controlador vea el error, por lo que volver a ejecutar una sola instrucción es segura. Si la instrucción en interbloqueo formaba parte de una transacción con varias instrucciones, las instrucciones anteriores también se han revertido y CRL no las vuelve a ejecutar, por lo que debe envolver toda la transacción en su propio bucle de reintentos. El error 1222 deja la transacción abierta y el reintento a nivel de instrucción solo vuelve a ejecutar la instrucción dentro de la transacción original; si además necesita limitar la duración de la transacción, envuelva toda la transacción en su propio bucle de reintentos.

• {40501,40613,40197,10928,10929,49918:4,5*2} reintenta cuatro veces los errores de limitación de Azure SQL, de conmutación por error durante la consulta y de límite de recursos, con un retroceso exponencial de 5, 10, 20 y 40 segundos. Estos errores se encuentran en la lista transitoria integrada para el bucle connect, pero retryExec es lo que los detecta cuando se producen durante una consulta en una conexión establecida. Los retrasos de CRL están limitados por queryTimeout. Si se establece queryTimeout en un valor inferior a la siguiente espera prevista, el controlador se da por vencido antes de tiempo y vuelve a lanzar el error. Elija un valor de queryTimeout que sea, como mínimo, igual a la suma de las esperas de CRL más el tiempo de ejecución de la instrucción, o acepte que los retrasos más largos no se activarán.

Para los grupos de conmutación por error de Azure SQL Database, las réplicas con nombre de Hyperscale y la escalabilidad horizontal de lectura, o los oyentes de grupos de disponibilidad de Always On, configura applicationIntent=ReadOnly cuando desees aterrizar en un secundario legible. En el caso de las nubes soberanas en las que el Nombre alternativo del sujeto (SAN) del certificado no incluye el host al que se va a conectar, establezca también hostNameInCertificate para que coincida con él (por ejemplo, *.database.usgovcloudapi.net para Azure Government).

Para obtener más información sobre cada parte de esta configuración, consulte:

• Creación de la dirección URL de conexión
• Establecimiento de las propiedades de conexión
• Conéctate usando la autenticación de Microsoft Entra
• Resistencia de conexión
• Lógica de reintento configurable
• Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres
• Descripción de las propiedades de tiempo de espera en el controlador JDBC

Para consultar el catálogo de errores transitorios de Azure SQL, consulte Solucionar errores transitorios de conexión.

Características clave

• JDBC basado en estándares: controlador de tipo 4. La compilación de JRE 11+ implementa JDBC 4.2, además de los métodos de límite de solicitud de JDBC 4.3 (beginRequest, endRequest) y los auxiliares de comillas de Statement. Las API de fragmentación de JDBC 4.3 (setShardingKey, la familia createConnectionBuilder) lanzan SQLFeatureNotSupportedException. La compilación JRE 8 implementa JDBC 4.2. Para obtener el desglose por versión y la lista completa de métodos compatibles y no compatibles 4.3, consulte compatibilidad con la especificación Java y JDBC.
• Compatibilidad con plataformas amplias: se ejecuta en cualquier plataforma con una máquina virtual (JVM) compatible con Java, incluidos Windows, Linux y macOS.
• Cifrado de forma predeterminada: conexiones cifradas con TLS con encrypt=true como valor predeterminado para los controladores actuales.
• Autenticación de Microsoft Entra ID: conexiones sin contraseña con identidad administrada, principal de servicio, autenticación interactiva, autenticación integrada, cadena de credenciales predeterminada y flujos de token de acceso.
• Kerberos: autenticación integrada para Active Directory local.
• NTLM: autenticación de desafío/respuesta de Windows para escenarios fuera de dominio o heredados.
• Always Encrypted: cifrado del lado cliente para columnas confidenciales, con enclaves seguros opcionales para operaciones en contexto.
• Copia masiva: inserciones de alto rendimiento con la API SQLServerBulkCopy y rendimiento de inserción por lotes para executeBatch.
• Resiliencia de conexión: reintentos de conexión integrados para errores transitorios, además de lógica de reintento configurable y opcional para sentencias (retryExec) y una lista personalizable de errores de conexión (retryConn).
• Compatibilidad con tipos de datos de SQL Server enriquecidos: datetimeoffset, sql_variant, JSON, espacial, vector, parámetros con valores de tabla y tipos definidos por el usuario.

Empieza ahora

Configuración y conexión

Autenticación

Secure

Trabajar con datos

Tipos de datos

Transacciones y simultaneidad

Rendimiento y confiabilidad

Diagnóstico y solución de problemas

Tareas relacionadas

Contenido relacionado

• Microsoft controlador JDBC para SQL Server en GitHub
• El controlador JDBC de Microsoft para SQL Server en Maven Central
• Notas de la versión del controlador JDBC de Microsoft para SQL Server
• Más información sobre el controlador JDBC
• Módulos de conexión para Microsoft SQL Database