Nota
L'accés a aquesta pàgina requereix autorització. Podeu provar d'iniciar la sessió o de canviar els directoris.
L'accés a aquesta pàgina requereix autorització. Podeu provar de canviar els directoris.
Este artículo enumera las palabras clave para cadenas de conexión y DSNs, y los atributos de conexión para SQLSetConnectAttr y SQLGetConnectAttr, disponibles en el controlador ODBC para SQL Server.
Palabras clave de DSN y de cadena de conexión admitidas, y atributos de conexión
La siguiente tabla enumera las palabras clave y atributos 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 palabras clave de cadena de conexión y atributos de conexión que no están documentados en Using Connection String Keywords with SQL Server Native Client, SQLSetConnectAttr y SQLSetConnectAttr Function.
Descripción
Describe la fuente de datos.
SQL_COPT_SS_ANSI_OEM
Controla la conversión de datos de ANSI a OEM.
| Valor de atributo | Descripción |
|---|---|
SQL_AO_OFF (valor predeterminado) |
La traducción no está terminada. |
SQL_AO_ON |
Se realiza la traducción. |
SQL_COPT_SS_AUTOBEGINTXN
A partir de la versión 17.6, con autocommit desactivado, utiliza esta opción para controlar automáticamente BEGIN TRANSACTION después de ROLLBACK o COMMIT.
| Valor de atributo | Descripción |
|---|---|
SQL_AUTOBEGINTXN_ON (valor predeterminado) |
Automático BEGIN TRANSACTION después ROLLBACK o COMMIT. |
SQL_AUTOBEGINTXN_OFF |
No hay automático BEGIN TRANSACTION después ROLLBACK ni COMMIT. |
SQL_COPT_SS_FALLBACK_CONNECT
Controla el uso de conexiones de reserva de SQL Server. Esta opción ya no está soportada.
| Valor de atributo | Descripción |
|---|---|
SQL_FB_OFF (valor predeterminado) |
Desactiva las conexiones de respaldo. |
SQL_FB_ON |
Activa conexiones de respaldo. |
Nuevas palabras clave y nuevos atributos 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 obtener más información, vea Uso de Microsoft Entra ID con ODBC Driver.
| Valor de palabra clave | Valor de 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. |
ActiveDirectoryInteractive |
SQL_AU_AD_INTERACTIVE |
Autenticación interactiva de Microsoft Entra. |
ActiveDirectoryMsi |
SQL_AU_AD_MSI |
Autenticación de identidad administrada de Microsoft Entra Para la identidad asignada por el usuario, UID se establece como el ID del objeto de la identidad del usuario. |
ActiveDirectoryServicePrincipal |
SQL_AU_AD_SPA |
Autenticación de entidades de servicio de Microsoft Entra.
UID se establece como el ID del cliente del principal de servicio.
PWD está configurado como el secreto del cliente. |
ActiveDirectoryPassword |
SQL_AU_AD_PASSWORD |
[OBSOLETO] Autenticación de contraseña de Microsoft Entra.ActiveDirectoryPassword está en desuso. Para obtener más información, consulte ActiveDirectoryPassword ha quedado obsoleto. |
SQL_AU_RESET |
Anular. Invalida cualquier DSN o configuración de cadena de conexión. |
Nota
Al usar la palabra clave Authentication o el atributo, especifique explícitamente la configuración Encrypt con el valor deseado en la cadena de conexión, el DSN o el 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 obtener más información, vea Using Always Encrypted with the ODBC Driver for SQL Server (Uso de Always Encrypted con el controlador ODBC para SQL Server).
| Valor de palabra clave | Valor de atributo | Descripción |
|---|---|---|
Enabled |
SQL_CE_ENABLED |
Habilita Always Encrypted. |
Disabled (valor predeterminado) |
SQL_CE_DISABLED |
Desactiva siempre cifrado. |
SQL_CE_RESULTSETONLY |
Habilita solo el descifrado (resultados y valores devueltos). |
ConcatNullYieldsNull: SQL_COPT_SS_CONCAT_NULL
Controla el uso del tratamiento ISO de NULL al concatenar cadenas. Para obtener más información, consulte SET CONCAT_NULL_YIELDS_NULL.
| Valor de palabra clave | Valor de atributo | Descripción |
|---|---|---|
Yes (valor predeterminado) |
SQL_CN_ON |
NULL concatenado da como resultado NULL. |
No |
SQL_CN_OFF |
NULL la concatenación produce una cadena. |
Cifrar
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 Encrypt, TrustServerCertificate y del lado del servidor Force Encryption determinan si las conexiones están cifradas en 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 | No | No | No se comprueba el certificado del servidor. Los datos enviados entre el cliente y el servidor no están cifrados. |
| No | Sí | No | No se comprueba el certificado del servidor. 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 | No se comprueba el certificado del servidor. 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í | No se comprueba el certificado del servidor. 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í | No se comprueba el certificado del servidor. Se cifran los datos enviados entre cliente y servidor. |
| Estricto | - | - |
TrustServerCertificate se pasa por alto. Se comprueba el certificado de servidor.Se cifran los datos enviados entre cliente y servidor. |
Nota
El Strict valor solo está disponible contra servidores que soportan conexiones TDS 8.0.
ODBC Driver 17 y versiones anteriores
| Configuración de cifrado | TrustServerCertificate | Cifrado a la fuerza del servidor | Resultado |
|---|---|---|---|
| No | No | No | No se comprueba el certificado del servidor. Los datos enviados entre el cliente y el servidor no están cifrados. |
| No | Sí | No | No se comprueba el certificado del servidor. 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 | No se comprueba el certificado del servidor. Se cifran los datos enviados entre cliente y servidor. |
| No | No | Sí | No se comprueba el certificado del servidor. Se cifran los datos enviados entre cliente y servidor. |
| No | Sí | Sí | No se comprueba el certificado del servidor. 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í | No se comprueba el certificado del servidor. Se cifran los datos enviados entre cliente y servidor. |
TransparentNetworkIPResolution: SQL_COPT_SS_TNIR
Controla la funcionalidad de resolución de IP de red transparente, un mecanismo de respaldo heredado multi-IP para el controlador ODBC. Esta configuración no afecta a la secuencia de conexión cuando MultiSubnetFailover=Yes, que es la recomendada para Azure SQL Database, Azure SQL Managed Instance, base de datos SQL en Microsoft Fabric, escuchadores de grupos de disponibilidad y instancias de clúster de conmutación por error. Para más información, consulte Usar resolución IP transparente de red con el controlador ODBC o Alta disponibilidad y recuperación ante desastres.
| Valor de palabra clave | Valor de atributo | Descripción |
|---|---|---|
Enabled (valor predeterminado) |
SQL_IS_ON |
Permite una resolución IP transparente de red. |
Disabled |
SQL_IS_OFF |
Deshabilita la resolución transparente de IP de red. |
UseFMTONLY
Controla el uso de SET FMTONLY para metadatos al conectarse a SQL Server 2012 y versiones posteriores.
| Valor de palabra clave | Descripción |
|---|---|
No (valor predeterminado) |
Úsalo sp_describe_first_result_set como metadatos si está disponible. |
Yes |
Use SET FMTONLY para 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 utiliza el inicio de sesión de replicación. |
Yes |
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. Activa esta función a través de la cadena de conexión usando la RetryExec palabra clave, junto con una lista de reglas de reintento. Cada regla de reintento tiene tres componentes separados por dos puntos: una coincidencia de error, una política de reintento y una coincidencia de consulta.
La coincidencia de la consulta determina la regla de reintento que se usará para una ejecución concreta. Coincide con el texto de comando entrante (SQLExecDirect) o el texto de comando preparado en el objeto de instrucción (SQLExecute). Si más de una regla coincide, se utiliza la primera regla de coincidencia en la lista. Este comportamiento permite listar las reglas en orden de generalidad creciente. Si ninguna regla coincide, no se aplica ningún reintento.
Cuando la ejecución resulta en un error y hay una regla de reintento aplicable, su coincidencia de error determina si la ejecución debe intentarse de nuevo.
El valor de la RetryExec palabra clave es una lista de reglas de reintento separadas por punto y coma.
RetryExec={rule1;rule2}
A continuación se indica una regla de reintento: <errormatch>:<retrypolicy>:<querymatch>
Coincidencia de errores: Una lista de códigos de error separada por comas. Por ejemplo, especificar
1000,2000lista los códigos de error que quieres volver a intentar.Política de reintentos: Especifica el retraso hasta el siguiente intento. El primer parámetro es el número de intentos, y el segundo parámetro es el retardo. Por ejemplo,
3,10+7significa tres intentos empezando en 10, y cada intento siguiente incrementa 7 segundos. Si no especificas+7, cada intento siguiente se duplica exponencialmente.Coincidencia de consulta: Especifica la consulta que quieres hacer coincidir. Si no especificas nada, la regla se aplica a todas las consultas. Especificar
SELECTsignifica todas las consultas que comienzan conSELECT.
Combinando los tres componentes para usarlos en una cadena de conexión:
RetryExec={1000,2000:3,10+7:SELECT}
Esta regla significa: Para errores 1000 y 2000 en una consulta que empiece con SELECT, inténtalo dos veces con un retraso inicial de 10 segundos, y añade 7 segundos por cada intento siguiente.
Ejemplos
40501,40540:4,5
Para errores 40501 y 40540, intenta hasta cuatro veces, con un retraso inicial de 5 segundos y duplicación exponencial entre cada intento. Esta regla se aplica a todas las consultas.
49919:2,10+:CREATE
Para un error 49919 en una consulta que empiece con CREATE, inténtalo como máximo dos veces, primero después de 10 segundos y luego 20 segundos.
49918,40501,10928:5,10+5:SELECT c1
Para errores 49918, , y 10928 en consultas que comienzan con SELECT c1, reintenta hasta cinco veces, esperando 10 segundos en el primer intento y aumentando la espera en 405015 segundos después.
Especifique las tres reglas anteriores 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}
Coloca la regla más general (que coincida con todo) al final, para permitir que las otras dos reglas más específicas se apliquen a sus respectivas consultas.
Certificado de cliente
Especifica el certificado para la autenticación con conexiones de loopback. Esta opción solo está disponible en SQL Server en Linux. 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 la Tienda de Certificados de Windows. |
subject:<subject> |
El controlador ODBC utiliza el sujeto para localizar un certificado en la Tienda de Certificados de Windows. |
file:<file_location>[,password:<password>] |
El controlador ODBC utiliza un archivo de certificado. |
Si el certificado está en PFX formato y la clave privada dentro del PFX certificado está protegida por contraseña, incluye la password palabra clave. Para los certificados en formatos PEM y DER, incluya el atributo ClientKey.
ClientKey
Especifica la ubicación del archivo de la clave privada para PEM o DER certificados especificados por el ClientCertificate atributo. Formato:
| Valor de la opción | Descripción |
|---|---|
file:<file_location>[,password:<password>] |
Especifica la ubicación del archivo de clave privada. |
Si el archivo de clave privada está protegido por contraseña, incluye la password palabra clave. Si la contraseña contiene algún , carácter, añade un carácter extra , inmediatamente después de cada uno. Por ejemplo, si la contraseña es a,b,c, la contraseña escapada en la cadena de conexión es a,,b,,c.
HostnameInCertificate
Especifica el nombre de host a esperar en el certificado del servidor cuando se negocia el cifrado , si es diferente del valor predeterminado derivado de Addr, Address, o Server. Se ignora la opción HostnameInCertificate cuando se usa la opción ServerCertificate.
Preferencia de dirección IP
A partir de la versión 18.1, utiliza esta opción para especificar el tipo de dirección IP que debes priorizar para las conexiones.
Las opciones posibles son IPv4First, IPv6First, y UsePlatformDefault.
UsePlatformDefault se conecta a las direcciones en el orden en el que las proporciona la llamada al sistema para resolver el nombre del servidor. El valor por defecto es IPv4First, que corresponde al comportamiento de versiones anteriores.
Certificado del servidor
A partir de la versión 18.1, utiliza esta opción con modo de cifrado estricto. Utiliza la ServerCertificate palabra clave para especificar la ruta hacia un archivo de certificado que coincida con el certificado TLS/SSL de SQL Server. La coincidencia se realiza en lugar de la validación estándar de certificados (caducidad, nombre de host, cadena de confianza, etc.). Los formatos de certificado permitidos son PEM, DER y CER. Si especificas esta opción, el certificado de SQL Server se comprueba comprobando si el ServerCertificate proporcionado es una coincidencia exacta.
SQL_COPT_SS_ACCESS_TOKEN
Utiliza un token de acceso Microsoft Entra para la autenticación. Para obtener más información, vea Uso de Microsoft Entra ID con ODBC Driver.
| Valor de atributo | Descripción |
|---|---|
NULL (valor predeterminado) |
No se suministra 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 de atributo | Descripción |
|---|---|
CEKEYSTOREDATA * |
Estructura de datos de comunicación para la biblioteca del 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 de 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 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 únicamente a una conexión ODBC, 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);
| Valor | Descripción | Plataformas |
|---|---|---|
XACALLPARAM objeto* |
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 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
Envía tipos de datos largos a los servidores como tipos de datos máximos.
| Valor de atributo | Descripción |
|---|---|
No (valor predeterminado) |
No conviertas tipos largos en tipos máximos al enviar. |
Yes |
Convierte los datos de tipos largos a tipos máximos al enviarlos. |
SQL_COPT_SS_SPID
Recupera el identificador de sesión 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 de atributo | Descripción |
|---|---|
DWORD |
SPID |