Establecimiento de las propiedades de conexión
Las propiedades de las cadenas de conexión se pueden especificar de diversas formas:
Como propiedades nombre=valor en la dirección URL de conexión cuando la conexión se establece con la clase DriverManager. Para obtener la sintaxis de la cadena de conexión, vea Building the connection URL (Creación de la dirección URL de conexión).
Como propiedades nombre=valor en el parámetro Properties del método Connect en la clase DriverManager.
Como valores en el método establecedor adecuado del origen de datos del controlador. Por ejemplo:
datasource.setServerName(value) datasource.setDatabaseName(value)
Observaciones
En los nombres de las propiedades no se distinguen entre mayúsculas y minúsculas, y los duplicados se resuelven de la siguiente forma:
- Argumentos de API (como usuario y contraseña)
- Colección de propiedades
- Última aparición de la cadena de conexión
Se permiten valores desconocidos para los nombres de propiedades, y el controlador JDBC no los valida en relación con la distinción entre mayúsculas y minúsculas.
Se permite el uso de sinónimos y se resuelven por orden, igual que los nombres de propiedad duplicados.
Propiedades
La siguiente tabla muestra todas las propiedades de cadena de conexión disponibles actualmente para el controlador JDBC.
| Propiedad Tipo Valor predeterminado |
Descripción |
|---|---|
| accessToken String null |
(Versión 6.0 y posteriores) Use esta propiedad para conectarse a una base de datos mediante un token de acceso. accessToken no se puede establecer mediante la dirección URL de conexión. |
| accessTokenCallbackClass Cadena null |
(Versión 12.4 y posteriores) Nombre de la clase de implementación de devolución de llamada que se va a usar con la devolución de llamada del token de acceso. |
| applicationIntent String ReadWrite |
(Versión 6.0 y posteriores) Declara el tipo de carga de trabajo de la aplicación para conectarse a un servidor. Los valores posibles son ReadOnly y ReadWrite. Para obtener más información sobre la recuperación ante desastres, vea el artículo Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres. |
| applicationName String [<=128 char] null |
Nombre de la aplicación o "Microsoft JDBC Driver para SQL Server" si no se ha proporcionado ningún nombre. Se usa para identificar la aplicación concreta en diversas herramientas de creación de perfiles y registros de SQL Server. |
| autenticación String NotSpecified |
(Versión 6.0 y posteriores) Esta propiedad opcional indica qué método de autenticación se debe usar para la conexión. Los valores posibles son ActiveDirectoryIntegrated, ActiveDirectoryPassword, ActiveDirectoryManagedIdentity (versión 12.2+), ActiveDirectoryMSI (versión 7.2+), ActiveDirectoryInteractive (versión 9.2+), ActiveDirectoryServicePrincipal (versión 9.2+), SqlPassword y NotSpecified (predeterminado). Usa ActiveDirectoryIntegrated (versión 6.0 y posteriores) para conectarse a una base de datos SQL mediante la autenticación integrada de Windows. Usa ActiveDirectoryPassword (versión 6.0 y posteriores) para conectarte a SQL con un nombre principal y contraseña de Microsoft Entra. Usa ActiveDirectoryManagedIdentity (versión 12.2 y posteriores) o ActiveDirectoryMSI (versión 7.2 o posteriores) para conectarte a SQL desde un recurso de Azure. Por ejemplo, una máquina virtual de Azure, App Service o aplicación de funciones mediante la autenticación de identidad administrada. Los dos tipos de identidades administradas que el controlador admite al usar el modo de autenticación ActiveDirectoryManagedIdentity o ActiveDirectoryMSI son: 1. Identidad administrada asignada por el sistema: Se usa para adquirir accessToken de forma predeterminada. 2. Identidad administrada asignada por el usuario: Se usa para adquirir accessToken si el identificador de cliente de una instancia de identidad administrada se especifica con la propiedad de conexión msiClientId. Usa ActiveDirectoryInteractive para conectarte a una base de datos mediante un flujo de autenticación interactiva. Usa ActiveDirectoryServicePrincipal (versión 9.2 y posteriores) para conectarte a una base de datos con el Id. de cliente y el secreto de una identidad de entidad de servicio. Especifique el Id. de cliente en la propiedad userName y el secreto en la propiedad password (10.2 y versiones posteriores). Usa SqlPassword para conectarse a SQL mediante las propiedades userName/user y password. Use NotSpecified si no se necesita ninguno de estos métodos de autenticación. Importante:Si la autenticación se establece en ActiveDirectoryIntegrated, es necesario instalar las dos bibliotecas siguientes: mssql-jdbc_auth-<version>-<arch>.dll (disponible en el paquete de controladores JDBC) y la Biblioteca de autenticación de Microsoft para SQL Server (ADAL.DLL). La biblioteca de autenticación de Microsoft se puede instalar mediante Microsoft ODBC Driver for SQL Server o Microsoft OLE DB Driver for SQL Server. El controlador JDBC solo admite la versión 1.0.2028.318 y posteriores para ADAL.DLL. Nota: Al establecer la propiedad de autenticación en cualquier otro valor distinto de NotSpecified, el controlador usa de forma predeterminada el cifrado de Seguridad de la capa de transporte (TLS), antes conocida como Capa de sockets seguros (SSL). Para más información sobre cómo configurar la autenticación de Microsoft Entra en Azure SQL, consulta Usar la autenticación de Microsoft Entra. |
| authenticationScheme String NativeAuthentication |
Indica qué tipo de seguridad integrada desea que use la aplicación. Los valores posibles son JavaKerberos, NTLM (versión 7.4 y posteriores) y NativeAuthentication (el predeterminado). NativeAuthentication hace que el controlador cargue mssql-jdbc_auth-<version>-<arch>.dll (por ejemplo, mssql-jdbc_auth-8.2.2.x64.dll) en Windows, que se usa para obtener información de autenticación integrada. (La biblioteca de autenticación nativa cargada se denomina sqljdbc_auth.dll al usar las versiones 6.0 a 7.4 del controlador).Al usar authenticationScheme=JavaKerberos, debe especificar el nombre de dominio completo (FQDN) en la propiedad serverName o serverSpn. De lo contrario, se produce un error (No se encontró el servidor en la base de datos de Kerberos). Para obtener más información sobre el uso de authenticationScheme=JavaKerberos, consulte el artículo Empleo de autenticación integrada de Kerberos para conectar con SQL Server. Al usar authenticationScheme=NTLM, debe especificar el dominio de Windows mediante la propiedad domain o domainName, las credenciales de Windows en la propiedad user o userName y la propiedad password. De lo contrario, se produce un error (deben especificarse las propiedades de conexión). |
| cacheBulkCopyMetadata boolean ["true" | "false"] false |
(Versión 12.8+) Al usar useBulkCopyForBatchInsert=true, esta propiedad se usa para indicar al controlador si debe almacenar en caché los metadatos de columna de destino en el nivel de conexión. Si se establece en true, asegúrese de que el destino no cambie entre inserciones masivas, ya que el controlador no tiene una manera de controlar este cambio. |
| calcBigDecimalPrecision boolean ["true" | "false"] false |
(Versión 12.6+) Marca para indicar si el controlador debe calcular la precisión de las entradas BigDecimal, en lugar de usar el valor máximo permitido para la precisión (38). |
| cancelQueryTimeout int -1 |
(Versión 6.4 y posteriores) Esta propiedad puede usarse para cancelar el valor queryTimeout establecido en la conexión. La ejecución de consultas se bloquea y no inicia ninguna excepción si la conexión TCP al servidor se quita en modo silencioso. Esta propiedad solo es aplicable si 'queryTimeout' se establece también en la conexión. El controlador espera la cantidad total de cancelQueryTimeout + queryTimeout segundos para quitar la conexión y cerrar el canal. El valor predeterminado de esta propiedad es -1 y el comportamiento es esperar de forma indefinida. |
| clientCertificate String null |
(Versión 8.4 y posteriores) Especifica la ubicación del certificado que se va a utilizar para la autenticación del certificado de cliente. El controlador JDBC admite las extensiones de archivo PFX, PEM, DER y CER. Consulte Autenticación de certificados de cliente para escenarios de bucles invertidos. |
| clientKey Cadena null |
(Versión 8.4 y posteriores) Especifica la ubicación de la clave privada para los certificados PEM, DER y CER especificados por el atributo clientCertificate. Consulte Autenticación de certificados de cliente para escenarios de bucles invertidos. |
| clientKeyPassword Cadena null |
(Versión 8.4 y posteriores) Se especifica la cadena de contraseña opcional para acceder a la clave privada del archivo clientKey. Consulte Autenticación de certificados de cliente para escenarios de bucles invertidos. |
| columnEncryptionSetting String ["Enabled" | "Disabled"] Disabled |
(Versión 6.0 y posteriores) Se establece en "Habilitado" para usar la característica Always Encrypted (AE). Cuando se habilita AE, el controlador JDBC cifra y descifra de forma transparente los datos confidenciales almacenados en columnas de base de datos cifradas en el servidor. Para obtener más información sobre Always Encrypted, vea Usar Always Encrypted con el controlador JDBC. Nota: Always Encrypted está disponible con SQL Server 2016 o versiones posteriores y Azure SQL Database. |
| connectRetryCount int [0..255] 1 |
(Versión 9.4 y posteriores) Número de intentos de reconexión si se produce un error de conexión. |
| connectRetryInterval int [1..60] 10 |
(Versión 9.4 y posteriores) Número de segundos entre cada reintento de conexión. |
| databaseName, database String [<=128 char] null |
Nombre de la base de datos a la que se conectará. Si no se especifica, se establece una conexión a la base de datos predeterminada. |
| datetimeParameterType String ["datetime" | "datetime2" | "datetimeoffset"] datetime2 |
(Versión 12.2 y posteriores) Tipo de datos SQL que se va a usar para los parámetros de fecha/marca de tiempo de Java. Al conectarse uno a SQL Server 2016 o a una versión posterior e interactuar con valores heredados "datetime", los clientes pueden beneficiarse de establecer la propiedad en "datetime". Esta configuración mitiga los problemas de conversión del lado servidor entre los valores "datetime" y "datetime2" Para obtener más información, consulte la información de Gestión del cambio de comportamiento de conversión de datetime a datetime2 a partir de SQL Server 2016 |
| delayLoadingLobs boolean ["true" | "false"] true |
Marca que indica si se debe transmitir por secuencias o no todos los objetos LOB recuperados del conjunto de resultados. Al establecer esta propiedad en "false", se carga el objeto LOB completo en la memoria sin transmisión por secuencias. |
| domainName, dominio String null |
(Versión 7.4 y posteriores) Dominio de Windows para la autenticación mediante NTLM. |
| disableStatementPooling boolean ["true" | "false"] true |
Marca que indica si debe usarse la agrupación de instrucciones. |
| enablePrepareOnFirst... PreparedStatementCall boolean ["true" | "false"] false |
Establézcalo en "true" para habilitar la creación del identificador de instrucción preparada llamando a sp_prepexec con la primera ejecución de una instrucción preparada. Establézcalo en "false" para cambiar la primera ejecución de una instrucción preparada para llamar a sp_executesql y no preparar una instrucción. Si se produce una segunda ejecución, llama a sp_prepexec para configurar un identificador de instrucción preparada. |
| enclaveAttestationUrl String null |
(Versión 8.2 y posteriores) Esta propiedad opcional indica la dirección URL del punto de conexión del servicio de atestación que se va a usar para Always Encrypted con enclaves seguros. Para más información sobre Always Encrypted con enclaves seguros, vea el artículo Uso de Always Encrypted con enclaves seguros con el controlador JDBC. |
| enclaveAttestationProtocol String null |
(Versión 8.2 y posteriores) Esta propiedad opcional indica el protocolo de atestación que se va a usar para Always Encrypted con enclaves seguros. Actualmente, los únicos valores admitidos para este campo son HGS, AAS y NONE (NONE solo se admite en la versión 11.2+). Para más información sobre Always Encrypted con enclaves seguros, vea el artículo Uso de Always Encrypted con enclaves seguros con el controlador JDBC. |
| encrypt String null |
Se establece en "true" para especificar que SQL Server usa el cifrado TLS para todos los datos enviados entre el cliente y el servidor si este último tiene un certificado instalado. El valor predeterminado es "true" en la versión 10.2 y posteriores y "false" en la versión 9.4 y anteriores. A partir de la versión 6.0, hay un valor de conexión "authentication" nuevo que usa el cifrado TLS de forma predeterminada. Para obtener más información, vea la propiedad "authentication". En la versión 11.2.0 y versiones posteriores, el cifrado se cambió de booleano a cadena, lo que permite la compatibilidad con TDS 8.0 cuando la propiedad está establecida en estricta. |
| failoverPartner String null |
Nombre del servidor de conmutación por error que se usa en la configuración de la creación de reflejo de la base de datos. Esta propiedad se usa para un error de conexión inicial al servidor principal. Después de realizar la conexión inicial, se omite esta propiedad. Se debe usar con la propiedad databaseName. Nota: El controlador no admite el número de puerto de la instancia de servidor para la instancia de asociado de conmutación por error como parte de la propiedad failoverPartner en la cadena de conexión. Sin embargo, el controlador sí que permite especificar las propiedades serverName, instanceName y portNumber de la instancia de servidor principal y la propiedad failoverPartner de la instancia de asociado de conmutación por error en la misma cadena de conexión. Si especifica un nombre de red virtual en la propiedad de conexión Server, no puede usar la creación de reflejo de la base de datos. Para obtener más información sobre la recuperación ante desastres, vea el artículo Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres. |
fipsboolean ["true" | "false"] "false" |
En el caso de la Máquina virtual Java (JVM) habilitada para FIPS, esta propiedad debe ser true. |
| fipsProvider String null |
Proveedor FIPS configurado en JVM. Por ejemplo, BCFIPS o SunPKCS11-NSS. Se ha quitado en la versión 6.4.0. Para más información, vea el problema 460 de GitHub. |
| gsscredential org.ietf.jgss.GSSCredential null |
(Versión 6.2 y posteriores) Las credenciales de usuario que se van a usar para la delegación restringida de Kerberos se pueden pasar en esta propiedad. Hay que usar este valor con integratedSecurity en true y JavaKerberos en authenticationScheme. |
| hostNameInCertificate String null |
El nombre de host que se usará para validar el certificado TLS/SSL de SQL Server. La opción hostNameInCertificate se puede usar para especificar el nombre de host en situaciones en las que el nombre, o los nombres, usados en el certificado no coinciden con el nombre pasado a la propiedad serverName. Sin embargo, si hay una coincidencia, no se debe usar la opción hostNameInCertificate. En situaciones en las que la propiedad hostNameInCertificate no se especifica o se establece en null, el driver Microsoft JDBC para SQL Server utiliza el valor de propiedad serverName en la dirección URL de conexión como nombre de host para validar el certificado TLS/SSL de SQL Server. Nota: Como se describe en el párrafo anterior, no se recomienda establecer la opción hostNameInCertificate a menos que pueda confirmar el nombre o los nombres, en el certificado no coinciden con los pasados en la opción serverName. Nota: Esta propiedad se usa en combinación con las propiedades de cifrado/ deautenticación y la propiedad trustServerCertificate. Esta propiedad afecta a la validación de certificados si la conexión usa el cifrado TLS y trustServerCertificate se establece en "false". Asegúrese de que el valor que se pase a hostNameInCertificate coincida con el nombre común (CN) o con el nombre DNS del nombre alternativo de firmante (SAN) del certificado de servidor para que la conexión TLS se establezca correctamente. Para obtener más información, consulte el artículo Descripción de la compatibilidad con cifrado. |
| NOMBREINSTANCIA String [<=128 char] null |
Nombre de la instancia de base de datos a la que se va a conectar. Si no se especifica, se establece una conexión a la instancia predeterminada. En el caso de que se especifique el puerto e instanceName, consulte las notas referentes al puerto. Si especifica un nombre de red virtual en la propiedad de conexión Server, no puede usar la propiedad de conexión instanceName. Para obtener más información sobre la recuperación ante desastres, consulte el artículo Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres. |
| integratedSecurity boolean ["true" | "false"] false |
Establézcalo en "true" para indicar que SQL Server usa las credenciales de Windows en sistemas operativos Windows. Si el valor es "true", el controlador JDBC busca en la memoria caché de credenciales del equipo local las que se suministraron al iniciar sesión un usuario en el equipo o en la red. Establézcalo en "true" (con authenticationscheme=JavaKerberos), para indicar que SQL Server usa las credenciales de Kerberos. Para obtener más información sobre la autenticación Kerberos, vea Empleo de autenticación integrada de Kerberos para conectar con SQL Server. Establézcalo en "true" (con authenticationscheme=NTLM), para indicar que SQL Server usa las credenciales NTLM. Si el valor es "false", se deben suministrar el nombre de usuario y la contraseña. |
| IpAddressPreference String [<=128 char] IPv4First |
Preferencia de IP usada por la aplicación cliente. Con IPV4First, el controlador recorre primero las direcciones IPv4. Si ninguna dirección IPv4 se puede conectar correctamente, el controlador continúa e intenta las direcciones IPv6, si hay alguna. Con IPV6First, el controlador recorre primero las direcciones IPv6. Si ninguna dirección IPv6 se puede conectar correctamente, el controlador continúa e intenta las direcciones IPv4, si hay alguna. Con UsePlatformDefault, el controlador recorre todas las direcciones IP en sus órdenes iniciales a partir de la resolución DNS. |
| jaasConfigurationName String SQLJDBCDriver |
(Versión 6.2 y posteriores) Cada conexión a SQL Server puede usar su propio nombre de configuración de inicio de sesión JAAS para establecer la conexión Kerberos. El nombre de la entrada de configuración se puede pasar por medio de esta propiedad. Esta propiedad está pensada para su uso al crear un archivo de configuración Kerberos. De forma predeterminada, el controlador busca el nombre SQLJDBCDriver.Si no se encuentra una configuración externa, el controlador establece useDefaultCcache = true para JVM de IBM y useTicketCache = true para otros JVM. |
| keyStoreAuthentication String null |
(Versión 6.0 y posteriores) Esta propiedad identifica el almacén de claves que se va a usar para la conexión con Always Encrypted y determina un mecanismo de autenticación usado para autenticarse en el almacén de claves. El controlador admite la configuración del almacén de claves de Java sin problemas cuando establece "keyStoreAuthentication=JavaKeyStorePassword". Para usar esta propiedad, también debe establecer las propiedades keyStoreLocation y keyStoreSecret para el almacén de claves de Java. Para obtener más información sobre Always Encrypted, vea Usar Always Encrypted con el controlador JDBC. A partir de Microsoft JDBC Driver 8.4, puede establecer "keyStoreAuthentication=KeyVaultManagedIdentity" o "keyStoreAuthentication=KeyVaultClientSecret" para autenticarse en Azure Key Vault mediante identidades administradas. Para obtener más información sobre Always Encrypted, vea Usar Always Encrypted con el controlador JDBC. |
| keyStoreLocation String null |
(Versión 6.0 y posteriores) Cuando keyStoreAuthentication=JavaKeyStorePassword, la propiedad keyStoreLocation identifica la ruta al archivo del almacén de claves de Java que almacena la clave maestra de columna que se va a usar con los datos de Always Encrypted. La ruta de acceso debe incluir el nombre del archivo del almacén de claves. Para obtener más información sobre Always Encrypted, vea Usar Always Encrypted con el controlador JDBC. |
| keyStorePrincipalId String null |
(Versión 8.4 y posteriores) Cuando keyStoreAuthentication=KeyVaultManagedIdentity, la propiedad keyStorePrincipalId especifica un Id. de cliente de aplicación de Microsoft Entra válido. Para obtener más información sobre Always Encrypted, vea Usar Always Encrypted con el controlador JDBC. |
| keyStoreSecret String null |
(Versión 6.0 y posteriores) Cuando keyStoreAuthentication=JavaKeyStorePassword, la propiedad keyStoreSecret identifica la contraseña que se va a usar para el almacén de claves y la clave. Cuando uno usa el almacén de claves de Java, el almacén de claves y la contraseña de la clave deben ser los mismos. Para obtener más información sobre Always Encrypted, vea Usar Always Encrypted con el controlador JDBC. |
| lastUpdateCount boolean ["true" | "false"] true |
Un valor "true" solo devuelve el último recuento de actualizaciones de una instrucción SQL que se pasa al servidor. También se usa solo en instrucciones SELECT, INSERT o DELETE únicas para omitir otros recuentos de actualizaciones que son desencadenadores de servidor. Si se establece esta propiedad en "false", se devuelven todos los recuentos de actualizaciones, incluidos los devueltos por los desencadenadores del servidor. Nota: Esta propiedad solamente se aplica cuando se usa con los métodos executeUpdate. Todos los demás métodos execute devuelven todos los resultados y recuentos de actualización. Esta propiedad solamente afecta a los recuentos de actualizaciones devueltos por los desencadenadores del servidor. No afecta a los conjuntos de resultados o errores que resultan como parte de la ejecución del desencadenador. |
| lockTimeout int -1 |
El número de milisegundos que hay que esperar antes de que la base de datos informe del tiempo de espera para la exclusión. El comportamiento predeterminado es esperar indefinidamente. Si el usuario no ha especificado un valor para esta propiedad, este será el predeterminado para todas las instrucciones de la conexión. Alternativamente, se puede usar Statement.setQueryTimeout() para establecer el tiempo de espera para instrucciones específicas. El valor puede ser 0, lo que significa que no hay espera. |
| loginTimeout int [0..65535] 30 (versión 11.2 y superiores) 15 (versión 10.2 e inferiores) |
Número de segundos que debería esperar el controlador antes de agotar el tiempo de espera de una conexión errónea. Un valor cero indica que el tiempo de espera es el predeterminado del sistema. Este valor es de 30 segundos (el valor predeterminado en la versión 11.2 y posteriores) o 15 segundos (el valor predeterminado en la versión 10.2 y anteriores). Un valor diferente a cero es el número de segundos que debería esperar el controlador antes de agotar el tiempo de espera de una conexión errónea. Si especifica un nombre de red virtual en la propiedad de conexión Server, debe indicar un valor de tiempo de espera de tres minutos o más para dejar tiempo suficiente para que una conexión de conmutación por error se realice correctamente. Para obtener más información sobre la recuperación ante desastres, vea el artículo Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres. |
| maxResultBuffer String null |
(Versión 9.2 y posteriores) Se puede usar maxResultBuffer para establecer el número máximo de bytes que se leerán en un conjunto de resultados. Si no se especifica, se leerá todo el conjunto de resultados. El tamaño se puede especificar de dos formas: 1. Como tamaño de bytes (por ejemplo, 100, 150M, 300K, 400G)2. Como un porcentaje de la memoria máxima del montón (por ejemplo, 10p, 15pct o 20percent). |
| msiClientId String null |
(En desuso) (Versión 7.2+) El id. de cliente de la instancia administrada (MSI) que se va a usar para adquirir un accessToken al establecer una conexión con el modo de autenticación ActiveDirectoryManagedIdentity o ActiveDirectoryMSI. |
| multiSubnetFailover Boolean false |
Especifique siempre multiSubnetFailover=true para conectarse a la escucha de grupo de disponibilidad de un grupo de disponibilidad de SQL Server o a una instancia de clúster de conmutación por error de SQL Server. multiSubnetFailover=true configura el controlador para proporcionar una detección del servidor activo y una conexión con él más rápidas. Los valores posibles son true y false. Para obtener más información sobre la recuperación ante desastres, consulte el artículo Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres. Puede acceder mediante programación a la propiedad de conexión multiSubnetFailover con getPropertyInfo, getMultiSubnetFailover y setMultiSubnetFailover. Nota: A partir de Microsoft JDBC Driver 6.0 para SQL Server, ya no es necesario establecer multiSubnetFailover en "true" al conectarse a una escucha de grupo de disponibilidad. Una nueva propiedad, transparentNetworkIPResolution, habilitada de forma predeterminada, proporciona la detección y conexión al servidor (actualmente) activo. |
| packetSize int [-1 | 0 | 512..32767] 8000 |
El tamaño del paquete de red se usa para establecer la comunicación con el servidor y se especifica en bytes. El valor -1 indica que se usa el tamaño de paquete de servidor predeterminado. Un valor de 0 indica que se debe usar el valor máximo de 32767. Si esta propiedad se establece en un valor fuera del rango aceptable, se produce una excepción. Importante: No se recomienda usar la propiedad packetSize si el cifrado está habilitado (encrypt=true). De lo contrario, el controlador podría generar un error de conexión. Para obtener más información sobre esta propiedad, vea el método setPacketSize de la clase SQLServerDataSource. |
| password String [<=128 char] null |
La contraseña de la base de datos, en caso de conexión con el usuario y la contraseña de SQL. En el caso de la conexión Kerberos con el nombre y la contraseña de la entidad de seguridad, esta propiedad se establece en la contraseña de la entidad de seguridad de Kerberos. (Versión 10.2 y posteriores) Cuando authentication=ActiveDirectoryServicePrincipal, la propiedad password identifica la contraseña que se usará para la entidad de seguridad de Active Directory. |
| portNumber, port int [0..65535] 1433 |
Puerto en el que está escuchando el servidor. Si se especifica el número de puerto en la cadena de conexión, no se realiza ninguna solicitud a SQLbrowser. Si se especifican el puerto e instanceName, se establece la conexión con el puerto especificado. Pero instanceName se valida y se produce un error si no coincide con el puerto. Importante: Se recomienda especificar siempre el número de puerto, ya que es más seguro que usar SQLbrowser. |
| prepareMethod String prepexec |
(Versión 11.2.0+) Especifica el método de preparación subyacente que va a usar el controlador con instrucciones preparadas. Establézcalo para prepararse para usarlo sp_prepare como método de preparación. Configurar este valor en prepareMethod da como resultado un viaje inicial independiente a la base de datos para preparar la instrucción sin ningún valor inicial para que la base de datos tenga en cuenta en el plan de ejecución. Establezca prepexec para usarlo sp_prepexec como método de preparación. Este método combina la acción de preparación con la primera ejecución, lo que reduce los recorridos de ida y vuelta. También proporciona a la base de datos valores de parámetro iniciales que la base de datos puede tener en cuenta en el plan de ejecución. |
| queryTimeout int -1 |
El número de segundos que hay que esperar antes de que se haya superado el tiempo de espera de una consulta. El valor predeterminado es -1, lo que significa que el tiempo de espera es infinito. Establecer este valor en 0 también implica esperar de forma indefinida. |
| realm String null |
(Versión 9.4 y posteriores) Dominio de la autenticación Kerberos. Al establecer este valor, se invalidará el dominio de autenticación Kerberos que el controlador detecta automáticamente desde el dominio kerberos del servidor. |
| La replicación boolean ["true" | "false"] false |
(Versión 9.4 y posteriores) Esta configuración indica al servidor si la conexión se usa para la replicación. Si se habilita, los desencadenadores con la opción NOT FOR REPLICATION no se activarán en la conexión. |
| responseBuffering String ["full" | "adaptive"] adaptive |
Si esta propiedad se establece en "adaptive", los datos mínimos posibles se almacenan en búfer cuando es necesario. El modo predeterminado es "adaptative". Si esta propiedad se establece en "full", el conjunto de resultados completo se lee del servidor cuando se ejecuta una instrucción. Nota: Después de la versión 1.2 de JDBC, el comportamiento por defecto del almacenamiento en búfer es "adaptativo". Si desea mantener el comportamiento por defecto de la versión 1.2 en su aplicación, establezca la propiedad responseBufferring en "full" en las propiedades de la conexión, o use el método setResponseBuffering del objeto SQLServerStatement. |
| selectMethod String ["direct" | "cursor"] direct |
Si esta propiedad se establece en "cursor", se crea un cursor de base de datos para cada consulta que se cree en la conexión para los cursores TYPE_FORWARD_ONLY y CONCUR_READ_ONLY. Esta propiedad normalmente solo es necesaria si la aplicación genera conjuntos de resultados grandes que no se pueden contener completamente en la memoria del cliente. Si se establece esta propiedad en "cursor", solo se mantienen en la memoria del cliente un número limitado de filas de los conjuntos de resultados. El comportamiento predeterminado es mantener en la memoria del cliente todas las filas de los conjuntos de resultados. Este comportamiento proporciona el rendimiento más rápido cuando la aplicación va a procesar todas las filas. |
| sendStringParameters... AsUnicode boolean ["true" | "false"] true |
Si la propiedad sendStringParametersAsUnicode está establecida en "true", los parámetros String se envían al servidor en formato Unicode. Si la propiedad sendStringParametersAsUnicode está establecida en "false", los parámetros String se envían al servidor en formato no Unicode, como ASCII o MBCS. El valor predeterminado de la propiedad sendStringParametersAsUnicode es "true". Nota: La propiedad sendStringParametersAsUnicode solo se comprueba cuando se envía un valor de parámetro con los tipos CHAR, VARCHAR o LONGVARCHAR JDBC. Los nuevos métodos de caracteres nacionales de JDBC 4.0 incluyen los métodos setNString, setNCharacterStream y setNClob de las clases SQLServerPreparedStatement y SQLServerCallableStatement. Estos métodos siempre envían sus valores de parámetro al servidor en Unicode, independientemente del valor de esta propiedad. Para obtener un rendimiento óptimo con los tipos de datos CHAR, VARCHAR y LONGVARCHAR de JDBC, una aplicación debe establecer la propiedad sendStringParametersAsUnicode en "false" y usar los métodos de caracteres no nacionales setString, setCharacterStream y setClob de las clases SQLServerPreparedStatement y SQLServerCallableStatement. Cuando la aplicación establece la propiedad sendStringParametersAsUnicode en "false" y usa un método de caracteres no nacionales para acceder a los tipos de datos Unicode en el servidor (como nchar, nvarchar y ntext), se pueden perder algunos datos si la intercalación de base de datos no es compatible con los caracteres de los parámetros String pasados por el método de caracteres no nacionales. La aplicación debería usar los métodos de caracteres nacionales setNString, setNCharacterStream y setNClob de las clases SQLServerPreparedStatement y SQLServerCallableStatement para los tipos de datos NCHAR, NVARCHAR y LONGNVARCHAR de JDBC. Cambiar este valor puede afectar a la ordenación de los resultados de la base de datos. Las diferencias de ordenación se deben a diferentes reglas de ordenación para caracteres Unicode y no Unicode. |
| sendTemporalDataTypes... AsStringForBulkCopy boolean ["true" | "false"] true |
(Versión 8.4 y posteriores) Esta propiedad de conexión, al establecerse en "false", enviará los tipos de datos DATE, DATETIME, DATIMETIME2, DATETIMEOFFSET, SMALLDATETIME y TIME como sus tipos correspondientes en lugar de enviarlos como cadena. Con esta propiedad de conexión establecida en "false", el controlador acepta el formato literal de cadena predeterminado de cada tipo de datos temporal, por ejemplo los siguientes: DATE: YYYY-MM-DDDATETIME: YYYY-MM-DD hh:mm:ss[.nnn]DATETIME2: YYYY-MM-DD hh:mm:ss[.nnnnnnn]DATETIMEOFFSET: YYYY-MM-DD hh:mm:ss[.nnnnnnn] [{+/-}hh:mm]SMALLDATETIME: YYYY-MM-DD hh:mm:ssTIME: hh:mm:ss[.nnnnnnn] |
| sendTimeAsDatetime boolean ["true" | "false"] true |
Esta propiedad se agregó en JDBC Driver 3.0 para SQL Server. Establézcalo en "true" para enviar los valores de java.sql.Time al servidor como valores datetime de SQL Server. Establézcalo en "false" para enviar los valores de java.sql.Time al servidor como valores time de SQL Server. Actualmente, el valor predeterminado de esta propiedad es "true" y podría verse modificado en una versión futura. Para obtener más información sobre cómo el controlador Microsoft JDBC configura los valores java.sql.Time antes de enviarlos al servidor; consulte Configurar el modo en que los valores java.sql.Time se envían al servidor. |
| serverCertificate, server String null |
(Versión 11.2.0+) Ruta de acceso al archivo de certificado de servidor. Se usa para la validación cuando se usa el cifrado establecido en strict. El controlador admite archivos de certificado mediante el formato de archivo PEM. |
| serverName, server String null |
Equipo que ejecuta SQL Server o una base de datos de Azure SQL. También puede especificar el nombre de red virtual de un grupo de disponibilidad. Para obtener más información sobre la recuperación ante desastres, vea el artículo Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres. |
| serverNameAsACE boolean ["true" | "false"] false |
(Versión 6.0 y posteriores) Se establece en "true" para indicar que el controlador debe traducir el nombre de servidor Unicode a una codificación compatible con ASCII (Punycode) para la conexión. Si esta configuración es false, el controlador usa el nombre del servidor tal como se proporciona para conectarse. Para obtener más información sobre las características internacionales, consulte Características internacionales del controlador JDBC. |
| serverPreparedStatement... DiscardThreshold Entero 10 |
(Versión 6.2 y posteriores) Esta propiedad se puede usar para controlar cuántas acciones de descarte de instrucción preparada pendientes (sp_unprepare) pueden estar pendientes por conexión antes de que se ejecute una llamada para limpiar los identificadores pendientes del servidor. Si esta propiedad se establece en <= 1, las acciones de cancelación de preparación se ejecutan inmediatamente en la instrucción preparada CLOSE. Si se establece la propiedad en > 1, estas llamadas se procesan por lotes para evitar la sobrecarga resultante de llamar a sp_unprepare con demasiada frecuencia. |
| serverSpn String null |
(Versión 4.2 y posteriores) Esta propiedad opcional puede usarse para especificar el nombre principal de servicio (SPN) para una conexión Kerberos de Java. Se usa con authenticationScheme. Para especificar el SPN, puede ser de la forma "MSSQLSvc/fqdn:port@REALM" donde fqdn es el nombre de dominio completo, port es el número de puerto y el REALM es el dominio Kerberos de SQL Server en letras mayúsculas. Nota: @REALM es opcional si el dominio predeterminado del cliente (como se especifica en la configuración de Kerberos) es el mismo que el dominio de Kerberos para SQL Server. Para obtener más información sobre el empleo de serverSpn con Java Kerberos, vea Empleo de autenticación integrada de Kerberos para conectar con SQL Server. |
| socketFactoryClass String null |
(Versión 8.4 y posteriores) Especifica el nombre de clase de un generador de sockets personalizado que se va a usar en lugar del generador de sockets predeterminado. |
| socketTimeout int 0 |
El número de milisegundos que hay que esperar antes de que se supere el tiempo de espera de una lectura o aceptación de socket. El valor predeterminado es 0, lo que significa que el tiempo de espera es infinito. |
| statementPooling... CacheSize int 0 |
(Versión 6.4 y posteriores) Esta propiedad se puede usar para habilitar el almacenamiento en caché de identificadores de instrucción preparada en el controlador. Esta propiedad define el tamaño de la memoria caché para la agrupación de instrucciones. Esta propiedad solo se puede usar con la propiedad de conexión disableStatementPooling, que debería establecerse en "false". Al establecerse disableStatementPooling en "true" o statementPoolingCacheSize en 0 se deshabilita el almacenamiento en caché de identificadores de instrucción preparada. |
| sslProtocol String TLS |
(Versión 6.4 y posteriores) Esta propiedad se puede usar para especificar el protocolo TLS que se debe tener en cuenta durante la conexión segura. Los valores posibles son: TLS, TLSv1, TLSv1.1 y TLSv1.2. Para más información sobre el protocolo Capa de sockets seguros, consulte SSLProtocol. |
| transparentNetwork... IPResolution boolean ["true" | "false"] true |
(Versión 6.0 y posteriores) Esta propiedad permite detectar el servidor (actualmente) activo y conectarse a este con mayor rapidez. Los valores posibles son "true" y "false", donde "true" es el valor predeterminado. Antes de Microsoft JDBC Driver 6.0 para SQL Server, una aplicación tenía que establecer la cadena de conexión para incluir "multiSubnetFailover=true" a fin de indicar que se conectaba a un grupo de disponibilidad Always On. Sin establecer la palabra clave de conexión multiSubnetFailover en "true", una aplicación podría experimentar un tiempo de espera al conectarse a un grupo de disponibilidad Always On. A partir de la versión 6.0, no es necesario que una aplicación vuelva a establecer multiSubnetFailover en true. Nota: Cuando transparentNetworkIPResolution=true, el primer intento de conexión usa 500 ms como tiempo de espera. Los intentos posteriores usan la misma lógica de tiempo de espera que la propiedad multiSubnetFailover. |
| trustManagerClass String null |
(Versión 6.4 y posteriores) El nombre de clase completo de una implementación de javax.net.ssl.TrustManager personalizada. |
| trustManager... ConstructorArg String null |
(Versión 6.4 y posteriores) Un argumento opcional que se debe pasar al constructor de trustManager. Si se especifica la propiedad trustManagerClass y se solicita una conexión cifrada, se usa el TrustManager personalizado en lugar del TrustManager basado en el almacén de claves de JVM del sistema predeterminado. |
| trustServerCertificate boolean ["true" | "false"] false |
Se establece en "true" para especificar que el controlador no valida el certificado TLS/SSL del servidor. Si es "true", se confía automáticamente en el certificado TLS/SSL del servidor cuando la capa de comunicación se cifra mediante TLS. Si es "false", el controlador validará el certificado TLS/SSL del servidor. Si se produce un error en la validación del certificado de servidor, el controlador genera un error y cierra la conexión. El valor predeterminado es "false". Asegúrese de que el valor que se pase a serverName coincida exactamente con el nombre común (CN) o con el nombre DNS del nombre alternativo de firmante del certificado de servidor para que la conexión TLS/SSL se establezca correctamente. Para obtener más información, consulte el artículo Descripción de la compatibilidad con cifrado. Nota: Esta propiedad se usa en combinación con las propiedades de cifrado/ deautenticación. Esta propiedad solo afecta a la validación del certificado TLS/SSL de servidor si la conexión usa el cifrado TLS. |
| trustStore String null |
La ruta de acceso (incluido el nombre de archivo) del archivo trustStore del certificado. El archivo trustStore contiene la lista de certificados en los que el cliente confía. Cuando esta propiedad no se ha especificado o está establecida en NULL, el controlador se basa en las reglas de búsqueda del generador del administrador de confianza para determinar qué almacén de certificados se va a usar. El generador SunX509 TrustManagerFactory predeterminado intenta buscar material de confianza en el orden de búsqueda siguiente: Un archivo especificado por la propiedad del sistema "javax.net.ssl.trustStore" de JVM. Archivo <java-home>/lib/security/jssecacerts .Archivo <java-home>/lib/security/cacerts .Para obtener más información sobre la interfaz de SUNX509 TrustManager, consulte la documentación en el sitio web de Sun Microsystems. Nota: Esta propiedad solo afecta a la búsqueda trustStore de certificado si la conexión usa el cifrado TLS y la propiedad trustServerCertificate se establece en "false". |
| trustStorePassword String null |
Contraseña que se usa para comprobar la integridad de los datos trustStore. Si se establece la propiedad trustStore, pero no se establece la propiedad trustStorePassword, la integridad de trustStore no se comprueba. Cuando las propiedades trustStore y trustStorePassword no se han especificado, el controlador usa las propiedades del sistema de JVM, "javax.net.ssl.trustStore" y "javax.net.ssl.trustStorePassword". Si no se especifica la propiedad del sistema "javax.net.ssl.trustStorePassword", no se comprueba la integridad del trustStore. Si el usuario no especifica la propiedad trustStore, pero sí la propiedad trustStorePassword, el controlador JDBC usa el archivo que especifica "javax.net.ssl.trustStore" como almacén de confianza. Además, el controlador comprueba la integridad del almacén de confianza mediante el trustStorePassword especificado. Este valor es necesario cuando la aplicación cliente no quiere almacenar la contraseña en la propiedad del sistema de JVM. Nota:La propiedad trustStorePassword solo afecta a la búsqueda trustStore de certificado si la conexión usa la conexión TLS y la propiedad trustServerCertificate se establece en "false". |
| trustStoreType String JKS |
Establezca esta propiedad para especificar el tipo de almacén de confianza que se va a usar para el modo FIPS. Los valores posibles son PKCS12 o el tipo que define el proveedor FIPS. |
| useBulkCopyFor... BatchInsert boolean ["true" | "false"] false |
(Versión 9.2 y posteriores) Esta propiedad de conexión se puede habilitar para hacer uso de forma transparente de la API de copia masiva al realizar operaciones de inserción de lote mediante java.sql.PreparedStatement. Esta característica proporciona potencialmente un mejor rendimiento cuando se habilita. Esta característica está deshabilitada de forma predeterminada. Establezca esta propiedad en "true" para habilitar esta característica. Nota importante: Esta característica solo admite consultas de INSERCIÓN totalmente parametrizadas. Si otras consultas SQL se combinan con las consultas INSERT, o contienen datos en valores, la ejecución usa la operación de inserción por lotes básica. Para obtener más información sobre cómo usar esta propiedad, consulte el artículo Uso de la API de copia masiva para la operación de inserción por lotes. |
| useDefaultGSSCredential boolean ["true" | "false"] false |
(Versión 12.6+) Marca para indicar si el controlador debe crear GSSCredential en nombre del usuario para usar GSS-API nativa para la autenticación Kerberos. |
| useDefaultJaasConfig boolean ["true" | "false"] false |
(Versión 12.6+) Cuando la aplicación existe junto con las bibliotecas que configuran JAAS en el nivel de sistema, establecer esta propiedad en true permite al controlador usar esa misma configuración para realizar la autenticación Kerberos. |
| useFmtOnly boolean ["true" | "false"] false |
(Versión 7.4 y posteriores) Proporciona una forma alternativa de consultar los metadatos de parámetros del servidor. Establezca esta propiedad en "true" para especificar que el controlador debería usar la lógica SET FMTONLY al consultar los metadatos de parámetros. Esta característica está desactivada de forma predeterminada y no se recomienda usar esta propiedad, ya que SET FMTONLY está marcada para su desuso. useFmtOnly se proporciona para su uso solo como solución alternativa a los problemas y limitaciones conocidos en sp_describe_undeclared_parameters.Actualmente, esta característica solo admite consultas SELECT/INSERT/UPDATE/DELETE únicas. Si se intenta usar esta característica con consultas no admitidas o múltiples, el controlador intenta analizarlas, pero lo más probable es que se produzca una excepción.Para obtener más información sobre esta propiedad, consulte el artículo Recuperación de ParameterMetaData a través de useFmtOnly. |
| userName, usuario String [<=128 char] null |
El usuario de la base de datos, en caso de conexión con el usuario y la contraseña de SQL. En el caso de la conexión Kerberos con el nombre y la contraseña de la entidad de seguridad, esta propiedad se establece en el nombre de la entidad de seguridad de Kerberos. (Versión 10.2 y posteriores) Cuando authentication=ActiveDirectoryServicePrincipal, la propiedad userName especifica un identificador de cliente seguro y válido de Azure Active Directory. |
| workstationID String [<=128 char] <empty string> |
Identificador de la estación de trabajo. Se usa para identificar la estación de trabajo concreta en diversas herramientas de creación de perfiles y registros. Si no se especifica, se usa <empty string>. |
| xopenStates boolean ["true" | "false"] false |
Establézcalo en "true" para especificar que el controlador devuelve en las excepciones códigos de estado compatibles con XOPEN. De forma predeterminada se devuelven códigos de estado SQL 99. |
Nota
El controlador Microsoft JDBC de SQL Server toma los valores predeterminados del servidor para las propiedades de conexión salvo ANSI_DEFAULTS e IMPLICIT_TRANSACTIONS. El controlador Microsoft JDBC de SQL Server activa ANSI_DEFAULTS y desactiva IMPLICIT_TRANSACTIONS automáticamente.
Importante
Si la autenticación se establece en ActiveDirectoryPassword, la biblioteca siguiente debe incluirse en la ruta de clase: microsoft-authentication-library-for-java. Se puede encontrar en el repositorio de Maven. La forma más sencilla de descargar la biblioteca y sus dependencias es mediante Maven:
- Instale Maven en el sistema.
- Vaya a la página de GitHub del controlador.
- Descargue el archivo pom.xml.
- Ejecute el siguiente comando de Maven para descargar la biblioteca y sus dependencias:
mvn dependency:copy-dependencies