Establecer 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.
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)
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
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 que se resuelven en el mismo orden que los nombres de propiedades 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 |
|---|---|---|---|
applicationName |
String [<=128 char] |
null |
Nombre de la aplicación o "controlador JDBC de Microsoft SQL Server" si no se le asigna un nombre. Se usa para identificar la aplicación específica en diversas herramientas de creación de perfiles y registros de 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. 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. 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. |
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 ha establecido en null, el controlador JDBC de Microsoft SQL Server 2005 utilizará el valor de la propiedad serverName en la dirección URL de conexión como el nombre de host para validar el certificado SSL de SQL Server. Nota 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". |
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. |
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. Nota 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. Nota 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 |
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. |
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 intervalo aceptable, se produce una excepción. Nota 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, instanceName se valida y se devuelve un error si no coincide con el puerto. Nota 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. Nota 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 está configurada en "true", los parámetros String se envían al servidor en formato Unicode. Si la propiedad sendStringParametersAsUnicode está configurada en “false", los parámetros String se envían al servidor en formato que no es Unicode, como ASCII/MBCS. El valor predeterminado de la propiedad sendStringParametersAsUnicode es "true". Nota La propiedad sendStringParametersAsUnicode solamente 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 debería configurar 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 configurar los valores java.sql.Time del controlador JDBC de SQL Server 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. |
userName, usuario |
String [<=128 char] |
null |
Usuario de la base de datos. |
trustServerCertificate |
boolean ["true"|"false"] |
false |
Establézcalo en "true" para especificar que el controlador JDBC de Microsoft 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 JDBC de Microsoft 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". Nota Esta propiedad se usa junto con la propiedad encrypt. Esta propiedad solo afecta a la validación de 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. Nota 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. Nota 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". |
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. |
Nota
El controlador JDBC de SQL Server toma los valores predeterminados del servidor para las propiedades de conexión salvo ANSI_DEFAULTS e IMPLICIT_TRANSACTIONS. El controlador JDBC de SQL Server activa ANSI_DEFAULTS y desactiva IMPLICIT_TRANSACTIONS automáticamente.