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.
Como propiedades nombre=valor en el parámetro Properties del método Connect de 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)
Notas
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 instancia de la cadena de conexión.
Además, se permiten valores desconocidos para los nombres de propiedades, el controlador JDBC no valida sus valores en relación a 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.
La siguiente tabla muestra todas las propiedades de cadena de conexión disponibles actualmente para el controlador JDBC.
Propiedad | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
applicationIntent | String | ReadWrite | Declara el tipo Workload de la aplicación cuando se conecta a un servidor. Los valores posibles son ReadOnly y ReadWrite. Para obtener más información, vea Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres. |
applicationName | String [<=128 char] | null | El nombre de la aplicación o "Controlador Microsoft JDBC para SQL Server" si no se proporciona ningún nombre. Se usa para identificar la aplicación específica en diversas herramientas de creación de perfiles y registros de SQL Server. |
authenticationScheme | String | "NativeAuthentication" | Indica qué tipo de seguridad integrada desea que use la aplicación. Los valores posibles son JavaKerberos y el valor predeterminado NativeAuthentication. Cuando se usa authenticationScheme=JavaKerberos, debe especificar el nombre de dominio completo (FQDN) en la propiedad serverName. De lo contrario, se producirá un error (No se encontró el servidor en la base de datos de Kerberos). Para obtener más información acerca de cómo usar authenticationScheme, vea Usar la autenticación integrada de Kerberos para conectar con SQL Server. |
databaseName, base de datos | 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. |
disableStatementPooling | boolean ["true"|"false"] | true | Actualmente solo se admite el valor "true". Si se estableciera en "false", se produciría una excepción. |
encrypt | boolean ["true"|"false"] | false | Se establece en "true" para especificar que SQL Server utiliza el cifrado de Capa de sockets seguros (SSL) para todos los datos enviados entre el cliente y el servidor, si el servidor tiene un certificado instalado. El valor predeterminado es false. |
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 junto con la propiedad databaseName. 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. Sin embargo, admite especificar las propiedades serverName, instanceName y portNumber de la instancia del servidor principal failoverPartner y la instancia del 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. Vea Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres para obtener más información. |
hostNameInCertificate | String | null | Nombre de host que se va a utilizar para validar el certificado SSL de SQL Server. Si la propiedad hostNameInCertificate no se ha especificado o se establece en NULL, el Controlador Microsoft JDBC para SQL Server usará el valor de propiedad serverName en la dirección URL de conexión como nombre de host para validar el certificado SSL de SQL Server. Esta propiedad se usa junto con las propiedades encrypt y trustServerCertificate. Esta propiedad afecta a la validación del certificado, únicamente en caso de que la propiedad encrypt se establezca en "true" y trustServerCertificate se establezca en "false". Asegúrese de que el valor pasado a hostNameInCertificate coincide exactamente con el Nombre común (CN) o con el nombre DNS del Nombre alternativo de sujeto (SAN) del certificado de servidor para que una conexión SSL se establezca correctamente. Para obtener más información, vea Descripción de la compatibilidad con SSL. |
instanceName | String [<=128 char] | null | Nombre de la instancia de SQL Server a la que conectarse. 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. Vea Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres para obtener más información. |
integratedSecurity | boolean ["true"|"false"] | false | Se establece en "true" para indicar que SQL Server va a usar credenciales de Windows para autenticar al usuario de la aplicación. Si el valor es "true", el controlador JDBC busca en la memoria caché de credenciales del equipo local suministradas en el equipo o en el inicio de sesión de red. Si el valor es "false", se deben suministrar el nombre de usuario y la contraseña. Esta propiedad de conexión solo se admite en los sistemas operativos de Microsoft Windows. |
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 los recuentos de actualizaciones adicionales 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. Esta propiedad solamente se aplica cuando se utiliza con los métodos executeUpdate. Todos los demás métodos execute devuelven todos los resultados y recuentos de actualizaciones. 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. Observe que 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 como mínimo para dejar tiempo suficiente para que una conexión de conmutación por error se realice correctamente. Vea Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres para obtener más información. |
multiSubnetFailover | Boolean | false | Especifique siempre multiSubnetFailover=true al conectarse al agente de escucha de grupo de disponibilidad de un grupo de disponibilidad de SQL Server 2012 o una instancia de clúster de conmutación por error de SQL Server 2012. multiSubnetFailover=true configura Controlador Microsoft JDBC para SQL Server para proporcionar una detección del servidor activo (actualmente) y una conexión al mismo más rápidas. Los valores posibles son true y false. Vea Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres para obtener más información. Puede tener acceso mediante programación a la propiedad de conexión multiSubnetFailover con getPropertyInfo, getMultiSubnetFailover y setMultiSubnetFailover. |
packetSize | int [-1| 0 | 512..32767] | 8000 | El tamaño del paquete de red se usa para establecer la comunicación con SQL Server 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. No recomendamos utilizar 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, vea el método setPacketSize de la clase SQLServerDataSource. |
password | String [<=128 char] | null | Contraseña de la base de datos. |
portNumber, puerto | int [0..65535] | 1433 | Puerto en el que está escuchando SQL Server. Si se especifica el número del 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. No obstante, se valida instanceName y se genera un error si no coincide con el puerto. Se recomienda especificar siempre el número de puerto, ya que es más seguro que usar sqlbrowser. |
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". Cuando esta propiedad se establece en "full", el conjunto de resultados completo se lee del servidor cuando se ejecuta una instrucción. Tras actualizar el controlador JDBC desde la versión 1.2, el comportamiento del almacenamiento en búfer predeterminado será "adaptive". Si su aplicación no ha configurado nunca la propiedad "responseBuffering" y quiere mantener en su aplicación el comportamiento predeterminado de la versión 1.2, debe configurar la propiedad responseBufferring en "full" bien en las propiedades de conexión o usando 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 muy grandes que no se pueden contener completamente en la memoria del cliente. Cuando se establece esta propiedad en "cursor", solo se retienen en la memoria del cliente un número limitado de filas de los conjuntos de resultados. El comportamiento predeterminado es retener 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. |
sendStringParametersAsUnicode | boolean ["true"|"false"] | true | Si la propiedad sendStringParametersAsUnicode se establece en "true", se envían parámetros String al servidor en formato Unicode. Si la propiedad sendStringParametersAsUnicode se establece en “false", se envían parámetros String al servidor en formato que no es Unicode, como ASCII/MBCS. El valor predeterminado de la propiedad sendStringParametersAsUnicode es "true". La propiedad sendStringParametersAsUnicode solo se comprueba cuando se envía un valor de parámetro con los tipos CHAR, VARCHAR o LONGVARCHAR de 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 de 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 configura la propiedad sendStringParametersAsUnicode en "false" y usa un método de caracteres no nacionales para obtener acceso a los tipos de datos Unicode en el lado del 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 nacional. Tenga en cuenta que la aplicación debería usar los métodos de caracteres no nacionales setNString, setNCharacterStream y setNClob de las clases SQLServerPreparedStatement y SQLServerCallableStatement para los tipos de datos NCHAR, NVARCHAR y LONGNVARCHAR de JDBC. |
sendTimeAsDatetime | boolean ["true"|"false"] | true | Esta propiedad se agregó en el controlador JDBC 3.0 de SQL Server . Cuando sea TRUE, los valores java.sql.Time se enviarán al servidor como valores datetime de SQL Server. Cuando sea FALSE, los valores java.sql.Time se enviarán al servidor como valores time de SQL Server. sendTimeAsDatetime también se pueden modificar mediante programación con SQLServerDataSource.setSendTimeAsDatetime. El valor predeterminado de esta propiedad podría verse modificado en una versión futura. Para obtener más información sobre cómo el Controlador Microsoft JDBC para SQL Server configura los valores java.sql.Time antes de enviarlos al servidor, vea Configurar el modo en que los valores java.sql.Time se envían al servidor. |
serverName, servidor | String | null | Equipo que ejecuta SQL Server. También puede especificar el nombre de red virtual de un grupo de disponibilidad Grupos de disponibilidad AlwaysOn. Vea Compatibilidad del controlador JDBC con alta disponibilidad y recuperación ante desastres para obtener más información. |
trustServerCertificate | boolean ["true"|"false"] | false | Establézcalo en "true" para especificar que el Controlador Microsoft JDBC para SQL Server no validará el certificado SSL de SQL Server. Si es "true", se confía automáticamente en el certificado SSL de SQL Server cuando el nivel de comunicación se cifra utilizando SSL. Si es "false", el Controlador Microsoft JDBC para SQL Server validará el certificado SSL del servidor. Si la validación del certificado de servidor da error, el controlador generará un error y terminará la conexión. El valor predeterminado es "false". Asegúrese de que el valor pasado a serverName coincide exactamente con el Nombre común (CN) o con el nombre DNS del Nombre alternativo de sujeto del certificado de servidor para que una conexión SSL se establezca correctamente. Para obtener más información, vea Descripción de la compatibilidad con SSL. Esta propiedad se usa junto con la propiedad encrypt. Esta propiedad solo afecta a la validación del certificado SSL de servidor si y solo si la propiedad encrypt se establece en "true". |
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 especifica o se establece en null, el controlador se basará en las reglas de búsqueda del generador del administrador de confianza para determinar qué almacén de certificados se usará. El generador TrustManagerFactory SunX509 predeterminado intenta buscar material de confianza en el orden de búsqueda siguiente:
Para obtener más información, consulte la documentación de la interfaz de SUNX509 TrustManager en el sitio web de Sun Microsystems. Esta propiedad solo afecta a la búsqueda trustStore de certificado, si y solo si la propiedad encrypt se establece en "true" 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 especifican, el controlador utilizará 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 establece la propiedad trustStore pero se establece la propiedad trustStorePassword, el controlador JDBC utilizará el archivo especificado por "javax.net.ssl.trustStore" como almacén de confianza y la integridad de éste se comprueba con la trustStorePassword especificada. Esto podría ser necesario cuando la aplicación cliente no desea almacenar la contraseña en la propiedad del sistema de JVM. La propiedad trustStorePassword solo afecta a la búsqueda de trustStore de certificado, si y solo si la propiedad encrypt se establece en "true" y la propiedad trustServerCertificate se establece en "false". |
userName, usuario | String [<=128 char] | null | Usuario de la base de datos. |
workstationID | String [<=128 char] | <cadena vacía> | El 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 de SQL Server. Si no se especifica ninguno, se utiliza 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. |
El Controlador Microsoft JDBC para SQL Server toma los valores predeterminados del servidor para las propiedades de conexión salvo para ANSI_DEFAULTS e IMPLICIT_TRANSACTIONS. El Controlador Microsoft JDBC para SQL Server establece ANSI_DEFAULTS en ON e IMPLICIT_TRANSACTIONS en OFF automáticamente.