Driver ODBC da Microsoft para SQL Server

Baixar driver ODBC

ODBC é a principal API nativa de acesso a dados para aplicativos escritos em C e C++ para SQL Server. O Microsoft ODBC Driver for SQL Server estabelece ligação ao SQL Server, ao Base de Dados SQL do Azure, ao Azure SQL Managed Instance, ao Azure Synapse Analytics e à base de dados SQL do Microsoft Fabric. Para as versões da base de dados que cada versão de driver suporta, consulte compatibilidade de versões SQL.

Outras linguagens que podem usar ODBC incluem COBOL, Perl, PHP e Python. O 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 este driver.

Os utilitários sqlcmd e bcp funcionam com este driver, mas instalam-se separadamente: o mssql-tools18 pacote no Linux e macOS, e os Microsoft Command Line Utilities no Windows. Use sqlcmd para executar instruções Transact-SQL (T-SQL), procedimentos do sistema e ficheiros de script. Utilize bcp para copiar dados em massa entre uma instância do SQL Server e um ficheiro de dados, em ambas as direções.

Escolhe o teu ponto de partida

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

Use este excerto como ponto de partida para uma ligação SQL do Azure orientada para produção. Carrega o nome do servidor e o nome da base de dados a partir da configuração da aplicação, autentica-se com uma identidade gerida para que não apareça segredo na cadeia de ligação, e permite a encriptação do Tabular Data Stream (TDS) 8.0 com validação completa do certificado. Define um tempo limite de início de sessão por tentativa e repete as tentativas em caso de falhas transitórias, com recuo exponencial e jitter.

O excerto em C++ neste artigo omite as diretivas include, a alocação de handles e a função auxiliar de registo por uma questão de 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 ativam a resiliência da ligação inativa, que restaura de forma transparente uma ligação que foi interrompida durante a inatividade. Eles não tentam novamente a ligação inicial, razão pela qual este snippet também implementa uma retentativa ao nível da aplicação. Mantém ambos.

O ODBC apresenta diagnósticos através de SQLGetDiagRec, e não apenas do código de retorno, pelo que classifique os erros antes de voltar a tentar. Uma operação falha imediatamente devido a um erro de autenticação ou de configuração, em vez de consumir todo o limite de tentativas de repetição.

Para mais informações sobre cada parte desta configuração, veja:

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

Principais características

  • Multiplataforma: A mesma API no Windows, Linux e macOS.
  • Autenticação do Microsoft Entra ID: Ligações sem palavra-passe com identidade gerida, entidade de serviço e fluxos interativos e integrados.
  • Encriptação rigorosa: ligações TDS 8.0 com validação completa de certificados na versão 18 e versões posteriores.
  • Always Encrypted: Encriptação do lado do cliente para colunas sensíveis, com suporte para provedores personalizados de arquivo de chaves.
  • Resiliência da ligação: Restauração transparente de uma ligação que caiu enquanto estava inativa.
  • Alta disponibilidade: Disponibilidade de apoio de ouvintes 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 através do Coordenador de Transações Distribuídas da Microsoft (MSDTC).
  • Ferramentas complementares: sqlcmd e bcp, instaladas separadamente.

Introdução

Artigo Description
Descarregar o Controlador ODBC para SQL Server Instaladores e transferências de pacotes para todas as versões de controladores suportadas, para as três plataformas.
Desenvolver aplicações em C e C++ com o driver ODBC Quais os cabeçalhos a incluir, por que ordem, que bibliotecas a ligar e como escolher entre execução assíncrona e threads.
Ligue-se e consulte uma base de dados com C++ Um exemplo completo em C++ que liga, executa uma consulta e lê resultados, para que possas confirmar a tua configuração de ponta a ponta.
Ciclo de vida do suporte Quais as versões dos drivers ainda suportadas e a data em que cada uma sai do suporte.
Principais diferenças de versão O que falha quando se passa da versão 17 para a versão 18, começando pela alteração padrão da encriptação.

Instale o controlador

Artigo Description
Requisitos do sistema, instalação e ficheiros de drivers (Windows) Versões do Windows suportadas, a linha de comandos do instalador para instalação silenciosa e onde cada ficheiro do controlador é guardado no disco.
Requisitos do sistema (Linux e macOS) Quais distribuições Linux e versões do macOS suportam cada versão do driver, além da compatibilidade com versões do SQL Server.
Instale o controlador ODBC no Linux Etapas do gestor de pacotes para Alpine, Debian, Red Hat, SUSE, Ubuntu e Azure Linux, além da instalação offline e das localizações dos ficheiros dos drivers.
Instale o driver ODBC no macOS Passos para o tap e as fórmulas do Homebrew no macOS, incluindo como instalar a versão 18, 17 ou 13.1.
Instale o gestor de drivers unixODBC (Linux e macOS) Instale ou atualize o unixODBC, o gestor de drivers que carrega o driver ODBC no Linux e macOS.

Configurar e ligar

Artigo Description
Palavras-chave e atributos de DSN e de cadeias de ligação O catálogo completo de palavras-chave de cadeia de ligação, entradas DSN e atributos SQLSetConnectAttr, com os valores aceites para cada um.
Palavras-chave de string de ligação e nomes de fontes de dados (Linux e macOS) Como odbc.ini e odbcinst.ini definem uma DSN no Linux e no macOS, bem como as definições de TLS e de 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 configuras uma fonte de dados através da interface em vez de uma cadeia de ligação.
Agrupamento de ligações com reconhecimento do controlador (Windows) Que palavras‑chave e atributos da cadeia de ligação colocam uma ligação no seu próprio grupo, e quais implicam uma ida e volta adicional para a repor.

Autenticar e proteger

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

Alta disponibilidade e resiliência

Artigo Description
Resiliência da ligação Como ConnectRetryCount e ConnectRetryInterval restauram uma ligação quando o servidor a interrompe quando esta está inativa, e os erros IMCxx que o controlador devolve quando a recuperação não é possível.
Alta disponibilidade e recuperação de desastres Liga-te através de um ouvinte de grupo de disponibilidade e usa MultiSubnetFailover para que o failover não fique bloqueado num timeout de subrede.
Utilizar resolução IP de rede transparente Como a alternativa legada TransparentNetworkIPResolution ordena as tentativas de ligação entre vários endereços IP e por que motivo MultiSubnetFailover a substitui.

Trabalhar com dados

Artigo Description
Tipo de dados vetoriais Associar, enviar e recuperar o tipo vetor, incluindo a sua representação nativa em C e suporte para cópia em massa.
Usar transações XA com DTC Inscreva o SQL Server numa 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) Que funcionalidades o controlador suporta no Linux e no macOS, quais não suporta e como o conjunto de caracteres e o tratamento do OpenSSL diferem do Windows.

Diagnosticar e solucionar problemas

Artigo Description
Resolução de problemas de encriptação de ligação Corrigir os erros de certificado e encriptação que a versão 18 revela porque ela encripta por defeito.
Rastreio de acesso a dados (Linux e macOS) Ativa o rastreio de condutores e captura um ficheiro de registo quando precisares de ver as chamadas que a tua aplicação realmente faz.
Problemas conhecidos (Linux e macOS) Defeitos confirmados e as suas soluções alternativas. Consulte aqui antes de submeter um pedido de suporte.
Perguntas frequentes (Linux e macOS) Respostas curtas às perguntas que surgem mais frequentemente sobre o driver no Linux e macOS.

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

Artigo Description
Notas de lançamento para Windows Novas funcionalidades, alterações de comportamento e correções em cada versão do driver do Windows.
Notas de lançamento para Linux e macOS Novas funcionalidades, alterações 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 às utilidades sqlcmd e bcp , que se instalam separadamente do driver no Linux e macOS.

Reference

Artigo Description
Controlador ODBC no Windows Um resumo, versão por versão, do que é suportado pelo controlador no Windows e um índice dos artigos específicos do Windows.
Funcionalidades do driver ODBC no Windows Qual das versões introduziu cada funcionalidade do Windows, além das alterações de comportamento associadas.

Pedir uma funcionalidade

Para solicitar uma funcionalidade, submeta uma ideia através do feedback do SQL Server.

Conteúdo relacionado

  • Last updated on