Perguntas Frequentes sobre ODBC em Linux e macOS

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

A alteração de atualização que afeta a maioria das aplicações é que o Driver 18 encripta as ligações por defeito. Para ver todas as diferenças, veja Diferenças entre versões principais.

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

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

O driver no Linux e macOS suporta a maioria das funcionalidades do SQL Server. Não suporta o registo distribuído de transações através do SQL_ATTR_ENLIST_IN_DTC atributo, espelhamento de base de dados, FILESTREAM ou os atributos de perfil de desempenho do driver. O LocalDB não está disponível no Linux ou macOS. As transações XA através do Distributed Transaction Coordinator (DTC) são suportadas a partir do Driver 17.3. Para mais informações, consulte Usar transações XA com DTC. Para a lista completa, veja Limitações.

No. O driver Microsoft ODBC para SQL Server não é open source.

O driver utiliza o gestor de drivers unixODBC. Quando instalas o Driver 17 ou 18 com o gestor de pacotes ou o Homebrew da tua plataforma, o unixODBC é instalado como uma dependência. Segue os passos para Linux ou macOS.

No macOS, constrói e executa a tua aplicação com unixODBC em vez de iODBC. Faça corresponder a arquitetura do processador da aplicação, gestor de drivers e driver. Um erro como incompatible architecture (have 'arm64', need 'x86_64') indica uma incompatibilidade de arquitetura, não necessariamente o gestor de drivers errado.

Corre odbcinst -q -d para listar os controladores registados. A saída mostra o nome de cada driver exatamente como uma cadeia de ligação deve escrever:

[ODBC Driver 18 for SQL Server]

Execute odbcinst -j para mostrar a versão unixODBC e os caminhos de odbcinst.ini, que regista os drivers, e odbc.ini, que contém os nomes das fontes de dados do sistema e do utilizador (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 ligaçã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 estas causas por ordem:

1. O Driver valor na cadeia de ligação ou DSN não corresponde a um nome de driver registado. Executa odbcinst -q -d e copia o nome exatamente.
2. A tua aplicação usa ficheiros de configuração diferentes dos que editaste. Executa odbcinst -j a partir do mesmo ambiente que a aplicação e verifica qual o gestor de drivers que a aplicação carrega. No macOS, crie ligações simbólicas de configuração apenas se a aplicação precisar delas, conforme descrito em Resolução de Problemas no macOS.
3. Mais do que uma cópia do gestor de drivers unixODBC está instalada, e a sua aplicação carrega o gestor errado. Em Linux, execute find /usr -name 'libodbc*.so*'. No macOS, execute find /opt/homebrew /usr/local -name 'libodbc*.dylib'. Vários caminhos, por si só, não provam que vários gestores de controladores estão instalados: as ligações do Homebrew podem apontar para a mesma biblioteca no seu diretório Cellar. Verifica qual a biblioteca que a aplicação carrega realmente. Para mais informações, consulte Resolver problemas de ligação.

O Driver 18 é a predefinição para Encrypt=yes. O driver 17 usa Encrypt=no por predefinição apenas quando não há nenhuma configuração não vazia Authentication ou token de acesso fornecido. Uma definição não vazia Authentication , incluindo Authentication=SqlPassword, ou um token de acesso, altera o Driver 17 por defeito para Encrypt=yes. Definições explícitas de encriptação sobrepõem-se a estas predefinições.

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

Com Encrypt=yes e TrustServerCertificate=no, ambos os drivers encriptam a ligação e validam o certificado do servidor. Com Encrypt=no, o Driver 17 não valida o certificado, enquanto o Driver 18 valida-o se o servidor forçar a encriptação e TrustServerCertificate=no. Uma ligação que anteriormente usava o padrão do Driver 17 Encrypt=no pode, portanto, falhar com o Driver 18 contra um servidor com um certificado auto-assinado ou de outra forma não confiável. Com um certificado auto-assinado, 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 de confiança ou certificate pinning. Utilize estas opções:

• Instala um certificado no servidor emitido por uma autoridade certificadora em que o cliente confia. Se o certificado for confiável mas o seu nome não corresponder ao valor de Server, defina HostNameInCertificate para o nome no certificado. HostNameInCertificate Muda apenas o nome esperado, por isso não corrige um certificado auto-assinado.
• Com o Driver 18.1 e versões posteriores e um servidor que suporta o Tabular Data Stream (TDS) 8.0, defina Encrypt=strict e defina ServerCertificate para o caminho de uma cópia do certificado do servidor. O condutor aceita então apenas esse certificado exato. ServerCertificate funciona apenas em modo estrito.
• Define Encrypt=no apenas se aceitares tráfego de aplicações não encriptado quando o servidor não forçar a encriptação. Isto corresponde ao padrão do Driver 17 apenas quando não é fornecida nenhuma configuração não vazia Authentication nem token de acesso e não há substituição de encriptação definida. Se o servidor forçar a encriptação, o Driver 18 continua a validar o certificado, a menos que TrustServerCertificate=yes desative a validação.

Para mais informações, veja Comportamento de encriptação por defeito.

Sim. Obtém um ticket Kerberos com kinit, e depois liga-te a Trusted_Connection=yes na cadeia de ligação ou DSN. A instância do SQL Server necessita de um nome principal de serviço (SPN) registado. Para os passos de configuração, veja Usar autenticação integrada.

Sim, para Base de Dados SQL do Azure, Azure SQL Managed Instance e SQL Server 2022 e versões posteriores. Para configurar o SQL Server, incluindo através do Azure Arc, utilize 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 gerida, com Authentication=ActiveDirectoryMsi, começando pelo Driver 17.3.
• service principal, com Authentication=ActiveDirectoryServicePrincipal, a partir do Driver 17.7.
• Autenticação integrada através do Kerberos num ambiente federado, com Authentication=ActiveDirectoryIntegrated, a partir do Driver 17.6.
• Um token de acesso que a sua aplicação obtém, passado através do SQL_COPT_SS_ACCESS_TOKEN atributo de conexão.

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

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

Para strings de ligaçã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 (API) ODBC e compilada com base em unixODBC pode carregar este controlador. Para utilizar funcionalidades específicas do SQL Server, inclua msodbcsql.h depois dos cabeçalhos unixODBC. Para comandos de compilador e nomes de bibliotecas, veja Desenvolver aplicações em C e C++ com o driver ODBC.

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

Os ficheiros de rastreio podem conter dados sensíveis. Na conta que executa a sua aplicação, crie um diretório ao qual só essa conta possa aceder:

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

Adicione estas definições à [ODBC] secção de odbcinst.ini. Substitui /home/<user>/odbc-trace/odbctrace.log pelo caminho absoluto dentro do diretório que criaste. No macOS, os diretórios domésticos normalmente usam /Users/<user> em vez de /home/<user>.

Mantenha o caminho completo do ficheiro de rastreamento com 62 bytes ou menos para evitar truncamento pelo unixODBC.

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

Estas definições permitem o rastreamento para aplicações que utilizam esta configuração de gestor de drivers, e o rastreio atrasa-as. Utilize um diretório privado separado para cada conta de aplicação. Remove Trace = Yes quando terminares e apaga os ficheiros de rastreamento que já não precisas. Para rastreamento por aplicação, veja Rastreio de acesso a dados no Linux e macOS.

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

Utilize UTF-8 para SQLCHAR dados. A partir do Driver 17, o driver também aceita um conjunto de páginas de código de um ou dois bytes para dados SQLCHAR quando a configuração regional do processo seleciona uma. Os processos começam no C locale, por isso o driver usa UTF-8, a menos que a aplicação chame setlocale. Para a lista de codificações, veja Processar dados de caráter.