Perguntas Frequentes sobre ODBC no Linux e macOS

Use o Microsoft ODBC Driver 18 para SQL Server, a linha atual de drivers, para novos desenvolvimentos. O Driver ODBC 17 da Microsoft para SQL Server continua suportado para aplicações que já o implantam, conforme descrito no ciclo de vida de suporte.

A mudança de atualização que afeta a maioria dos aplicativos é que o Driver 18 criptografa as conexões por padrão. Para todas as diferenças, veja Diferenças entre versões principais.

O Driver 18 suporta estes sistemas operacionais e arquiteturas de processadores:

As versões do sistema operacional suportadas mudam a cada lançamento do driver. Para a tabela versão por versão, veja Requisitos do Sistema.

O driver no Linux e macOS suporta a maioria dos recursos do SQL Server. Ele não suporta o alistamento distribuído de transações através do SQL_ATTR_ENLIST_IN_DTC atributo, espelhamento de banco de dados, FILESTREAM ou os atributos de perfil de desempenho do driver. O LocalDB não está disponível no Linux ou macOS. Transações XA através do Coordenador de Transações Distribuídas (DTC) são suportadas a partir do Driver 17.3. Para mais informações, veja Usar transações XA com DTC. Para a lista completa, veja Limitações.

No. O driver Microsoft ODBC para SQL Server não é código aberto.

O driver usa o gerenciador de drivers unixODBC. Quando você instala o Driver 17 ou 18 com o gerenciador de pacotes ou Homebrew da sua plataforma, o unixODBC é instalado como uma dependência. Siga os passos para Linux ou macOS.

No macOS, construa e execute sua aplicação com unixODBC em vez de iODBC. Iguale a arquitetura da plataforma da aplicação, do gerenciador de drivers e do driver. Um erro como incompatible architecture (have 'arm64', need 'x86_64') indica um descompasso de arquitetura, não necessariamente o gerenciador de drivers errado.

Execute odbcinst -q -d para listar os drivers registrados. A saída mostra cada nome de driver exatamente como uma cadeia de conexão deve soletrá-lo:

[ODBC Driver 18 for SQL Server]

Execute odbcinst -j para mostrar a versão do unixODBC e os caminhos de odbcinst.ini, que registra os drivers, e de odbc.ini, que contém os nomes das fontes de dados do sistema e do usuário (DSNs):

unixODBC 2.3.11
DRIVERS............: /etc/odbcinst.ini
SYSTEM DATA SOURCES: /etc/odbc.ini
FILE DATA SOURCES..: /etc/ODBCDataSources
USER DATA SOURCES..: /home/<user>/.odbc.ini

Para configurar uma DSN, veja Strings de conexão e DSNs.

O erro é o seguinte:

[01000][unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server' : file not found

Verifique essas causas em ordem:

1. O Driver valor na cadeia de conexão ou DSN não corresponde ao nome do driver registrado. Execute odbcinst -q -d e copie exatamente o nome.
2. Seu aplicativo usa arquivos de configuração diferentes dos que você editou. Execute odbcinst -j a partir do mesmo ambiente que a aplicação e verifique qual gerenciador de drivers a aplicação carrega. No macOS, crie links simbólicos de configuração apenas se a aplicação precisar deles, conforme descrito em Solução de Problemas no macOS.
3. Mais de uma cópia do gerenciador de drivers unixODBC está instalada, e seu aplicativo carrega o gerenciador errado. No Linux, execute find /usr -name 'libodbc*.so*'. No macOS, execute find /opt/homebrew /usr/local -name 'libodbc*.dylib'. Múltiplos caminhos sozinhos não provam que múltiplos gerenciadores de drivers estão instalados: links homebrew podem apontar para a mesma biblioteca no diretório Cellar. Verifique qual biblioteca o aplicativo realmente carrega. Para mais informações, veja Solucionar problemas de conexão.

O driver 18 usa Encrypt=yes por padrão. O driver 17 usa Encrypt=no por padrão apenas quando nenhuma configuração Authentication não vazia ou token de acesso é fornecido. Uma configuração não vazia Authentication , incluindo Authentication=SqlPassword, ou um token de acesso, altera o Driver 17 por padrão para Encrypt=yes. Configurações explícitas de criptografia sobrepõem esses padrões.

Verifique as configurações efetivas na sua cadeia de conexão, DSN e atributos de pré-conexão definidos por SQLSetConnectAttr. Por exemplo, Encrypt=yes em uma DSN ou SQL_COPT_SS_ENCRYPT=SQL_EN_ON solicita criptografia mesmo quando a cadeia de conexão omite Encrypt. Forneça tokens de acesso apenas através do atributo de conexão SQL_COPT_SS_ACCESS_TOKEN, não de uma palavra-chave de cadeia de conexão.

Com Encrypt=yes e TrustServerCertificate=no, ambos os drivers criptografam a conexão e validam o certificado do servidor. Com Encrypt=no, o Driver 17 não valida o certificado, enquanto o Driver 18 o valida se o servidor forçar a criptografia e TrustServerCertificate=no. Uma conexão que anteriormente usava o padrão do Driver 17 Encrypt=no pode, portanto, falhar com o Driver 18 contra um servidor com certificado autoassinado ou não confiável. Com um certificado autoassinado, o erro do Driver 18 é o seguinte:

[Microsoft][ODBC Driver 18 for SQL Server]SSL Provider: [error:0A000086:SSL routines::certificate verify failed:self-signed certificate]
[Microsoft][ODBC Driver 18 for SQL Server]Client unable to establish connection. For solutions related to encryption errors, see https://go.microsoft.com/fwlink/?linkid=2226722

Prefira um certificado confiável ou a fixação de certificado. Use estas opções:

• Instale um certificado no servidor emitido por uma autoridade certificadora em quem o cliente confia. Se o certificado for confiável, mas seu nome não corresponder ao valor de Server, defina HostNameInCertificate para o nome no certificado. HostNameInCertificate muda apenas o nome esperado, então não corrige um certificado autoassinado.
• Com o Driver 18.1 e versões posteriores e um servidor que suporta Tabular Data Stream (TDS) 8.0, defina Encrypt=strict e defina ServerCertificate como o caminho de uma cópia do certificado do servidor. O motorista então aceita apenas esse certificado exato. ServerCertificate funciona apenas no modo estrito.
• Defina Encrypt=no somente se você aceitar tráfego de aplicação não criptografado quando o servidor não forçar criptografia. Isso corresponde ao padrão do Driver 17 apenas quando nenhuma configuração não vazia Authentication ou token de acesso é fornecido e nenhuma substituição de criptografia é definida. Se o servidor forçar a criptografia, o Driver 18 ainda valida o certificado, a menos que TrustServerCertificate=yes desative a validação.

Para mais informações, veja Comportamento padrão de criptografia.

Sim. Receba um ticket Kerberos com kinit, e depois conecte-se com Trusted_Connection=yes na cadeia de conexão ou DSN. A instância do SQL Server precisa de um nome principal de serviço (SPN) registrado. Para ver as etapas de configuração, veja Usar autenticação integrada.

Sim, para Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure e SQL Server 2022 e versões posteriores. Para configurar o SQL Server, inclusive via Azure Arc, use a autenticação Microsoft Entra para o SQL Server. No Linux e macOS, o Driver 17 e versões posteriores suportam estes métodos:

• Identidade gerenciada, com Authentication=ActiveDirectoryMsi, a partir do Driver 17.3.
• Entidade de serviço, com Authentication=ActiveDirectoryServicePrincipal, começando com o Driver 17.7.
• Autenticação integrada via Kerberos em um ambiente federado, com Authentication=ActiveDirectoryIntegrated, começando pelo Driver 17.6.
• Um token de acesso que sua aplicação obtém, passado pelo atributo de conexão SQL_COPT_SS_ACCESS_TOKEN.

ActiveDirectoryInteractiveestá disponível apenas no driver do Windows. ActiveDirectoryPassword está obsoleto. A autenticação gerenciada por drivers no Linux e macOS não suporta cenários que exigem políticas de acesso condicional. Se sua aplicação adquirir um token de acesso separadamente, a biblioteca de autenticação e as políticas do Microsoft Entra ID regerão esse processo de aquisição do token. Passe o token através de SQL_COPT_SS_ACCESS_TOKEN.

No Alpine Linux, a autenticação integrada requer uma compilação libcurl com suporte ao Mecanismo de Negociação de Interface de Programa de Aplicação de Serviço Genérico de Segurança Simples e Protegida (SPNEGO). Verifique suas capacidades instaladas libcurl em vez de assumir que o pacote padrão suporta isso.

Para strings de conexão e exemplos de código, veja Usar o Microsoft Entra ID com o driver ODBC.

Sim. Uma aplicação escrita na interface de programação de aplicações ODBC (API) e compilada com unixODBC pode carregar esse driver. Para usar recursos específicos do SQL Server, inclua msodbcsql.h após os cabeçalhos unixODBC. Para comandos de compilador e nomes de bibliotecas, veja Desenvolver aplicações em C e C++ com o driver ODBC.

Sim. Conecte-se e consulte com C++ e ODBC compila e executa um exemplo no Linux, macOS e Windows.

Arquivos de rastreamento podem conter dados sensíveis. Como conta que roda sua aplicação, crie um diretório que somente essa conta possa acessar:

mkdir -m 700 "$HOME/odbc-trace"

Adicione essas configurações à seção [ODBC] de odbcinst.ini. Substitua /home/<user>/odbc-trace/odbctrace.log pelo caminho absoluto dentro do diretório que você criou. No macOS, os diretórios domésticos normalmente usam /Users/<user> em vez de /home/<user>.

Mantenha o caminho completo do arquivo de traço em 62 bytes ou menos para evitar truncamento pelo unixODBC.

[ODBC]
Trace = Yes
TraceFile = /home/<user>/odbc-trace/odbctrace.log

Essas configurações permitem o rastreamento para aplicações que usam essa configuração do gerenciador de drivers, e o rastreamento os atrasa. Use um diretório privado separado para cada conta de aplicação. Remova Trace = Yes quando terminar e apague os arquivos de rastreamento que não precisa mais. Para rastreamento por aplicação, veja rastreamento de acesso a dados no Linux e macOS.

Use UTF-16LE (little endian) para dados SQLWCHAR. Use buffers UTF-16 SQLWCHAR com as APIs ODBC de caracteres largos em vez do tipo nativo wchar_t, que é de 32 bits no Linux e macOS.

Use UTF-8 para os dados SQLCHAR. A partir do Driver 17, o driver também aceita um conjunto de páginas de código de byte único e de byte duplo para dados SQLCHAR quando a localidade do processo seleciona uma. Os processos começam no C locale, então o driver usa UTF-8, a menos que o aplicativo chame setlocale. Para a lista de codificações, veja Processar dados de caracteres.