Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Esta página lista as palavras-chave para cadeias de conexão e DSNs e atributos de conexão para SQLSetConnectAttr e SQLGetConnectAttr, disponíveis no driver ODBC para SQL Server.
Palavras-chave e atributos de DSN/cadeia de conexão suportados
A tabela a seguir lista as palavras-chave disponíveis e os atributos para cada plataforma (L: Linux; M: macOS; W: Janelas). Selecione a palavra-chave ou atributo para obter mais detalhes.
Aqui estão algumas palavras-chave e atributos de conexão de cadeia 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.
Description
Usado para descrever a fonte de dados.
SQL_COPT_SS_ANSI_OEM
Controla a conversão de dados ANSI para OEM.
| Valor do Atributo | Description |
|---|---|
| SQL_AO_OFF | (Padrão) A tradução não está feita. |
| SQL_AO_ON | A tradução está feita. |
SQL_COPT_SS_AUTOBEGINTXN
Versão 17.6+ Enquanto a confirmação automática está desativada, os controles automáticos BEGIN TRANSACTION após ROLLBACK ou COMMIT.
| Valor do Atributo | Description |
|---|---|
| SQL_AUTOBEGINTXN_ON | (Padrão) Automático START TRANSACTION após ROLLBACK ou COMMIT. |
| SQL_AUTOBEGINTXN_OFF | Nenhuma transação automática BEGIN após ROLLBACK ou COMMIT. |
SQL_COPT_SS_FALLBACK_CONNECT
Controla o uso de conexões de fallback do SQL Server. Este não é mais suportado.
| Valor do Atributo | Description |
|---|---|
| SQL_FB_OFF | (Padrão) As conexões de fallback estão desabilitadas. |
| SQL_FB_ON | As conexões de fallback estão habilitadas. |
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 se conectar ao SQL Server. Para obter mais informações, consulte Usando a ID do Microsoft Entra.
| Valor da palavra-chave | Valor do Atributo | Description |
|---|---|---|
| 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. |
| ActiveDirectoryIntegrado | SQL_AU_AD_INTEGRATED | Autenticação integrada Microsoft Entra. |
| ActiveDirectoryPassword | SQL_AU_AD_PASSWORD | Autenticação de senha do Microsoft Entra. |
| ActiveDirectoryInteractive | SQL_AU_AD_INTERACTIVE | Autenticação interativa do Microsoft Entra. |
| ActiveDirectoryMsi | SQL_AU_AD_MSI | Autenticação de identidade gerenciada do Microsoft Entra. Para identidade atribuída pelo usuário, o UID é definido como a ID do objeto da identidade do usuário. |
| ActiveDirectoryServicePrincipal | SQL_AU_AD_SPA | Autenticação da entidade de serviço do Microsoft Entra. O UID é definido como a ID do cliente da entidade de serviço. PWD é definido para o segredo do cliente. |
| SQL_AU_RESET | Desconfigurado. Substitui qualquer configuração de DSN ou cadeia de conexão. |
Observação
Ao usar Authentication palavra-chave ou atributo, especifique Encrypt explicitamente a configuração para o valor desejado na cadeia de conexão / DSN / atributo de conexão. Consulte 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 obter mais informações, consulte Usando sempre criptografado (ODBC).
| Valor da palavra-chave | Valor do Atributo | Description |
|---|---|---|
| Enabled | SQL_CE_ENABLED | Habilita Sempre Criptografado. |
| Disabled | SQL_CE_DISABLED | (Padrão) Desativa Sempre Encriptado. |
| SQL_CE_RESULTSETONLY | Permite apenas a desencriptação (resultados e valores de retorno). |
Criptografar
Especifica se as conexões usam criptografia TLS pela rede. Os valores possíveis são yes/mandatory(18,0+), no/optional(18,0+) e strict(18,0+). O valor padrão está yes na versão 18.0+ e no em versões anteriores.
Independentemente da configuração Encryptdo , as credenciais de login do servidor (nome de usuário e senha) são sempre criptografadas.
Encrypt, TrustServerCertificatee as configurações do lado Force Encryption do servidor desempenham um papel no fato de as conexões serem criptografadas pela rede. As tabelas a seguir mostram o efeito dessas configurações.
ODBC Driver 18 e mais recente
| Criptografar configuração | Certificado de servidor confiável | Criptografia de força de servidor | resultado |
|---|---|---|---|
| Não | Não | Não | O certificado do servidor não está verificado. Os dados enviados entre o cliente e o servidor não são criptografados. |
| Não | Yes | Não | O certificado do servidor não está verificado. Os dados enviados entre o cliente e o servidor não são criptografados. |
| Yes | Não | Não | O certificado do servidor está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
| Yes | Yes | Não | O certificado do servidor não está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
| Não | Não | Yes | O certificado do servidor está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
| Não | Yes | Yes | O certificado do servidor não está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
| Yes | Não | Yes | O certificado do servidor está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
| Yes | Yes | Yes | O certificado do servidor não está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
| Estrito | - | - | TrustServerCertificate é ignorado. O certificado do servidor está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
Observação
Strict só está disponível em servidores que suportam conexões TDS 8.0.
Driver ODBC 17 e mais antigo
| Criptografar configuração | Certificado de servidor confiável | Criptografia de força de servidor | resultado |
|---|---|---|---|
| Não | Não | Não | O certificado do servidor não está verificado. Os dados enviados entre o cliente e o servidor não são criptografados. |
| Não | Yes | Não | O certificado do servidor não está verificado. Os dados enviados entre o cliente e o servidor não são criptografados. |
| Yes | Não | Não | O certificado do servidor está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
| Yes | Yes | Não | O certificado do servidor não está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
| Não | Não | Yes | O certificado do servidor não está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
| Não | Yes | Yes | O certificado do servidor não está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
| Yes | Não | Yes | O certificado do servidor está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
| Yes | Yes | Yes | O certificado do servidor não está verificado. Os dados enviados entre o cliente e o servidor são criptografados. |
TransparentNetworkIPResolution - SQL_COPT_SS_TNIR
Controla o recurso Resolução IP de Rede Transparente, que interage com MultiSubnetFailover para permitir tentativas de reconexão mais rápidas. Para obter mais informações, consulte Usando resolução IP de rede transparente.
| Valor da palavra-chave | Valor do Atributo | Description |
|---|---|---|
| Enabled | SQL_IS_ON | (Padrão) Permite uma resolução IP de rede transparente. |
| Disabled | SQL_IS_OFF | Desativa a resolução IP de rede transparente. |
UseFMTONLY
Controla o uso de SET FMTONLY para metadados ao se conectar ao SQL Server 2012 e mais recente.
| Valor da palavra-chave | Description |
|---|---|
| Não | (Padrão) Use sp_describe_first_result_set para metadados, se disponíveis. |
| Yes | Use SET FMTONLY para metadados. |
Replication
Especifica o uso de um logon de replicação no driver ODBC versão 17.8 e mais recente.
| Valor da palavra-chave | Description |
|---|---|
| Não | (Padrão) O login de replicação não é usado. |
| Yes | Os gatilhos com a NOT FOR REPLICATION opção não disparam na conexão. |
RetryExec
A lógica de repetição configurável está disponível a partir da versão 18.1. Ele reexecuta automaticamente chamadas de função ODBC específicas com base em condições configuráveis. Esse recurso pode ser ativado através da cadeia de conexão usando a palavra-chave RetryExec , juntamente com 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 é correspondida com o texto do comando de entrada (SQLExecDirect) ou o texto do comando preparado no objeto de instrução (SQLExecute). Se mais de uma regra corresponder, a primeira correspondente na lista será usada. Esse comportamento permite que as regras sejam listadas em ordem crescente de generalidade. Se nenhuma regra corresponder, nenhuma nova tentativa 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 é a seguinte: <errormatch>:<retrypolicy>:<querymatch>
Correspondência de erro: Uma lista separada por vírgulas de códigos de erro. Por exemplo, especificar 1000,2000 seriam os códigos de erro que você deseja tentar novamente.
Política de repetição: Especifica o atraso até a próxima nova tentativa. O primeiro parâmetro seria o número de novas tentativas, enquanto o segundo seria o atraso. Por exemplo, 3,10+7 seriam 3 tentativas começando em 10 e cada tentativa seguinte aumentaria em 7 segundos. Se +7 não for especificado, cada repetição a seguir será exponencialmente dobrada.
Correspondência de consulta: Especifica a consulta com a qual você deseja corresponder. Se nada for especificado, ele se aplica a todas as consultas. Especificar SELECT significaria para todas as consultas que começam com select.
A combinação dos três componentes acima para usar em uma cadeia de conexão seria:
RetryExec={1000,2000:3,10+7:SELECT}
O que significaria: "Para erros 1000 e 2000, em uma consulta que começa com SELECT. Tente novamente duas vezes com um atraso inicial de 10 segundos e adicionando 7 segundos para cada tentativa seguinte"
Examples
40501,40540:4,5
Para os erros 40501 e 40540, tente novamente até quatro vezes, com um atraso inicial de 5 segundos, e dobrando exponencialmente entre cada nova tentativa. Esta regra aplica-se 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 duas vezes, inicialmente após 10 segundos e, em seguida, 20 segundos.
49918,40501,10928:5,10+5:SELECT c1
Para erros, 49918, 40501 e 10928 em consultas que começam com SELECT c1, tente novamente até cinco vezes, aguardando 10 segundos na primeira tentativa e aumentando a espera em 5 segundos depois disso.
As três regras acima podem ser especificadas juntas 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, para permitir que as duas regras mais específicas antes dela correspondam às suas respetivas consultas.
Certificado de Cliente
Especifica o certificado a ser usado para autenticação com conexões de loopback (disponível apenas no SQL Server no Linux). As opções são:
| Valor da opção | Description |
|---|---|
sha1:<hash_value> |
O driver ODBC usa hash SHA1 para localizar um certificado no Windows Certificate Store |
subject:<subject> |
O driver ODBC usa subject para localizar um certificado no Windows Certificate Store |
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 senha é necessária. Para certificados nos formatos PEM e DER é necessário o atributo ClientKey
Chave de Cliente
Especifica um local de arquivo da chave privada ou PEMDER certificados especificados pelo atributo ClientCertificate. Formato:
| Valor da opção | Description |
|---|---|
file:<file_location>[,password:<password>] |
Especifica o local do arquivo de chave privada. |
No caso, se o arquivo de chave privada é protegido por senha, então a palavra-chave senha é necessária. Se a senha contiver algum , caractere, um caractere extra , será adicionado imediatamente após cada um. 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 de host a ser esperado no certificado do servidor quando a criptografia é 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 | IPv6Primeiro | UsePlatformDefault]." UsePlatformDefault se conecta a endereços na ordem em que são fornecidos pela chamada do sistema para 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, esta opção pode ser usada com o modo de encriptação estrita. A palavra-chave ServerCertificate é usada para especificar o caminho para um arquivo de certificado a ser correspondido ao certificado TLS/SSL do SQL Server. A correspondência é feita em vez da validação de certificado padrão (validade, nome do host, cadeia de confiança, etc.) Os formatos de certificado aceitos são PEM, DER e CER. Se especificado, o certificado do SQL Server é verificado verificando 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, consulte Usando a ID do Microsoft Entra.
| Valor do Atributo | Description |
|---|---|
| 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 keystore carregada. Consulte Controla a criptografia de coluna transparente (Sempre criptografada). Este atributo não tem valor padrão. Para obter mais informações, consulte Provedores de armazenamento de chaves personalizados.
| Valor do Atributo | Description |
|---|---|
| CEKEYSTOREDATA * | Estrutura de dados de comunicação para biblioteca de provedor de keystore |
SQL_COPT_SS_CEKEYSTOREPROVIDER
Carrega uma biblioteca de provedor de keystore para Always Encrypted ou recupera os nomes de bibliotecas de provedor de keystore carregadas. Para obter mais informações, consulte Provedores de armazenamento de chaves personalizados. Este atributo não tem valor padrão.
| Valor do Atributo | Description |
|---|---|
| char * | Caminho para uma biblioteca de provedor de keystore |
SQL_COPT_SS_ENLIST_IN_XA
Para habilitar transações XA com um TP (Transaction Processor) compatível com XA, o aplicativo precisa chamar SQLSetConnectAttr com SQL_COPT_SS_ENLIST_IN_XA e um ponteiro para um XACALLPARAM objeto. Esta opção é suportada no Windows (17.3+), Linux e 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 em vez do ponteiro ao chamar SQLSetConnectAttr. Essa configuração só é válida 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 | Description | Plataformas |
|---|---|---|
| Objeto XACALLPARAM* | O ponteiro para o XACALLPARAM objeto. |
Windows, Linux e macOS |
| TRUE | Associa a transação XA à conexão ODBC. Todas as atividades de banco de dados relacionadas são realizadas sob a proteção da transação XA. | Windows |
| FALSE | Desassocia a transação com a conexão ODBC. | Windows |
Para obter mais informações sobre transações XA, consulte Usando transações XA.
SQL_COPT_SS_LONGASMAX
Permite que dados de tipo longo sejam enviados para servidores como dados de tipo máximo.
| Valor do Atributo | Description |
|---|---|
| Não | (Padrão) Não converta tipos longos em tipos máximos ao enviar. |
| Yes | Converte dados de tipos longos em tipos máximos ao enviar. |
SQL_COPT_SS_SPID
Recupera a ID de sessão da conexão. Essa propriedade é equivalente à variável T-SQL @@SPID , exceto que ela não incorre em uma viagem de ida e volta extra para o servidor.
| Valor do Atributo | Description |
|---|---|
| DWORD | SPID |