Compartir vía


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.

Palabra clave de cadena de conexión y DSN Atributo de conexión Plataforma
Addr LMW
Dirección LMW
AnsiNPW SQL_COPT_SS_ANSI_NPW LMW
APP LMW
ApplicationIntent SQL_COPT_SS_APPLICATION_INTENT LMW
AttachDBFileName SQL_COPT_SS_ATTACHDBFILENAME LMW
Autenticación SQL_COPT_SS_AUTHENTICATION LMW
AutoTranslate SQL_COPT_SS_TRANSLATE LMW
ClientCertificate LMW
ClientKey LMW
ColumnEncryption SQL_COPT_SS_COLUMN_ENCRYPTION LMW
ConnectRetryCount SQL_COPT_SS_CONNECT_RETRY_COUNT LMW
ConnectRetryInterval SQL_COPT_SS_CONNECT_RETRY_INTERVAL LMW
Base de datos SQL_ATTR_CURRENT_CATALOG LMW
Descripción LMW
Controlador LMW
DSN LMW
Encrypt SQL_COPT_SS_ENCRYPT LMW
Failover_Partner SQL_COPT_SS_FAILOVER_PARTNER W
FailoverPartnerSPN SQL_COPT_SS_FAILOVER_PARTNER_SPN W
FileDSN LMW
GetDataExtensions (v18.0+) SQL_COPT_SS_GETDATA_EXTENSIONS LMW
HostnameInCertificate (v18.0+) LMW
IpAddressPreference (v18.1+) LMW
KeepAlive (versión 17.4 y posteriores; DSN solo antes de la versión 17.8) LMW
KeepAliveInterval (versión 17.4 y posteriores; DSN solo antes de la versión 17.8) LMW
KeystoreAuthentication LMW
KeystorePrincipalId LMW
KeystoreSecret LMW
Lenguaje LMW
LongAsMax (v18.0+) SQL_COPT_SS_LONGASMAX LMW
MARS_Connection SQL_COPT_SS_MARS_ENABLED LMW
MultiSubnetFailover SQL_COPT_SS_MULTISUBNET_FAILOVER LMW
Net LMW
Network LMW
PWD LMW
QueryLog_On SQL_COPT_SS_PERF_QUERY W
QueryLogFile SQL_COPT_SS_PERF_QUERY_LOG W
QueryLogTIme SQL_COPT_SS_PERF_QUERY_INTERVAL W
QuotedId SQL_COPT_SS_QUOTED_IDENT LMW
Regional LMW
Replicación LMW
RetryExec (18.1+) LMW
SaveFile LMW
Server LMW
ServerCertificate (a partir de v18.1) LMW
ServerSPN SQL_COPT_SS_SERVER_SPN LMW
StatsLog_On SQL_COPT_SS_PERF_DATA W
StatsLogFile SQL_COPT_SS_PERF_DATA_LOG W
TransparentNetworkIPResolution SQL_COPT_SS_TNIR LMW
Trusted_Connection SQL_COPT_SS_INTEGRATED_SECURITY LMW
TrustServerCertificate SQL_COPT_SS_TRUST_SERVER_CERTIFICATE LMW
UID LMW
UseFMTONLY LMW
WSID LMW
SQL_ATTR_ACCESS_MODE
(SQL_ACCESS_MODE)
LMW
SQL_ATTR_ASYNC_DBC_EVENT W
SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE W
SQL_ATTR_ASYNC_DBC_PCALLBACK W
SQL_ATTR_ASYNC_DBC_PCONTEXT W
SQL_ATTR_ASYNC_ENABLE W
SQL_ATTR_AUTO_IPD LMW
SQL_ATTR_AUTOCOMMIT
(SQL_AUTOCOMMIT)
LMW
SQL_ATTR_CONNECTION_DEAD LMW
SQL_ATTR_CONNECTION_TIMEOUT LMW
SQL_ATTR_DBC_INFO_TOKEN LMW
SQL_ATTR_LOGIN_TIMEOUT
(SQL_LOGIN_TIMEOUT)
LMW
SQL_ATTR_METADATA_ID LMW
SQL_ATTR_ODBC_CURSORS
(SQL_ODBC_CURSORS)
LMW
SQL_ATTR_PACKET_SIZE
(SQL_PACKET_SIZE)
LMW
SQL_ATTR_QUIET_MODE
(SQL_QUIET_MODE)
LMW
SQL_ATTR_RESET_CONNECTION
(SQL_COPT_SS_RESET_CONNECTION)
LMW
SQL_ATTR_TRACE
(SQL_OPT_TRACE)
LMW
SQL_ATTR_TRACEFILE
(SQL_OPT_TRACEFILE)
LMW
SQL_ATTR_TRANSLATE_LIB
(SQL_TRANSLATE_DLL)
LMW
SQL_ATTR_TRANSLATE_OPTION
(SQL_TRANSLATE_OPTION)
LMW
SQL_ATTR_TXN_ISOLATION
(SQL_TXN_ISOLATION)
LMW
SQL_COPT_SS_ACCESS_TOKEN LMW
SQL_COPT_SS_ANSI_OEM W
SQL_COPT_SS_AUTOBEGINTXN LMW
SQL_COPT_SS_BCP LMW
SQL_COPT_SS_BROWSE_CACHE_DATA LMW
SQL_COPT_SS_BROWSE_CONNECT LMW
SQL_COPT_SS_BROWSE_SERVER LMW
SQL_COPT_SS_CEKEYSTOREDATA LMW
SQL_COPT_SS_CEKEYSTOREPROVIDER LMW
SQL_COPT_SS_CLIENT_CONNECTION_ID LMW
SQL_COPT_SS_CONCAT_NULL LMW
SQL_COPT_SS_CONNECTION_DEAD LMW
SQL_COPT_SS_DATACLASSIFICATION_VERSION (v17.4.2+) LMW
SQL_COPT_SS_ENLIST_IN_DTC W
SQL_COPT_SS_ENLIST_IN_XA LMW
SQL_COPT_SS_FALLBACK_CONNECT LMW
SQL_COPT_SS_INTEGRATED_AUTHENTICATION_METHOD LMW
SQL_COPT_SS_MUTUALLY_AUTHENTICATED LMW
SQL_COPT_SS_OLDPWD LMW
SQL_COPT_SS_PERF_DATA_LOG_NOW W
SQL_COPT_SS_PRESERVE_CURSORS LMW
SQL_COPT_SS_SPID (v17.5+) LMW
SQL_COPT_SS_TXN_ISOLATION LMW
SQL_COPT_SS_USER_DATA LMW
SQL_COPT_SS_WARN_ON_CP_ERROR LMW

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 No El certificado de servidor no está activado.
Los datos enviados entre el cliente y el servidor no están cifrados.
No No Se comprueba el certificado de servidor.
Se cifran los datos enviados entre cliente y servidor.
No El certificado de servidor no está activado.
Se cifran los datos enviados entre cliente y servidor.
No No Se comprueba el certificado de servidor.
Se cifran los datos enviados entre cliente y servidor.
No El certificado de servidor no está activado.
Se cifran los datos enviados entre cliente y servidor.
No Se comprueba el certificado de servidor.
Se cifran los datos enviados entre cliente y servidor.
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 No El certificado de servidor no está activado.
Los datos enviados entre el cliente y el servidor no están cifrados.
No No Se comprueba el certificado de servidor.
Se cifran los datos enviados entre cliente y servidor.
No El certificado de servidor no está activado.
Se cifran los datos enviados entre cliente y servidor.
No No El certificado de servidor no está activado.
Se cifran los datos enviados entre cliente y servidor.
No El certificado de servidor no está activado.
Se cifran los datos enviados entre cliente y servidor.
No Se comprueba el certificado de servidor.
Se cifran los datos enviados entre cliente y servidor.
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.
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.
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.
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