Microsoft ODBC Driver para SQL Server

Baixar driver ODBC

O ODBC é a API de acesso a dados nativo primária para aplicativos escritos em C e C++ para o SQL Server. O Microsoft ODBC Driver for SQL Server conecta-se ao SQL Server, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure, Azure Synapse Analytics e banco de dados SQL no Microsoft Fabric. Para as versões de banco de dados que cada versão de driver suporta, veja compatibilidade de versões SQL.

Outros idiomas que usam o ODBC incluem COBOL, Perl, PHP e Python. ODBC é amplamente utilizado em cenários de integração de dados, e os drivers Microsoft para PHP para SQL Server são construídos sobre esse driver.

Os utilitários sqlcmd e bcp funcionam com esse driver, mas eles se instalam separadamente: o mssql-tools18 pacote no Linux e macOS, e os Utilitários de Linha de Comando da Microsoft no Windows. Use sqlcmd para executar instruções Transact-SQL (T-SQL), procedimentos do sistema e arquivos de script. Use bcp para copiar dados em massa entre uma instância do SQL Server e um arquivo de dados, em ambas as direções.

Escolha o ponto de partida

Linha de base de produção para SQL do Azure

Use esse snippet como ponto de partida para uma conexão de SQL do Azure orientada à produção. Ele carrega o nome do servidor e o nome do banco de dados a partir da configuração da aplicação, autentica com uma identidade gerenciada para que nenhum segredo apareça na cadeia de conexão e permite a criptografia Tabular Data Stream (TDS) 8.0 com validação completa do certificado. Define um tempo limite de login por tentativa e repete as tentativas em caso de falhas transitórias com backoff exponencial e jitter.

O trecho em C++ neste artigo omite as diretivas de inclusão, a alocação de handles e a função auxiliar de registro em log por brevidade.

std::wstring BuildConnectionString(const wchar_t* server, const wchar_t* database) {
    std::wstring cs = L"Driver={ODBC Driver 18 for SQL Server}";
    cs += L";Server=tcp:"; cs += server; cs += L",1433";
    cs += L";Database="; cs += database;
    cs += L";Authentication=ActiveDirectoryMsi";   // managed identity, no stored secret
    cs += L";Encrypt=strict";                      // TDS 8.0 with certificate validation
    cs += L";ConnectRetryCount=3";                 // idle connection resiliency, not initial connect
    cs += L";ConnectRetryInterval=10";
    return cs;
}

// Transient fault codes documented for Azure SQL, plus the resource governance
// codes. Network termination and timeout errors (64, 233, 258, 10053, 10054,
// 10060) are retried a bounded number of times, which is the documented
// guidance for them. 258 is the code the driver reports for a connect timeout.
// 10053 and 10054 can also mean the encryption handshake failed rather than a
// plain network reset, so read the error text before assuming a network fault.
bool IsTransient(SQLINTEGER nativeError) {
    switch (nativeError) {
        case 615: case 926: case 4060: case 4221:
        case 10928: case 10929: case 10936:
        case 40197: case 40501: case 40613:
        case 42108: case 42109:
        case 49918: case 49919: case 49920:
        case 40020: case 40143: case 40166: case 40540:   // failover subcodes
        case 64: case 233: case 258:
        case 10053: case 10054: case 10060:
            return true;
        default:
            return false;
    }
}

// Retries only errors that a new connection can clear, with exponential backoff
// plus jitter so that concurrent clients don't retry in lockstep.
SQLRETURN ConnectWithRetry(SQLHDBC hDbc, const std::wstring& connectionString, int maxAttempts) {
    SQLRETURN rc = SQL_ERROR;
    for (int attempt = 1; attempt <= maxAttempts; ++attempt) {
        // Set the per-attempt connect timeout through the connection attribute.
        // This works on every driver version, so the sample doesn't depend on
        // which connection string keywords a given release accepts.
        SQLSetConnectAttrW(hDbc, SQL_ATTR_LOGIN_TIMEOUT,
                           reinterpret_cast<SQLPOINTER>(static_cast<SQLLEN>(30)), 0);

        rc = SQLDriverConnectW(hDbc, nullptr,
                               const_cast<SQLWCHAR*>(reinterpret_cast<const SQLWCHAR*>(connectionString.c_str())),
                               SQL_NTS, nullptr, 0, nullptr, SQL_DRIVER_NOPROMPT);
        if (SQL_SUCCEEDED(rc)) {
            Log("INFO", "connected on attempt %d/%d", attempt, maxAttempts);
            return rc;
        }

        // Walks the diagnostic records and returns the first record that carries
        // a real SQL Server error number. Microsoft Entra failures report several
        // driver-specific records first, whose native error is 0.
        SQLINTEGER native = LogDiagnostics(SQL_HANDLE_DBC, hDbc, "connect");
        if (attempt == maxAttempts || !IsTransient(native)) return rc;

        // Cap the backoff at 64 seconds. This also keeps the shift in range
        // when a caller passes a large maxAttempts.
        int shift = (attempt - 1 < 6) ? attempt - 1 : 6;
        DWORD delayMs = (1UL << shift) * 1000UL + (DWORD)(GetTickCount64() % 500);
        Log("WARN", "retrying in %lu ms (attempt %d/%d)", delayMs, attempt + 1, maxAttempts);
        Sleep(delayMs);
    }
    return rc;
}

ConnectRetryCount e ConnectRetryInterval habilitam a resiliência de conexão ociosa, que restaura de forma transparente uma conexão que foi perdida enquanto estava ociosa. Eles não fazem nova tentativa de conexão inicial, por isso este trecho também implementa novas tentativas em nível de aplicação. Mantenha ambos.

O ODBC relata diagnósticos por meio de SQLGetDiagRec, e não apenas pelo código de retorno, portanto classifique as falhas antes de tentar novamente. Nesse caso, a operação falha imediatamente devido a um erro de autenticação ou de configuração, em vez de consumir todo o orçamento de retentativas.

Para obter mais informações sobre cada parte dessa configuração, consulte:

Para o catálogo de erros transientes do SQL do Azure, veja códigos de erro de falha transitória.

Características principais

  • Multiplataforma: A mesma API no Windows, Linux e macOS.
  • Autenticação Microsoft Entra ID: Conexões sem senha com identidade gerenciada, principal de serviço, fluxos interativos e integrados.
  • Criptografia rigorosa: conexões TDS 8.0 com validação completa de certificados na versão 18 e versões posteriores.
  • Always Encrypted: Criptografia do lado do cliente para colunas sensíveis, com suporte a provedores de keystore personalizados.
  • Resiliência da conexão: Restauração transparente de uma conexão que caiu enquanto estava ociosa.
  • Alta disponibilidade: Disponibilidade de apoio ao ouvinte em grupo com MultiSubnetFailover.
  • Classificação de dados: Metadados de sensibilidade para colunas classificadas.
  • Tipo de dado vetorial: Suporte nativo para o tipo vetorial .
  • Transações distribuídas: suporte a transações XA por meio do Coordenador de Transações Distribuídas da Microsoft (MSDTC).
  • Ferramentas complementares: sqlcmd e bcp, instalados separadamente.

Introdução

Artigo Description
Baixar o driver ODBC para SQL Server Instaladores e pacotes para baixar para cada versão de driver suportada, em todas as três plataformas.
Desenvolver aplicações em C e C++ com o driver ODBC Quais cabeçalhos incluir, em qual ordem, quais bibliotecas vincular e como escolher entre execução assíncrona e threads.
Conecte-se e consulte um banco de dados com C++ Um exemplo completo em C++ que conecta, executa uma consulta e lê resultados, para que você possa confirmar sua configuração de ponta a ponta.
Ciclo de vida do suporte Quais versões de drivers ainda são suportadas e a data em que cada uma sai do suporte.
Principais diferenças de versão O que quebra quando você passa da versão 17 para a versão 18, começando com a mudança na configuração padrão de criptografia.

Instalar o driver

Artigo Description
Requisitos do sistema, instalação e arquivos de driver (Windows) Versões do Windows compatíveis, a linha de comando do instalador para implantação silenciosa e onde cada arquivo de driver é armazenado no disco.
Requisitos do sistema (Linux e macOS) Quais distribuições Linux e versões do macOS cada versão de driver suportam, além da compatibilidade com versões do SQL Server.
Instale o driver ODBC no Linux Etapas do gerenciador de pacotes para Alpine, Debian, Red Hat, SUSE, Ubuntu e Azure Linux, além da instalação offline e da localização dos arquivos dos drivers.
Instale o driver ODBC no macOS Etapas de tap e fórmula do Homebrew para macOS, incluindo como instalar as versões 18, 17 ou 13.1.
Instale o gerenciador de drivers unixODBC (Linux e macOS) Instale ou atualize o unixODBC, o gerenciador de drivers que carrega o driver ODBC no Linux e macOS.

Configuração e conexão

Artigo Description
Atributos e palavras-chave da cadeia de conexão e DSN O catálogo completo de palavras-chave da cadeia de conexão, entradas DSN e atributos SQLSetConnectAttr, com os valores aceitos para cada um deles.
Palavras-chave de string de conexão e nomes de fontes de dados (Linux e macOS) Como odbc.ini e odbcinst.ini definem uma DSN no Linux e macOS, além das configurações de TLS e TCP keep-alive específicas dessas plataformas.
Administrador de Fonte de Dados ODBC DSN (Windows) Todas as opções nas páginas do assistente DSN do Windows, para quando você configura uma fonte de dados pela interface em vez de uma cadeia de conexão.
Pool de conexões com reconhecimento de driver (Windows) Quais palavras-chave e atributos da cadeia de conexão colocam uma conexão em seu próprio pool, e quais exigem uma ida e volta adicional para serem redefinidos.

Autenticar e proteger

Artigo Description
Usar Microsoft Entra ID com o driver ODBC Cada valor de palavra-chave Authentication, de identidade gerenciada e entidade de serviço até interativo e integrado, com a configuração que cada um precisa.
Usar Always Encrypted com o driver ODBC Criptografe colunas sensíveis no processo cliente para que o texto simples nunca chegue ao servidor, com o resumo da API do driver e suas limitações documentadas.
Classificação de dados Leia os rótulos de sensibilidade que o servidor atribui às colunas classificadas, para que sua aplicação possa aplicar sua própria política de proteção de dados.
Usar autenticação integrada (Linux e macOS) Configure o Kerberos para que um cliente Linux ou macOS possa se conectar com credenciais do Windows em vez de um login do SQL Server.

Alta disponibilidade e resiliência

Artigo Description
Resiliência de conexão Como ConnectRetryCount e ConnectRetryInterval restauram uma conexão quando o servidor a interrompe por inatividade, e os erros IMCxx que o driver retorna quando a recuperação não é possível.
Alta disponibilidade e recuperação de desastre Conecte-se por meio de um listener de grupo de disponibilidade e use MultiSubnetFailover para que o failover não fique bloqueado por um tempo limite da sub-rede.
Use resolução IP de rede transparente Como o mecanismo de fallback legado TransparentNetworkIPResolution ordena as tentativas de conexão em vários endereços IP e por que MultiSubnetFailover o substitui.

Trabalhar com dados

Artigo Description
Tipo de dados de vetor Vincule, envie e recupere o tipo vetorial , incluindo sua representação nativa em C e suporte a cópias em massa.
Use transações XA com DTC Insale o SQL Server em uma transação distribuída através do Coordenador de Transações Distribuídas da Microsoft no Windows, Linux ou macOS.
Diretrizes de programação (Linux e macOS) Quais recursos o driver oferece suporte no Linux e no macOS, quais não, e como o conjunto de caracteres e o tratamento do OpenSSL diferem em relação ao Windows.

Diagnosticar e solucionar problemas

Artigo Description
Solução de problemas de criptografia de conexão Corrija os erros de certificado e de criptografia que a versão 18 gera porque criptografa por padrão.
Rastreamento de acesso a dados (Linux e macOS) Ative o rastreamento de motoristas e capture um arquivo de log quando precisar ver as chamadas que seu aplicativo realmente faz.
Problemas conhecidos (Linux e macOS) Defeitos confirmados e suas soluções alternativas. Confira aqui antes de abrir um chamado de suporte.
Perguntas frequentes (Linux e macOS) Respostas curtas para as perguntas que mais surgem sobre o driver no Linux e macOS.

Notas de lançamento e correções de bugs

Artigo Description
Notas de lançamento para Windows Novos recursos, mudanças de comportamento e correções em cada versão do driver do Windows.
Notas de lançamento para Linux e macOS Novos recursos, mudanças de comportamento e correções em cada lançamento de drivers para Linux e macOS.
Notas de atualização para as ferramentas do SQL Server Alterações nas utilidades sqlcmd e bcp , que são instaladas separadamente do driver no Linux e macOS.

Reference

Artigo Description
Driver ODBC no Windows Um resumo versão por versão do que o driver suporta no Windows e um índice dos artigos específicos do Windows.
Recursos do driver ODBC no Windows Qual versão introduziu cada recurso do Windows, além das mudanças de comportamento que vieram junto.

Solicitar um recurso

Para solicitar uma funcionalidade, envie uma ideia por meio do feedback do SQL Server.

Conteúdo relacionado

  • Last updated on