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.
Este artigo lista as palavras-chave para strings de ligação e DSNs, e os atributos de ligação para SQLSetConnectAttr e SQLGetConnectAttr, disponíveis no ODBC Driver for SQL Server.
Palavras-chave de DSN e de cadeia de ligação suportadas, e atributos de ligação
A tabela seguinte lista as palavras-chave e atributos disponíveis para cada plataforma (L: Linux; M: macOS; W: Windows). Selecione a palavra-chave ou atributo para obter mais detalhes.
Eis algumas palavras-chave da cadeia de ligação e atributos de ligação que não estão documentados em Using Connection String Keywords with SQL Server Native Client, SQLSetConnectAttr e SQLSetConnectAttr Function.
Description
Descreve 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 (predefinição) |
A tradução não está feita. |
SQL_AO_ON |
A tradução está feita. |
SQL_COPT_SS_AUTOBEGINTXN
A partir da versão 17.6, quando o autocommit estiver desativado, utilize esta opção para controlar a execução automática de BEGIN TRANSACTION após ROLLBACK ou COMMIT.
| Valor do atributo | Description |
|---|---|
SQL_AUTOBEGINTXN_ON (predefinição) |
Automático BEGIN TRANSACTION 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 das ligações de reserva do SQL Server. Esta opção já não é suportada.
| Valor do atributo | Description |
|---|---|
SQL_FB_OFF (predefinição) |
Desativa as ligações de contingência. |
SQL_FB_ON |
Permite ligações de recurso. |
Novas palavras-chave e atributos da cadeia de ligaçã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 Microsoft Entra ID com o Driver ODBC.
| Valor da palavra-chave | Valor do atributo | Description |
|---|---|---|
SQL_AU_NONE (predefinição) |
Não está 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 Microsoft Entra. |
ActiveDirectoryInteractive |
SQL_AU_AD_INTERACTIVE |
Autenticação interativa Microsoft Entra. |
ActiveDirectoryMsi |
SQL_AU_AD_MSI |
Autenticação de identidade gerenciada do Microsoft Entra. Para a identidade atribuída pelo utilizador, UID é definido como o ID do objeto da identidade do utilizador. |
ActiveDirectoryServicePrincipal |
SQL_AU_AD_SPA |
Autenticação da entidade de serviço do Microsoft Entra.
UID está definido para o ID do cliente do principal de serviço.
PWD está definido como o segredo do cliente. |
ActiveDirectoryPassword |
SQL_AU_AD_PASSWORD |
[DEPRECIADO] Autenticação por palavra-passe Microsoft Entra.ActiveDirectoryPassword está obsoleto. Para obter mais informações, consulte ActiveDirectoryPassword está obsoleto. |
SQL_AU_RESET |
Não definido. Ignora qualquer configuração de DSN ou string de ligação. |
Observação
Ao utilizar a palavra-chave ou o atributo Authentication, especifique explicitamente a definição Encrypt com o valor desejado na cadeia de ligação, no DSN ou no atributo de ligação. Consulte Usando palavras-chave de cadeia de conexão com o SQL Server Native Client para obter detalhes.
EncriptaçãoDeColuna - SQL_COPT_SS_COLUMN_ENCRYPTION
Controla a encriptação transparente de colunas (Always Encrypted). Para obter mais informações, consulte Always Encrypted com o driver ODBC para SQL Server.
| Valor da palavra-chave | Valor do atributo | Description |
|---|---|---|
Enabled |
SQL_CE_ENABLED |
Habilita Sempre Criptografado. |
Disabled (predefinição) |
SQL_CE_DISABLED |
Desativa sempre encriptado. |
SQL_CE_RESULTSETONLY |
Permite apenas a desencriptação (resultados e valores de retorno). |
ConcatNullYieldsNull - SQL_COPT_SS_CONCAT_NULL
Controla a utilização do tratamento ISO de NULL ao concatenar cadeias de caracteres. Para obter mais informações, veja SET CONCAT_NULL_YIELDS_NULL.
| Valor da palavra-chave | Valor do atributo | Description |
|---|---|---|
Yes (predefinição) |
SQL_CN_ON |
NULL a concatenação produz NULL. |
No |
SQL_CN_OFF |
NULL a concatenação produz uma cadeia. |
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 definição de Encrypt, as credenciais de início de sessão do servidor (nome de utilizador e palavra-passe) estão sempre encriptadas.
As definições de Encrypt, TrustServerCertificate e Force Encryption do lado do servidor determinam se as ligações são encriptadas através da 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
O Strict valor só está disponível contra servidores que suportam ligaçõ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 a funcionalidade Transparent Network IP Resolution, uma alternativa legada multi-IP para o driver ODBC. Esta configuração não afeta a sequência de ligação quando MultiSubnetFailover=Yes, que é a definição recomendada para o Base de Dados SQL do Azure, o Azure SQL Managed Instance, a base de dados SQL no Microsoft Fabric, os listeners de grupos de disponibilidade e as instâncias de cluster de failover. Para mais informações, consulte Usar resolução transparente de IP de rede com o driver ODBC ou Alta disponibilidade e recuperação de desastres.
| Valor da palavra-chave | Valor do atributo | Description |
|---|---|---|
Enabled (predefinição) |
SQL_IS_ON |
Permite uma resolução transparente de IP de rede. |
Disabled |
SQL_IS_OFF |
Desativa a resolução transparente de IP de rede. |
UseFMTONLY
Controla a utilização de SET FMTONLY para metadados ao ligar ao SQL Server 2012 e versões posteriores.
| Valor da palavra-chave | Description |
|---|---|
No (predefinição) |
Use sp_describe_first_result_set para metadados, se disponível. |
Yes |
Uso 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 |
|---|---|
No (predefinição) |
O login de replicação não é utilizado. |
Yes |
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. Ele reexecuta automaticamente chamadas de função ODBC específicas com base em condições configuráveis. Ative esta funcionalidade na cadeia de ligação, utilizando a palavra-chave RetryExec, juntamente com uma lista de regras de repetição de tentativas. Cada regra de nova tentativa tem três componentes separados por dois-pontos: um critério de correspondência de erro, uma política de nova tentativa e um critério de correspondência de consulta.
A correspondência da consulta determina a regra de repetição a utilizar para uma determinada execução. Corresponde ao texto de comando recebido (SQLExecDirect) ou ao texto de comando preparado no objeto de instrução (SQLExecute). Se mais do que uma regra coincidir, é usada a primeira regra correspondente da lista. Este comportamento permite listar regras por ordem crescente de generalidade. Se nenhuma regra coincidir, não é aplicada nova tentativa.
Quando a execução resulta num erro e existe uma regra de repetição aplicável, a correspondência com o erro dessa regra determina 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 erros: Uma lista de códigos de erro separada por vírgulas. Por exemplo, especificar
1000,2000lista os códigos de erro que quer tentar novamente.Política de repetição: Especifica o intervalo até à próxima tentativa. O primeiro parâmetro é o número de tentativas, e o segundo parâmetro é o atraso. Por exemplo,
3,10+7significa três tentativas começando em 10, e cada tentativa seguinte incrementa 7 segundos. Se não especificares+7, cada tentativa seguinte duplica exponencialmente.Correspondência da consulta: Especifica a consulta a estabelecer como correspondência. Se não especificares nada, a regra aplica-se a todas as consultas. Especificar
SELECTsignifica todas as consultas que começam porSELECT.
Combinando os três componentes juntos para uso numa cadeia de ligação:
RetryExec={1000,2000:3,10+7:SELECT}
Esta regra significa: Para erros 1000 e 2000 numa consulta que comece por SELECT, tente novamente duas vezes com um atraso inicial de 10 segundos, e adicione 7 segundos para cada tentativa seguinte.
Examples
40501,40540:4,5
Para erros 40501 e 40540, tente novamente até quatro vezes, com um atraso inicial de 5 segundos e duplicação exponencial entre cada tentativa. Esta regra aplica-se a todas as consultas.
49919:2,10+:CREATE
Para erro 49919 numa consulta que comece por CREATE, tente novamente 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 por SELECT c1, tente 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 ligaçã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 (corresponde a tudo) no final, para permitir que as duas regras mais específicas correspondam às respetivas consultas.
Certificado de Cliente
Especifica o certificado de autenticação com ligações de loopback. Esta opção está disponível apenas no SQL Server em Linux. As opções são:
| Valor da opção | Description |
|---|---|
sha1:<hash_value> |
O driver ODBC utiliza o hash SHA1 para localizar um certificado na Loja de Certificados do Windows. |
subject:<subject> |
O driver ODBC utiliza o assunto para localizar um certificado na Windows Certificate Store. |
file:<file_location>[,password:<password>] |
O driver ODBC usa um arquivo de certificado. |
Se o certificado estiver no PFX formato e a chave privada dentro do PFX certificado estiver protegida por palavra-passe, inclua a password palavra-chave. Para certificados em PEM e DER formatos, inclua o ClientKey atributo.
Chave de Cliente
Especifica a localização do ficheiro da chave privada para PEM ou DER certificados especificados pelo ClientCertificate atributo. Formato:
| Valor da opção | Description |
|---|---|
file:<file_location>[,password:<password>] |
Especifica a localização do ficheiro de chave privada. |
Se o ficheiro de chave privada estiver protegido por palavra-passe, inclua a password palavra-chave. Se a palavra-passe tiver algum , caractere, adicione um carácter extra , imediatamente após cada um. Por exemplo, se a palavra-passe for a,b,c, a palavra-passe com escape na cadeia de ligação é a,,b,,c.
HostnameInCertificate
Especifica o nome de host a esperar no certificado do servidor quando a encriptação for negociada, se for diferente do valor padrão derivado de Addr, Address, ou Server. A opção HostnameInCertificate é ignorada quando utiliza a opção ServerCertificate.
Preferência de Endereço IP
A partir da versão 18.1, use esta opção para especificar o tipo de endereço IP a priorizar para as ligações.
As opções possíveis são IPv4First, IPv6First, e UsePlatformDefault.
UsePlatformDefault estabelece ligação aos endereços pela ordem em que são fornecidos na chamada de sistema usada para resolver o nome do servidor. O valor padrão é IPv4First, que corresponde ao comportamento das versões anteriores.
ServerCertificate
A partir da versão 18.1, use esta opção com modo de encriptação rigorosa. Use a ServerCertificate palavra-chave para especificar o caminho para um ficheiro de certificado a corresponder ao certificado TLS/SSL do SQL Server. A verificação é efetuada em vez da validação padrão do certificado (expiração, nome do host, cadeia de confiança, etc.). Os formatos de certificado aceitos são PEM, DERe CER. Se especificar esta 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 Usando Microsoft Entra ID com o Driver ODBC.
| Valor do atributo | Description |
|---|---|
NULL (predefinição) |
Não é fornecido nenhum token de acesso. |
ACCESSTOKEN* |
Ponteiro para um token de acesso. |
SQL_COPT_SS_CEKEYSTOREDATA
Comunica-se com uma biblioteca de provedor de keystore carregada. Controla a encriptação transparente de colunas (Always Encrypted). 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 a biblioteca do fornecedor de keystore |
SQL_COPT_SS_CEKEYSTOREPROVIDER
Carrega uma biblioteca do fornecedor de arquivos de chaves para Always Encrypted ou obtém os nomes das bibliotecas do fornecedor de arquivos de chaves 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 a biblioteca do fornecedor de keystore |
SQL_COPT_SS_ENLIST_IN_XA
Para ativar transações XA com um processador de transações (TP) compatível com XA, a aplicação tem de chamar SQLSetConnectAttr com SQL_COPT_SS_ENLIST_IN_XA e um ponteiro para um objeto XACALLPARAM. 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 ligaçã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 |
|---|---|---|
XACALLPARAM objeto* |
O ponteiro para o objeto XACALLPARAM. |
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
Envia tipos de dados longos para servidores como tipos de dados máximos.
| Valor do atributo | Description |
|---|---|
No (predefinição) |
Não convertas tipos longos em tipos máximos ao enviares. |
Yes |
Converte dados de tipos longos para 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 |