Atributos y palabras clave de cadena de conexión y DSN
En esta página se enumeran las palabras clave para las cadenas de conexión y DSN, así como los atributos de conexión para SQLSetConnectAttr y SQLGetConnectAttr, disponibles en el controlador ODBC para SQL Server.
Atributos de conexión y palabras clave de cadena de conexión y DSN compatibles
En la tabla siguiente se enumeran los atributos y las palabras clave disponibles para cada plataforma (L: Linux; M: macOS; W: Windows). Seleccione la palabra clave o el atributo para obtener más detalles.
Estas son algunas de las palabras clave de cadena de conexión y los atributos de conexión, que no se documentan en Uso de palabras clave de cadena de conexión con SQL Server Native Client, SQLSetConnectAttr ni Función SQLSetConnectAttr.
Descripción
Se usa para describir el origen de datos.
SQL_COPT_SS_ANSI_OEM
Controla la conversión de datos de ANSI a OEM.
| Valor del atributo | Descripción |
|---|---|
| SQL_AO_OFF | (Valor predeterminado) No se realiza la traducción. |
| SQL_AO_ON | Se realiza la traducción. |
SQL_COPT_SS_AUTOBEGINTXN
Versión 17.6 y posterior Mientras que la confirmación automática está desactivada, controla la transacción BEGIN TRANSACTION automática después de ROLLBACK o COMMIT.
| Valor del atributo | Descripción |
|---|---|
| SQL_AUTOBEGINTXN_ON | (Predeterminado) Transacción BEGIN TRANSACTION automática después de ROLLBACK o COMMIT. |
| SQL_AUTOBEGINTXN_OFF | Ninguna transacción BEGIN TRANSACTION automática después de ROLLBACK o COMMIT. |
SQL_COPT_SS_FALLBACK_CONNECT
Controla el uso de conexiones de reserva de SQL Server. Ya no se admite.
| Valor del atributo | Descripción |
|---|---|
| SQL_FB_OFF | (Valor predeterminado) Las conexiones de reserva están deshabilitadas. |
| SQL_FB_ON | Las conexiones de reserva están habilitadas. |
Nuevos atributos de conexión y palabras clave de cadena de conexión
Autenticación: SQL_COPT_SS_AUTHENTICATION
Establece el modo de autenticación que se utilizará al conectarse a SQL Server. Para más información, consulta Usar Microsoft Entra ID.
| Valor de palabra clave | Valor del atributo | Descripción |
|---|---|---|
| SQL_AU_NONE | (Valor predeterminado) Sin establecer. La combinación de otros atributos determina el modo de autenticación. | |
| SqlPassword | SQL_AU_PASSWORD | Autenticación de SQL Server con nombre de usuario y contraseña. |
| ActiveDirectoryIntegrated | SQL_AU_AD_INTEGRATED | Autenticación integrada de Microsoft Entra. |
| ActiveDirectoryPassword | SQL_AU_AD_PASSWORD | Autenticación de contraseña de Microsoft Entra. |
| ActiveDirectoryInteractive | SQL_AU_AD_INTERACTIVE | Autenticación interactiva de Microsoft Entra. |
| ActiveDirectoryMsi | SQL_AU_AD_MSI | Usa las identidades administradas de Microsoft Entra para la autenticación. Para la identidad asignada por el usuario, el UID se establece en el identificador de objeto de la identidad del usuario. |
| ActiveDirectoryServicePrincipal | SQL_AU_AD_SPA | Autenticación de entidades de servicio de Microsoft Entra. UID se establece en el identificador de cliente de la entidad de servicio. PWD se establece en el secreto de cliente. |
| SQL_AU_RESET | Anular. Invalida cualquier DSN o configuración de cadena de conexión. |
Nota
Al utilizar un atributo o palabra clave Authentication, especifique explícitamente la opción Encrypt en el valor deseado de la cadena de conexión, DSN o atributo de conexión. Para más información, consulte Usar palabras clave de cadena de conexión con SQL Server Native Client.
ColumnEncryption: SQL_COPT_SS_COLUMN_ENCRYPTION
Controla el cifrado transparente de columnas (Always Encrypted). Para más información, vea Uso de Always Encrypted (ODBC).
| Valor de palabra clave | Valor del atributo | Descripción |
|---|---|---|
| habilitado | SQL_CE_ENABLED | Habilita Always Encrypted. |
| Disabled | SQL_CE_DISABLED | (Valor predeterminado) Deshabilita Always Encrypted. |
| SQL_CE_RESULTSETONLY | Habilita solamente el descifrado (los resultados y valores devueltos). |
Cifrado
Especifica si las conexiones usan el cifrado TLS a través de la red. Los posibles valores son yes/mandatory(18.0 y versiones posteriores), no/optional(18.0 y versiones posteriores) y strict(18.0 y versiones posteriores). El valor predeterminado es yes en la versión 18.0 y posteriores, y no en versiones anteriores.
Independientemente de la configuración de Encrypt, siempre se cifran las credenciales de inicio de sesión del servidor (nombre de usuario y contraseña).
Las configuraciones de Encrypt, TrustServerCertificate y Force Encryption del lado de servidor influyen en si las conexiones se cifran a través de la red. En las tablas siguientes se muestra el efecto de estas configuraciones.
ODBC Driver 18 y versiones más recientes
| Configuración de cifrado | TrustServerCertificate | Cifrado a la fuerza del servidor | Resultado |
|---|---|---|---|
| No | N.º | No | El certificado de servidor no está activado. Los datos enviados entre el cliente y el servidor no están cifrados. |
| No | Sí | No | El certificado de servidor no está activado. Los datos enviados entre el cliente y el servidor no están cifrados. |
| Sí | No | No | Se comprueba el certificado de servidor. Se cifran los datos enviados entre cliente y servidor. |
| Sí | Sí | No | El certificado de servidor no está activado. Se cifran los datos enviados entre cliente y servidor. |
| No | No | Sí | Se comprueba el certificado de servidor. Se cifran los datos enviados entre cliente y servidor. |
| No | Sí | Sí | El certificado de servidor no está activado. Se cifran los datos enviados entre cliente y servidor. |
| Sí | No | Sí | Se comprueba el certificado de servidor. Se cifran los datos enviados entre cliente y servidor. |
| Sí | Sí | Sí | El certificado de servidor no está activado. Se cifran los datos enviados entre cliente y servidor. |
| Strict | - | - | TrustServerCertificate se omite. Se comprueba el certificado de servidor. Se cifran los datos enviados entre cliente y servidor. |
Nota
Estricto solo está disponible en servidores que admiten conexiones TDS 8.0.
ODBC Driver 17 y versiones anteriores
| Configuración de cifrado | TrustServerCertificate | Cifrado a la fuerza del servidor | Resultado |
|---|---|---|---|
| No | N.º | No | El certificado de servidor no está activado. Los datos enviados entre el cliente y el servidor no están cifrados. |
| No | Sí | No | El certificado de servidor no está activado. Los datos enviados entre el cliente y el servidor no están cifrados. |
| Sí | No | No | Se comprueba el certificado de servidor. Se cifran los datos enviados entre cliente y servidor. |
| Sí | Sí | No | El certificado de servidor no está activado. Se cifran los datos enviados entre cliente y servidor. |
| No | No | Sí | El certificado de servidor no está activado. Se cifran los datos enviados entre cliente y servidor. |
| No | Sí | Sí | El certificado de servidor no está activado. Se cifran los datos enviados entre cliente y servidor. |
| Sí | No | Sí | Se comprueba el certificado de servidor. Se cifran los datos enviados entre cliente y servidor. |
| Sí | Sí | Sí | El certificado de servidor no está activado. Se cifran los datos enviados entre cliente y servidor. |
TransparentNetworkIPResolution: SQL_COPT_SS_TNIR
Controla la característica de resolución de IP de red transparente, que interactúa con MultiSubnetFailover para permitir intentos de reconexión más rápidos. Para más información, vea Uso de resolución de IP de red transparente.
| Valor de palabra clave | Valor del atributo | Descripción |
|---|---|---|
| habilitado | SQL_IS_ON | (Predeterminado) Habilita la resolución de IP de red transparente. |
| Disabled | SQL_IS_OFF | Deshabilita la resolución de IP de red transparente. |
UseFMTONLY
Controla el uso de SET FMTONLY para los metadatos al conectarse a SQL Server 2012 y versiones más recientes.
| Valor de palabra clave | Descripción |
|---|---|
| No | (Valor predeterminado) Si está disponible, use sp_describe_first_result_set para los metadatos. |
| Sí | Use SET FMTONLY para los metadatos. |
Replicación
Permite especificar el uso de un inicio de sesión de replicación en la versión 17.8 y posteriores de ODBC Driver.
| Valor de palabra clave | Descripción |
|---|---|
| No | (Valor predeterminado) No se usa el inicio de sesión de replicación. |
| Sí | Los desencadenadores con la opción NOT FOR REPLICATION no se activan en la conexión. |
RetryExec
La lógica de reintento configurable está disponible a partir de la versión 18.1. Vuelve a ejecutar automáticamente llamadas a funciones ODBC específicas en función de condiciones configurables. Esta característica puede habilitarse a través de la cadena de conexión mediante la palabra clave RetryExec, junto con una lista de reglas de reintento. Cada regla de reintento tiene tres componentes separados por dos puntos: una coincidencia de errores, una directiva de reintento y una coincidencia de consulta.
La coincidencia de consulta determina la regla de reintento que se va a usar para una ejecución determinada y se hace coincidir con el texto del comando entrante (SQLExecDirect) o el texto del comando preparado en el objeto de instrucción (SQLExecute). Si hay más de una regla que coincide, se usa la primera coincidencia de la lista. Este comportamiento permite que las reglas se muestren en orden creciente de generalidad. Si ninguna regla coincide, no se aplica ningún reintento.
Cuando la ejecución produce un error y existe una regla de reintento aplicable, se usa su coincidencia de error para determinar si debe reintentarse la ejecución.
El valor de la palabra clave RetryExec es una lista de reglas de reintento separadas por el símbolo de punto y coma.
RetryExec={rule1;rule2}
A continuación se indica una regla de reintento: <errormatch>:<retrypolicy>:<querymatch>
Coincidencia de error: una lista separada por comas de códigos de error. Por ejemplo, especificar 1000,2000 serían los códigos de error que desea reintentar.
Directiva de reintento: especifica el retraso hasta el siguiente reintento. El primer parámetro sería el número de reintentos, mientras que el segundo sería el retraso. Por ejemplo , 3,10+7 serían 3 intentos a partir de 10 y cada reintento subsiguiente se incrementaría en 7 segundos. Si no se especifica +7, cada reintento subsiguiente se duplica de forma exponencial.
Coincidencia de consulta: especifica la consulta con la que hay que coincidir. Si no se especifica nada, se aplica a todas las consultas. Especificar SELECT indicaría que se trata de todas las consultas que empiezan por select.
Combinar los tres componentes anteriores para usarlos en una cadena de conexión sería:
RetryExec={1000,2000:3,10+7:SELECT}
Lo que significaría: "Para los errores 1000 y 2000, en una consulta que empieza por SELECT. Vuelva a intentarlo dos veces con un retraso inicial de 10 segundos y agregue 7 segundos a cada intento subsiguiente"
Ejemplos
40501,40540:4,5
Para los errores 40501 y 40540, vuelve a intentarlo hasta 4 veces, con un retraso inicial de 5 segundos y duplicación exponencial entre cada reintento. Esta regla se aplica a todas las consultas.
49919:2,10+:CREATE
Para el error 49919 en una consulta que comienza con CREATE, vuelve a intentarlo como máximo dos veces, inicialmente después de 10 segundos y, a continuación, 20 segundos.
49918,40501,10928:5,10+5:SELECT c1
En el caso de los errores 49918, 40501 y 10928 en consultas que comiencen con SELECT c1, vuelve a intentarlo hasta 5 veces, esperando 10 segundos en el primer reintento y después incrementando la espera en 5 segundos.
Las tres reglas anteriores se pueden especificar juntas en la cadena de conexión de la siguiente manera:
RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}
Ten en cuenta que la regla más general (match-all) se ha colocado al final, para permitir que las dos reglas más específicas que la preceden coincidan con sus respectivas consultas.
ClientCertificate
Especifica el certificado que se usará para la autenticación. Las opciones son:
| Valor de la opción | Descripción |
|---|---|
sha1:<hash_value> |
El controlador ODBC utiliza el hash SHA1 para localizar un certificado en el Almacén de certificados de Windows |
subject:<subject> |
El controlador ODBC utiliza subject para localizar un certificado en el Almacén de certificados de Windows |
file:<file_location>[,password:<password>] |
El controlador ODBC utiliza un archivo de certificado. |
En caso de que el certificado esté en formato PFX y la clave privada dentro del certificado PFX esté protegida por contraseña, se requiere la palabra clave de contraseña. Para los certificados en formatos PEM y DER, se requiere el atributo ClientKey
ClientKey
Especifica una ubicación de archivo de la clave privada para certificados PEM o DER especificados por el atributo ClientCertificate. Formato:
| Valor de la opción | Descripción |
|---|---|
file:<file_location>[,password:<password>] |
Especifica la ubicación del archivo de clave privada. |
En caso de que el archivo de clave privada esté protegido por contraseña, se requiere la palabra clave de contraseña. Si la contraseña contiene algún carácter «,», se agrega de manera automática un carácter «,» adicional inmediatamente después de cada uno de ellos. Por ejemplo, si la contraseña es «a,b,c», la contraseña con escape presente en la cadena de conexión es «a,,b,,c».
HostnameInCertificate
Especifica el nombre de host que se espera en el certificado de servidor cuando se negocia el cifrado, si no es el mismo que el valor predeterminado derivado de Addr/Address/Server. La opción HostnameInCertificate se omite cuando se especifica la opción ServerCertificate.
IpAddressPreference
Esta opción está disponible a partir de la versión 18.1 y permite que el usuario especifique el tipo de dirección IP que quiere priorizar para las conexiones. Las opciones posibles son «IpAddress= [ IPv4First | IPv6First | UsePlatformDefault]». UsePlatformDefault se conecta a direcciones en el orden en que las facilita la llamada del sistema para resolver el nombre del servidor. El valor predeterminado es IPv4First, que corresponde al comportamiento en versiones anteriores.
ServerCertificate
Esta opción está disponible a partir de la versión 18.1 y se puede usar con el modo de cifrado estricto. La palabra clave ServerCertificate se usa para especificar la ruta de acceso a un archivo de certificado que debe coincidir con el certificado TLS/SSL de SQL Server. La coincidencia se realiza en lugar de la validación de certificados estándar (expiración, nombre de host, cadena de confianza, etc.). Los formatos de certificado aceptados son PEM, DER y CER. Si se especifica, el certificado de SQL Server se comprueba verificando si la palabra ServerCertificate proporcionada constituye una coincidencia exacta.
SQL_COPT_SS_ACCESS_TOKEN
Permite el uso de un token de acceso de Microsoft Entra para la autenticación. Para más información, consulta Usar Microsoft Entra ID.
| Valor de atributo | Descripción |
|---|---|
| NULL | (Valor predeterminado) No se proporciona ningún token de acceso. |
| ACCESSTOKEN* | Puntero a un token de acceso. |
SQL_COPT_SS_CEKEYSTOREDATA
Se comunica con una biblioteca de proveedor de almacén de claves cargada. Controla el cifrado transparente de columnas (Always Encrypted). Este atributo no tiene ningún valor predeterminado. Para más información, vea Proveedores de almacén de claves personalizados.
| Valor del atributo | Descripción |
|---|---|
| CEKEYSTOREDATA * | Estructura de datos de comunicación para la biblioteca de proveedor de almacén de claves |
SQL_COPT_SS_CEKEYSTOREPROVIDER
Carga una biblioteca de proveedor de almacén de claves para Always Encrypted o recupera los nombres de las bibliotecas de proveedor de almacén de claves cargadas. Para más información, vea Proveedores de almacén de claves personalizados. Este atributo no tiene ningún valor predeterminado.
| Valor del atributo | Descripción |
|---|---|
| char * | Ruta de acceso a una biblioteca de proveedor de almacén de claves |
SQL_COPT_SS_ENLIST_IN_XA
Para habilitar transacciones XA con un procesador de transacciones (TP) compatible con XA, la aplicación debe llamar a SQLSetConnectAttr con SQL_COPT_SS_ENLIST_IN_XA establecido y un puntero a un objeto XACALLPARAM. Esta opción es compatible con Windows (17.3 y versiones posteriores), Linux y macOS.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER); // XACALLPARAM *param
Para asociar una transacción XA con una conexión ODBC solamente, proporcione TRUE o FALSE con SQL_COPT_SS_ENLIST_IN_XA, en lugar del puntero al llamar a SQLSetConnectAttr . Esta configuración solo es válida en Windows y no se puede usar para especificar operaciones XA mediante una aplicación cliente.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, (SQLPOINTER)TRUE, 0);
| Value | Descripción | Plataformas |
|---|---|---|
| Objeto XACALLPARAM* | El puntero al objeto XACALLPARAM. |
Windows, Linux y macOS |
| TRUE | Asocia la transacción XA con la conexión ODBC. Todas las actividades de base de datos relacionadas se realizan bajo la protección de la transacción XA. | Windows |
| FALSE | Desasocia la transacción XA con la conexión ODBC. | Windows |
Para más información sobre las transacciones XA, vea Uso de las transacciones XA.
SQL_COPT_SS_LONGASMAX
Permite enviar datos de tipo largo a los servidores como datos de tipo máximo.
| Valor del atributo | Descripción |
|---|---|
| No | (Valor predeterminado) No convierta tipos largos en tipos máximos al enviar. |
| Sí | Convierte datos de tipos largos a tipos máximos al enviar. |
SQL_COPT_SS_SPID
Recupera el identificador de proceso de servidor de la conexión. Esta propiedad es equivalente a la variable @@SPID de T-SQL, con la salvedad de que no incurre en un recorrido de ida y vuelta adicional al servidor.
| Valor del atributo | Descripción |
|---|---|
| DWORD | SPID |