DSN e palavras-chave e atributos da cadeia de conexão

Este artigo lista as palavras-chave para strings de conexão e DSNs, e os atributos de conexão para SQLSetConnectAttr e SQLGetConnectAttr, disponíveis no ODBC Driver for SQL Server.

Palavras-chave e atributos de conexão suportados por DSN e cadeia de conexão

A tabela a seguir lista as palavras-chave e atributos disponíveis para cada plataforma (L: Linux; M: macOS; W: Windows). Selecione a palavra-chave ou o atributo para obter mais detalhes.

Aqui estão algumas palavras-chave de cadeia de conexão e atributos de conexão que não estão documentados em Using Connection String Keywords with SQL Server Native Client, SQLSetConnectAttr e SQLSetConnectAttr Function.

Descrição

Descreve a fonte de dados.

SQL_COPT_SS_ANSI_OEM

Controla a conversão de dados de ANSI para OEM.

SQL_COPT_SS_AUTOBEGINTXN

A partir da versão 17.6, com o autocommit desativado, use esta opção para controlar a execução automática de BEGIN TRANSACTION após ROLLBACK ou COMMIT.

SQL_COPT_SS_FALLBACK_CONNECT

Controla o uso de conexões de contingência do SQL Server. Essa opção não é mais suportada.

Novas palavras-chave de cadeia de conexão e atributos de conexão

Autenticação – SQL_COPT_SS_AUTHENTICATION

Define o modo de autenticação a ser usado ao conectar-se ao SQL Server. Para obter mais informações, consulte Usar o Microsoft Entra ID com o driver ODBC.

ColumnEncryption – SQL_COPT_SS_COLUMN_ENCRYPTION

Controla a criptografia transparente de colunas (Always Encrypted). Para obter mais informações, veja Como usar Always Encrypted com o Windows ODBC Driver for SQL Server.

ConcatNullYieldsNull - SQL_COPT_SS_CONCAT_NULL

Controla o uso do tratamento ISO de NULL ao concatenar cadeias de caracteres. Para obter mais informações, consulte SET CONCAT_NULL_YIELDS_NULL.

Encrypt

Especifica se as conexões usam criptografia TLS na rede. Os valores possíveis são: yes/mandatory(18.0+), no/optional(18.0+) e strict(18.0+). O valor padrão é yes na versão 18.0 e superiores e no nas versões anteriores.

Independentemente da configuração de Encrypt, as credenciais de logon do servidor (nome de usuário e senha) são sempre criptografadas.

As configurações de Encrypt, TrustServerCertificate e Force Encryption do lado do servidor determinam se as conexões são criptografadas na rede. As tabelas a seguir mostram o efeito dessas configurações.

Driver ODBC 18 e mais recentes

ODBC Driver 17 e anteriores

TransparentNetworkIPResolution – SQL_COPT_SS_TNIR

Controla a funcionalidade Transparent Network IP Resolution, um mecanismo legado de fallback com vários IPs para o driver ODBC. Essa configuração não afeta a sequência da conexão quando MultiSubnetFailover=Yes, que é a configuração recomendada para o Banco de Dados SQL do Azure, o Instância Gerenciada de SQL do Azure, o Banco de Dados SQL no Microsoft Fabric, ouvintes de grupo de disponibilidade e instâncias de cluster de failover. Para mais informações, veja Usar resolução transparente de IP de rede com o driver ODBC ou Alta disponibilidade e recuperação em desastres.

UseFMTONLY

Controla o uso de SET FMTONLY para metadados ao conectar-se ao SQL Server 2012 e posteriores.

Replicação

Especifica o uso de um logon de replicação no Driver ODBC versão 17.8 e mais recente.

RetryExec

A lógica de repetição configurável está disponível a partir da versão 18.1. Ela reexecuta automaticamente chamadas de função ODBC específicas com base em condições configuráveis. Ative este recurso por meio da cadeia de conexão usando a palavra-chave RetryExec, juntamente com uma lista de regras de repetição. Cada regra de retentativa possui três componentes separados por dois pontos: uma correspondência de erro, uma política de retentativa e uma correspondência de consulta.

A correspondência da consulta determina qual regra de nova tentativa usar para uma determinada execução. Ele corresponde ao texto do comando recebido (SQLExecDirect) ou ao texto do comando preparado no objeto da instrução (SQLExecute). Se mais de uma regra coincidir, a primeira regra correspondente da lista é usada. Esse comportamento permite listar regras em ordem crescente de generalidade. Se nenhuma regra corresponder, nenhuma nova tentativa será realizada.

Quando a execução resulta em erro e há uma regra de nova tentativa aplicável, o critério de correspondência do erro determina se a execução deve ser executada novamente.

O valor da RetryExec palavra-chave é uma lista de regras de tentativa separadas por ponto e vírgula.
RetryExec={rule1;rule2}

Uma regra de repetição é como a seguinte: <errormatch>:<retrypolicy>:<querymatch>

• Correspondência de erros: Lista de códigos de erro separados por vírgulas. Por exemplo, especificar 1000,2000 lista os códigos de erro que você quer tentar novamente.

• Política de Retentativa: Especifica o intervalo até a próxima tentativa. O primeiro parâmetro é o número de tentativas, e o segundo parâmetro é o atraso. Por exemplo, 3,10+7 significa três tentativas começando em 10, e cada tentativa seguinte aumenta em 7 segundos. Se você não especificar +7, cada nova tentativa é duplicada exponencialmente.

• Correspondência de consulta: Especifica a consulta à qual você deseja corresponder. Se você não especificar nada, a regra se aplica a todas as consultas. Especificar SELECT significa todas as consultas que começam com SELECT.

Combinando os três componentes para usar em uma cadeia de conexão:

RetryExec={1000,2000:3,10+7:SELECT}

Essa regra significa: Para erros 1000 e 2000 em uma consulta que comece com SELECT, tente novamente duas vezes com um atraso inicial de 10 segundos, e adicione 7 segundos para cada tentativa seguinte.

Exemplos

40501,40540:4,5

Para erros 40501 e 40540, tente até quatro vezes, com um atraso inicial de 5 segundos e duplicação exponencial entre cada tentativa. Essa regra é aplicável a todas as consultas.

49919:2,10+:CREATE

Para erro 49919 em uma consulta que começa com CREATE, tente no máximo duas vezes, inicialmente após 10 segundos, e depois 20 segundos.

49918,40501,10928:5,10+5:SELECT c1

Para erros 49918, , e 10928 em consultas que começam com SELECT c1, tente novamente até cinco vezes, esperando 10 segundos na primeira tentativa e aumentando a espera em 405015 segundos depois.

Especifique as três regras anteriores juntas na cadeia de conexão da seguinte forma:

RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}

Coloque a regra mais geral (que corresponde a tudo) no final, para permitir que as duas regras mais específicas correspondam às respectivas consultas.

Certificado do Cliente

Especifica o certificado para autenticação em conexões de loopback. Essa opção está disponível apenas no SQL Server em Linux. As opções são:

Se o certificado estiver em PFX formato e a chave privada dentro do PFX certificado estiver protegida por senha, inclua a password palavra-chave. Para certificados nos formatos PEM e DER, inclua o atributo ClientKey.

ClientKey

Especifica a localização do arquivo da chave privada para PEM ou DER certificados especificados pelo ClientCertificate atributo. Formato:

Se o arquivo da chave privada estiver protegido por senha, inclua a password palavra-chave. Se a senha contiver algum , caractere, adicione um caractere extra , imediatamente após cada um. Por exemplo, se a senha for a,b,c, a senha com escape na cadeia de conexão será a,,b,,c.

HostnameInCertificate

Especifica o nome de host a esperar no certificado do servidor quando a criptografia for negociada, se for diferente do valor padrão derivado de Addr, Address, ou Server. A opção HostnameInCertificate é ignorada quando você usa a opção ServerCertificate.

IpAddressPreference

A partir da versão 18.1, use essa opção para especificar o tipo de endereço IP a priorizar para conexões.

As opções possíveis são IPv4First, IPv6First, e UsePlatformDefault. UsePlatformDefault conecta-se aos endereços na ordem em que são fornecidos pela chamada de sistema usada para resolver o nome do servidor. O valor padrão é IPv4First, que corresponde ao comportamento das versões anteriores.

Certificado do servidor

A partir da versão 18.1, use essa opção com modo de criptografia rigorosa. Use a ServerCertificate palavra-chave para especificar o caminho até um arquivo de certificado para corresponder ao certificado TLS/SSL do SQL Server. A verificação de correspondência é feita em vez da validação padrão de certificado (expiração, nome do host, cadeia de confiança etc.). Os formatos de certificado aceitos são PEM, DER e CER. Se você especificar essa opção, o certificado do SQL Server é verificado para ver se o ServerCertificate fornecido é uma correspondência exata.

SQL_COPT_SS_ACCESS_TOKEN

Use um token de acesso Microsoft Entra para autenticação. Para obter mais informações, consulte Usar o Microsoft Entra ID com o driver ODBC.

SQL_COPT_SS_CEKEYSTOREDATA

Comunica-se com uma biblioteca de provedor de repositório de chaves carregada. Controla a criptografia transparente de colunas (Always Encrypted). Esse atributo não tem valor padrão. Para obter mais informações, consulte Provedores de repositório de chaves personalizado.

SQL_COPT_SS_CEKEYSTOREPROVIDER

Carrega uma biblioteca de provedor de repositório de chaves para Always Encrypted ou recupera os nomes das bibliotecas de provedor de repositório de chaves carregadas. Para obter mais informações, consulte Provedores de repositório de chaves personalizado. Esse atributo não tem valor padrão.

SQL_COPT_SS_ENLIST_IN_XA

Para habilitar transações XA com um processador de transações (TP) compatível com XA, a aplicação precisa chamar SQLSetConnectAttr com SQL_COPT_SS_ENLIST_IN_XA e um ponteiro para um objeto XACALLPARAM. Essa opção tem suporte no Windows (17.3+), no Linux e no macOS.

SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER);  // XACALLPARAM *param

Para associar uma transação XA apenas a uma conexão ODBC, forneça TRUE ou FALSE com SQL_COPT_SS_ENLIST_IN_XA no lugar do ponteiro ao chamar SQLSetConnectAttr. Essa configuração é válida somente no Windows e não pode ser usada para especificar operações XA por meio de um aplicativo cliente.

SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, (SQLPOINTER)TRUE, 0);

Para saber mais sobre transações XA, confira Usar transações XA.

SQL_COPT_SS_LONGASMAX

Envia tipos de dados longos para servidores como tipos de dados máximos.

SQL_COPT_SS_SPID

Recupera a ID da sessão da conexão. Essa propriedade equivale à variável T-SQL @@SPID, exceto pelo fato de que não incorre em uma viagem de ida e volta adicional ao servidor.