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