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.

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.

SQL_COPT_SS_FALLBACK_CONNECT

Controla el uso de conexiones de reserva de SQL Server. Ya no se admite.

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.

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).

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

ODBC Driver 17 y versiones anteriores

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.

UseFMTONLY

Controla el uso de SET FMTONLY para los metadatos al conectarse a SQL Server 2012 y versiones más recientes.

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.

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:

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:

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.

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.

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.

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);

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.

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.