Compartilhar via


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

Esta página lista as palavras-chave para cadeias de conexão e DSNs e os atributos de conexão para SQLSetConnectAttr e SQLGetConnectAttr, disponíveis no ODBC Driver for SQL Server.

Atributos de conexão e palavras-chave de cadeia de conexão/DSN com suporte

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

Palavras-chave da cadeia de conexão/DSN Atributo de conexão Plataforma
Addr LMW
Endereço LMW
AnsiNPW SQL_COPT_SS_ANSI_NPW LMW
APP LMW
ApplicationIntent SQL_COPT_SS_APPLICATION_INTENT LMW
AttachDBFileName SQL_COPT_SS_ATTACHDBFILENAME LMW
Autenticação 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
Backup de banco de dados SQL_ATTR_CURRENT_CATALOG LMW
Descrição LMW
Driver 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 e mais recente) LMW
KeepAlive (v17.4+, somente DSN anterior a 17.8) LMW
KeepAliveInterval (v17.4+, somente DSN anterior a 17.8) LMW
KeystoreAuthentication LMW
KeystorePrincipalId LMW
KeystoreSecret LMW
Idioma 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
Rede 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
Replicação LMW
RetryExec (18.1 e mais recente) LMW
SaveFile LMW
Servidor LMW
ServerCertificate (v18.1 e mais recente) 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 são algumas palavras-chave de cadeia de conexão e os atributos de conexão que não estão documentados em Usando palavras-chave de cadeia de conexão com SQL Server Native Client, SQLSetConnectAttr e Função SQLSetConnectAttr.

Descrição

Usado para descrever a fonte de dados.

SQL_COPT_SS_ANSI_OEM

Controles para conversão de dados de ANSI em OEM.

Valor do atributo Descrição
SQL_AO_OFF (Padrão) A conversão não foi concluída.
SQL_AO_ON A conversão foi concluída.

SQL_COPT_SS_AUTOBEGINTXN

Versão 17.6 e posterior Enquanto a confirmação automática está desativada, controla BEGIN TRANSACTION automático após ROLLBACK ou COMMIT.

Valor do atributo Descrição
SQL_AUTOBEGINTXN_ON (Padrão) BEGIN TRANSACTION automático após ROLLBACK ou COMMIT.
SQL_AUTOBEGINTXN_OFF Sem BEGIN TRANSACTION automático após ROLLBACK ou COMMIT.

SQL_COPT_SS_FALLBACK_CONNECT

Controla o uso de Conexões de Fallback do SQL Server. Esse atributo não tem mais suporte.

Valor do atributo Descrição
SQL_FB_OFF (Padrão) Conexões de fallback estão desabilitadas.
SQL_FB_ON Conexões de fallback estão habilitadas.

Novos atributos de conexão e palavras-chave da cadeia 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, confira Locação no Microsoft Entra ID.

Valor de Palavra-Chave Valor do atributo Descrição
SQL_AU_NONE (Padrão) Não definido. A combinação de outros atributos determina o modo de autenticação.
SqlPassword SQL_AU_PASSWORD Autenticação do SQL Server com nome de usuário e senha.
ActiveDirectoryIntegrated SQL_AU_AD_INTEGRATED Autenticação integrada do Microsoft Entra
ActiveDirectoryPassword SQL_AU_AD_PASSWORD Autenticação por senha do Microsoft Entra
ActiveDirectoryInteractive SQL_AU_AD_INTERACTIVE Autenticação interativa do Microsoft Entra
ActiveDirectoryMsi SQL_AU_AD_MSI Use as identidades gerenciadas do Microsoft Entra para autenticação. Para identidade atribuída pelo usuário, o UID é definido como a ID de objeto da identidade do usuário.
ActiveDirectoryServicePrincipal SQL_AU_AD_SPA Autenticação da entidade de serviço do Microsoft Entra. A UID é definida como a ID do cliente da entidade de serviço. PWD é definida como o segredo do cliente.
SQL_AU_RESET Remover definição. Substitui qualquer configuração de cadeia de conexão ou DSN.

Observação

Ao usar a palavra-chave ou atributo Authentication, especifique explicitamente a configuração Encrypt como o valor desejado na cadeia de conexão/DSN/atributo de conexão. Veja Usando palavras-chave de cadeia de conexão com o SQL Server Native Client para obter detalhes.

ColumnEncryption – SQL_COPT_SS_COLUMN_ENCRYPTION

Controla a criptografia de coluna transparente (Always Encrypted). Para saber mais, confira Usar Always Encrypted (ODBC).

Valor de Palavra-Chave Valor do atributo Descrição
habilitado SQL_CE_ENABLED Habilita o Always Encrypted.
Desabilitado SQL_CE_ENABLED (Padrão) Desabilita o Always Encrypted.
SQL_CE_RESULTSETONLY Habilite somente descriptografia (resultados e valores retornados).

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.

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

Driver ODBC 18 e mais recentes

Configuração de criptografia Confiar em Certificado do Servidor Criptografia forçada do servidor Resultado
Não No Não O certificado do servidor não é verificado.
Os dados enviados entre o cliente e o servidor não são criptografados.
Não Sim Não O certificado do servidor não é verificado.
Os dados enviados entre o cliente e o servidor não são criptografados.
Sim Não Não O certificado do servidor é verificado.
Os dados enviados entre cliente e servidor são criptografados.
Sim Sim Não O certificado do servidor não é verificado.
Os dados enviados entre cliente e servidor são criptografados.
Não No Sim O certificado do servidor é verificado.
Os dados enviados entre cliente e servidor são criptografados.
Não Sim Sim O certificado do servidor não é verificado.
Os dados enviados entre cliente e servidor são criptografados.
Sim Não Sim O certificado do servidor é verificado.
Os dados enviados entre cliente e servidor são criptografados.
Sim Sim Sim O certificado do servidor não é verificado.
Os dados enviados entre cliente e servidor são criptografados.
Rigoroso - - TrustServerCertificate é ignorado. O certificado do servidor é verificado.
Os dados enviados entre cliente e servidor são criptografados.

Observação

Estrito só está disponível em servidores que dão suporte a conexões TDS 8.0.

Driver ODBC 17 e mais antigos

Configuração de criptografia Confiar em Certificado do Servidor Criptografia forçada do servidor Resultado
Não No Não O certificado do servidor não é verificado.
Os dados enviados entre o cliente e o servidor não são criptografados.
Não Sim Não O certificado do servidor não é verificado.
Os dados enviados entre o cliente e o servidor não são criptografados.
Sim Não Não O certificado do servidor é verificado.
Os dados enviados entre cliente e servidor são criptografados.
Sim Sim Não O certificado do servidor não é verificado.
Os dados enviados entre cliente e servidor são criptografados.
Não No Sim O certificado do servidor não é verificado.
Os dados enviados entre cliente e servidor são criptografados.
Não Sim Sim O certificado do servidor não é verificado.
Os dados enviados entre cliente e servidor são criptografados.
Sim Não Sim O certificado do servidor é verificado.
Os dados enviados entre cliente e servidor são criptografados.
Sim Sim Sim O certificado do servidor não é verificado.
Os dados enviados entre cliente e servidor são criptografados.

TransparentNetworkIPResolution – SQL_COPT_SS_TNIR

Controla o recurso de Resolução de IP de Rede Transparente, que interage com MultiSubnetFailover para permitir tentativas de reconexão mais rápidas. Para saber mais, confira Usar resolução de IP de rede transparente.

Valor de Palavra-Chave Valor do atributo Descrição
habilitado SQL_IS_ON (Padrão) Habilita a resolução IP de rede transparente.
Desabilitado SQL_IS_OFF Desativa a resolução IP de rede transparente.

UseFMTONLY

Controla o uso de SET FMTONLY para metadados quando está se conectando ao SQL Server 2012 e versões mais recentes.

Valor de Palavra-Chave Descrição
Não (Padrão) Use sp_describe_first_result_set para metadados, se disponível.
Sim Use SET FMTONLY para metadados.

Replicação

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

Valor de Palavra-Chave Descrição
Não (Padrão) O logon de replicação não é usado.
Sim Os gatilhos com a opção NOT FOR REPLICATION não são acionados na conexão.

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. Esta funcionalidade pode ser habilitada por meio da cadeia de conexão usando a palavra-chave RetryExec e uma lista de regras de repetição. Cada regra de repetição tem três componentes separados por dois-pontos: uma correspondência de erro, uma política de repetição e uma correspondência de consulta.

A correspondência de consulta determina a regra de repetição a ser usada para uma determinada execução e é comparada com o texto de comando de entrada (SQLExecDirect) ou o texto de comando preparado no objeto de instrução (SQLExecute). Se houver correspondência de mais de uma regra, a primeira regra correspondente na lista será usada. Esse comportamento permite a listagem das regras em ordem crescente de generalidade. Se não houver nenhuma correspondência de regra, nenhuma repetição será aplicada.

Quando a execução resulta em um erro e há uma regra de repetição aplicável, sua correspondência de erro é usada para determinar se a execução deve ser repetida.

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

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

Correspondência de erro: uma lista de códigos de erro separados por vírgulas. Por exemplo, é recomendado realizar a repetição no caso da especificação dos códigos de erro 1000 e 2000.

Política de repetição: especifica o atraso até a próxima repetição. O primeiro parâmetro seria o número de repetições e o segundo seria o atraso. Por exemplo, 3,10+7 indicaria 3 tentativas começando em 10, com cada repetição seguinte incrementada em 7 segundos. Se +7 não for especificado, cada repetição seguinte será duplicada exponencialmente.

Correspondência de consulta: especifica a consulta com a qual fazer a correspondência. Caso nada seja especificado, aplica-se a todas as consultas. A especificação de SELECT está relacionada a todas as consultas que começam com select.

A combinação de todos os três componentes acima para usar em uma cadeia de conexão seria:

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

O que significaria: "Para os erros 1000 e 2000, em uma consulta que começa com SELECT. Tente novamente duas vezes, com um atraso inicial de dez segundos e a adição de sete segundos para cada tentativa posterior"

Exemplos

40501,40540:4,5

Para os erros 40501 e 40540, tente novamente até 4 vezes, com um atraso inicial de 5 segundos e duplicação exponencial entre as repetições. Essa regra é aplicável a todas as consultas.

49919:2,10+:CREATE

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

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

Para os erros 49918, 40501 e 10928 em consultas que começam com SELECT c1, tente novamente até 5 vezes, aguardando 10 segundos na primeira repetição e, em seguida, aumentando a espera em 5 segundos.

É possível especificar as três regras acima em conjunto na cadeia de conexão da seguinte maneira:

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

A regra mais geral (match-all) é colocada no final, a fim de que as duas regras mais específicas antes dela correspondam às respectivas consultas.

ClientCertificate

Especifica o certificado a ser usado para autenticação. As opções são:

Valor de Opção Descrição
sha1:<hash_value> O driver ODBC usa o hash SHA1 para localizar um certificado no Repositório de Certificados do Windows
subject:<subject> O driver ODBC usa o assunto para localizar um certificado no Repositório de Certificados do Windows
file:<file_location>[,password:<password>] O driver ODBC usa um arquivo de certificado.

Caso o certificado esteja no formato PFX e a chave privada dentro do certificado PFX esteja protegida por senha, a palavra-chave da senha será exigida. Para certificados nos formatos PEM e DER, o atributo ClientKey é exigido

ClientKey

Especifica um local de arquivo da chave privada para certificados PEM ou DER especificados pelo atributo ClientCertificate. Formato:

Valor de Opção Descrição
file:<file_location>[,password:<password>] Especifica o local do arquivo de chave privada.

Caso o arquivo de chave privada seja protegido por senha, a palavra-chave da senha será exigida. Se a senha contiver quaisquer caracteres ,, um caractere , extra será adicionado imediatamente após cada um deles. Por exemplo, se a senha for a,b,c, a senha com escape presente na cadeia de conexão será a,,b,,c.

HostnameInCertificate

Especifica o nome do host a ser esperado no certificado do servidor quando a criptografia for negociada, se for diferente do valor padrão derivado de Addr/Address/Server. A opção HostnameInCertificate é ignorada ao usar a opção ServerCertificate.

IpAddressPreference

Disponível a partir da versão 18.1, essa opção permite que o usuário especifique o tipo de endereço IP que deseja priorizar para conexões. As opções possíveis são "IpAddress= [ IPv4First | IPv6First | UsePlatformDefault]". UsePlatformDefault conecta-se aos endereços na ordem em que eles são fornecidos pela chamada do sistema a fim de resolver o nome do servidor. O valor padrão é IPv4First, que corresponde ao comportamento em versões anteriores.

ServerCertificate

Disponível a partir da versão 18.1, essa opção pode ser usada com o modo de criptografia estrito. A palavra-chave ServerCertificate é usada para especificar o caminho para um arquivo de certificado a ser correspondido com o certificado TLS/SSL do SQL Server. A correspondência é feita em vez da validação de certificado padrão (expiração, nome do host, cadeia confiável etc.). Os formatos de certificado aceitos são PEM, DER e CER. Se especificado, o certificado SQL Server será verificado para analisar se o ServerCertificate fornecido é uma correspondência exata.

SQL_COPT_SS_ACCESS_TOKEN

Permite o uso de um token de acesso do Microsoft Entra para autenticação. Para obter mais informações, confira Locação no Microsoft Entra ID.

Valor do atributo Descrição
NULO (Padrão) Nenhum token de acesso é fornecido.
ACCESSTOKEN* Ponteiro para um token de acesso.

SQL_COPT_SS_CEKEYSTOREDATA

Comunica-se com uma biblioteca de provedor de repositório de chaves carregada. Veja Controla a criptografia de coluna transparente (Always Encrypted). Esse atributo não tem valor padrão. Para saber mais, confira Provedores do Repositório de Chaves Personalizado.

Valor do atributo Descrição
CEKEYSTOREDATA * Estrutura de dados de comunicação para a biblioteca do provedor de repositório de chaves

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 saber mais, confira Provedores do Repositório de Chaves Personalizado. Esse atributo não tem valor padrão.

Valor do atributo Descrição
char * Caminho para uma biblioteca de provedores de repositório de chaves

SQL_COPT_SS_ENLIST_IN_XA

Para habilitar transações XA com um TP (Processador de Transações) em conformidade com XA, o aplicativo 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 a somente uma conexão ODBC, forneça TRUE ou FALSE com SQL_COPT_SS_ENLIST_IN_XA em vez 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);
Valor Descrição Plataformas
Objeto XACALLPARAM* O ponteiro para o objeto XACALLPARAM. Windows, Linux e macOS
TRUE Associa a transação XA à conexão ODBC. Todas as atividades relacionadas de banco de dados são executadas sob a proteção da transação XA. Windows
FALSE Associa a transação à conexão ODBC. Windows

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

SQL_COPT_SS_LONGASMAX

Permite que dados de tipo longo sejam enviados a servidores como dados de tipo máximo.

Valor do atributo Descrição
Não (Padrão) Não converta tipos longos em tipos Max ao enviar.
Sim Converte dados de tipos longos para tipos Max ao enviar.

SQL_COPT_SS_SPID

Recupera a ID do processo do servidor 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.

Valor do atributo Descrição
DWORD SPID