Establecimiento de las propiedades de conexión

DescargarDescargar controlador para JDBC

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:

  1. Argumentos de API (como usuario y contraseña)
  2. Colección de propiedades
  3. Última instancia en la cadena de conexión Además, se permiten valores desconocidos para los nombres de propiedades, y el controlador JDBC no valida sus valores 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
aadSecurePrincipalId

String

null
(Versión 9.2 y posteriores) Cuando authentication=ActiveDirectoryServicePrincipal, la propiedad aadSecurePrincipalId especifica un identificador de cliente seguro y válido de Azure Active Directory.
aadSecurePrincipalSecret

String

null
(Versión 9.2 y posteriores) Cuando authentication=ActiveDirectoryServicePrincipal, la propiedad aadSecurePrincipalSecret identifica la contraseña que se usará para la entidad de seguridad de Active Directory.
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.
applicationIntent

String

ReadWrite
(Versión 6.0 y posteriores) Declara el tipo de carga de trabajo de la aplicación al 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, ActiveDirectoryMSI (versión 7.2 y posteriores), ActiveDirectoryInteractive (versión 9.2 y posteriores), ActiveDirectdoryServicePrincipal (versión 9.2 y posteriores), SqlPassword y NotSpecified (el predeterminado).

Use ActiveDirectoryIntegrated (versión 6.0 y posteriores) para conectarse a una base de datos SQL mediante la autenticación integrada de Windows.

Use ActiveDirectoryPassword (versión 6.0 y posteriores) para conectarse a una base de datos SQL con un nombre de entidad de seguridad y contraseña de Azure AD.

Use ActiveDirectoryMSI (versión 7.2 y posteriores) para conectarse a una base de datos SQL desde un recurso de Azure. Por ejemplo, una máquina virtual de Azure, App Service o Function App mediante la autenticación de identidad administrada (MSI).

Los dos tipos de identidades administradas que el controlador admite al usar el modo de autenticación 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 (MSI) se especifica con la propiedad de conexión msiClientId.

Use ActiveDirectoryInteractive para conectarse a una base de datos SQL mediante un flujo de autenticación interactiva.

Use ActiveDirectoryServicePrincipal (versión 9.2 y posteriores) para conectarse a una base de datos SQL con el identificador de cliente y el secreto de una identidad de entidad de servicio.

Use SqlPassword para conectarse a una base de datos 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 Active Directory para SQL Server (ADAL.DLL). ADAL 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 obtener información sobre cómo configurar la autenticación de Azure Active Directory, vea el artículo Uso de la autenticación de Azure Active Directory.
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).
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 admitirá las extensiones de archivo PFX, PEM, DER y CER.

Consulte Autenticación de certificados de cliente para escenarios de bucles invertidos.
clientKey

String

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

String

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
["Habilitado" | "Deshabilitado"]

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.
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 cargará 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, llamará 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, el único valor que se admite para este campo es HGS.

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

boolean
["true" | "false"]

false
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 "false".

A partir de la versión 6.0, hay un nuevo valor de conexión "authentication" que usa el cifrado TLS de forma predeterminada.

Para obtener más información, vea la propiedad "authentication".
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 con el servidor principal; una vez establecida la conexión inicial, se omite esta propiedad. Se debe usar con la propiedad databaseName.

Nota: El controlador no permite especificar 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. Pero sí 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.
fips

boolean
["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 quitó en la versión 6.4.0 (consulte los detalles aquí).
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.

Debe usarse con integratedSecurity como true y JavaKerberos como authenticationScheme.
hostNameInCertificate

String

null
Nombre de host que se va a usar al validar el certificado TLS/SSL de SQL Server.

Si la propiedad hostNameInCertificate no se ha especificado o está establecida en NULL, Microsoft JDBC Driver para SQL Server usa 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: Esta propiedad se usa en combinación con las propiedades de cifrado/ de autenticació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.
jaasConfigurationName

String

SQLJDBCDriver
(Versión 6.2 y posteriores) Cada conexión a SQL Server puede tener su propio archivo de configuración de inicio de sesión JAAS para establecer la conexión Kerberos. El nombre del archivo de configuración de inicio de sesión se puede pasar por medio de esta propiedad.
De forma predeterminada, el controlador establece useDefaultCcache = true para los 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 identificador de cliente de aplicación de Azure Active Directory.

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. Para usar 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
El valor "true" solamente devuelve el último recuento de actualizaciones de una instrucción SQL pasada al servidor y se puede usar en instrucciones SELECT, INSERT o DELETE individuales para omitir otros recuentos de actualizaciones generados por los desencadenadores del 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 se especifica, este valor será el predeterminado para todas las instrucciones de la conexión. 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]

15
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, que está especificado en 15 segundos de manera predeterminada. 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 un tamaño de bytes (por ejemplo, 100 B, 150 MB, 300 KB o 400 GB).
2. Como un porcentaje de la memoria máxima del montón (por ejemplo, 10 %, 15 % o 20 %).
msiClientId

String

null
(Versión 7.2 y posteriores) El identificador 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 ActiveDirectoryMSI.
multiSubnetFailover

Boolean

false
Especifique siempre multiSubnetFailover=true al 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. El valor 0 indica que se usa el valor máximo, que es 32767. Si esta propiedad se establece en un valor fuera del rango aceptable, se produce una excepción.

Importante: No recomendamos usar la propiedad packetSize cuando 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.
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.
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: Tras actualizar el controlador JDBC desde la versión 1.2, el comportamiento del almacenamiento en búfer predeterminado será "adaptive". Si quiere mantener el comportamiento predeterminado de la versión 1.2 en la aplicación, debe establecer la propiedad responseBufferring en "full" en las propiedades de conexión o con 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, como los métodos setNString, setNCharacterStream y setNClob de las clases SQLServerPreparedStatement y SQLServerCallableStatement, envían siempre sus valores de parámetro al servidor en formato Unicode con independencia de la configuración 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.
sendTemporalDataTypesAsStringForBulkCopy

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 String.

Con esta propiedad de conexión establecida en "false", el controlador solo aceptará el formato literal de cadena predeterminado de cada tipo de datos temporal, por ejemplo:

DATE: YYYY-MM-DD
DATETIME: 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:ss
TIME: 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 valores java.sql.Time al servidor como valores datetime de SQL Server.
Establézcalo en "false" para enviar valores 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 Microsoft JDBC Driver para SQL Server configura java.sql.Time antes de enviarlos al servidor, consulte Configurar el modo en que los valores java.sql.Time se envían al servidor.
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 Grupos de disponibilidad AlwaysOn. 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 este valor se establece en false, el controlador se conecta mediante el nombre de servidor tal como lo proporciona el usuario.

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 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 hacerse con el formato: "MSSQLSvc/fqdn:port@REALM", donde fqdn es el nombre de dominio completo, port es el número de puerto y 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 obtener más información sobre el protocolo SSL, consulte la página 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 AlwaysOn. 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 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/ de autenticació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 no se ha establecido la propiedad trustStore, pero sí trustStorePassword, el controlador JDBC usa el archivo que especifica "javax.net.ssl.trustStore" como almacén de confianza y la integridad de este se comprueba con la propiedad trustStorePassword especificada. 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 INSERT totalmente parametrizadas. Si otras consultas SQL combinan las consultas INSERT, o estas últimas contienen datos en valores, la ejecución utilizará 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.
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 intentará analizar dichas consultas, 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.
workstationID

String
[<=128 char]

<cadena vacía>
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 ninguna, se usa la <cadena vacía>.
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

Microsoft JDBC Driver para SQL Server toma los valores predeterminados del servidor para las propiedades de conexión, salvo para ANSI_DEFAULTS e IMPLICIT_TRANSACTIONS. Microsoft JDBC Driver para SQL Server establece ANSI_DEFAULTS en ON e IMPLICIT_TRANSACTIONS en OFF 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:

  1. Instale Maven en el sistema.
  2. Vaya a la página de GitHub del controlador.
  3. Descargue el archivo pom.xml.
  4. Ejecute el siguiente comando de Maven para descargar la biblioteca y sus dependencias: mvn dependency:copy-dependencies

Consulte también

Conexión a SQL Server con el controlador JDBC
Modo FIPS