Microsoft JDBC Driver para SQL Server

Descargar controlador JDBC

El controlador de conectividad de base de datos (JDBC) de Microsoft Java para SQL Server es un controlador JDBC de tipo 4 (Java puro, habla directamente el protocolo TDS de SQL Server, no se requiere ninguna biblioteca nativa) que permita que cualquier aplicación o servidor de aplicaciones Java se conecte a SQL Server, Azure SQL Database, Azure SQL Managed Instance y SQL Database en Microsoft Fabric. 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 Seguridad de la capa de transporte (TLS), identidad administrada, reintentos de conexión ante errores transitorios, recuperación rápida del grupo de conmutación por error, un tiempo de espera de inicio de sesión más largo para cubrir una conmutación por error tras un arranque en frío y lógica de reintento configurable (CRL) para instrucciones que se ven afectadas por la limitación de Azure SQL o por una conmutación por error a mitad de 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 los grupos de conmutación por error de Azure SQL Database y Azure SQL Managed Instance.

Establezca multiSubnetFailover=true solo cuando se conecte a un agente de escucha de grupo de conmutación por error, un agente de escucha de grupo de disponibilidad o un punto de conexión de instancia de clúster de conmutación por error. Usar esta propiedad con puntos de conexión que no sean listeners de alta disponibilidad (HA) puede perjudicar el rendimiento y no es compatible. 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 configura retryConn porque el controlador ya reintenta de forma predeterminada los errores transitorios de conexión más comunes de Azure SQL (incluidos 4060, 40197, 40501, 40613, 49918, 49919, 49920, 10928 y 10929), condicionado 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} vuelve a intentar tres veces las víctimas de interbloqueo (1205) y los tiempos de espera de las solicitudes de bloqueo (1222), con una espera 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 sentencia que provocó el interbloqueo formaba parte de una transacción de varias sentencias, las sentencias anteriores también se revirtieron y CRL no las vuelve a ejecutar, así que envuelve toda la transacción en tu propio bucle de reintento. 1222 mantiene abierta la transacción y el reintento a nivel de instrucción solo vuelve a ejecutar la instrucción dentro de la transacción original; si también necesita limitar la duración de la transacción, encapsule toda la transacción en su propio bucle de reintento.

• {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 en mitad de la consulta y de límite de recursos, con intervalos de espera exponenciales de 5, 10, 20 y 40 segundos. Estos errores están en la lista integrada de errores transitorios del bucle connect, pero retryExec es quien los detecta cuando se producen en mitad de una consulta en una conexión ya establecida. Los intervalos de espera de CRL están acotados por queryTimeout. Si estableces queryTimeout por debajo de la siguiente espera prevista, el controlador desiste antes de tiempo y vuelve a lanzar la excepción. Elija un queryTimeout que sea como mínimo tan grande como el total de sus esperas de CRL más el tiempo de ejecución de la instrucción, o acepte que los mayores intervalos de espera no se activarán.

Para los grupos de conmutación por error de Azure SQL Database, las réplicas con nombre hiperescala y el escalado horizontal de lectura o los agentes de escucha del grupo de disponibilidad AlwaysOn, establezca applicationIntent=ReadOnly cuando quiera llegar a una base de datos secundaria 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 para JRE 11+ implementa JDBC 4.2, además de los métodos de delimitación de solicitudes de JDBC 4.3 (beginRequest, endRequest) y las utilidades de comillas 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 sin dominio o heredados.
• Always Encrypted: cifrado del lado cliente para columnas confidenciales, con enclaves seguros opcionales para operaciones en contexto.
• Copia en bloque: inserciones de alto rendimiento con la API SQLServerBulkCopy y rendimiento en la 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