Problemas conhecidos do driver ODBC no Linux e macOS

  • Artigo

Baixar driver ODBC

Este artigo contém uma lista de problemas conhecidos com o Microsoft ODBC Driver 13, 13.1, 17 e 18 para SQL Server em Linux e macOS. Ele também contém etapas para solucionar problemas de conectividade.

Problemas conhecidos

Problemas adicionais serão postados no blog de Drivers do SQL Server.

  • Devido às limitações da biblioteca do sistema, o Alpine Linux é compatível com menos codificações e localidades de caracteres. Por exemplo, en_US.UTF-8 não está disponível. Para saber mais, confira musl libc – Diferenças funcionais em relação ao glibc.

  • Windows, Linux e macOS convertem caracteres da PUA (Área de Uso Particular) ou EUDC (Caracteres Definidos pelo Usuário Final ) de maneira diferente. Conversões executadas no servidor no Transact-SQL usam a biblioteca de conversão do Windows. Conversões no driver usam as bibliotecas de conversão do Windows, do Linux ou do macOS. Cada biblioteca pode produzir resultados diferentes ao executar as conversões. Para obter mais informações, confira End-User-Defined and Private Use Area Characters (Caracteres de área de uso privado e definidos pelo usuário final).

  • Se a codificação de cliente for UTF-8, o gerenciador de driver nem sempre converterá corretamente UTF-8 em UTF-16. Atualmente, os dados são corrompidos quando um ou mais caracteres da cadeia de caracteres não são caracteres UTF-8 válidos. Caracteres ASCII são mapeados corretamente. O gerenciador de driver tentará fazer essa conversão ao chamar as versões SQLCHAR da API do ODBC (por exemplo, SQLDriverConnectA). O gerenciador de driver não tentará fazer essa conversão ao chamar as versões SQLWCHAR da API ODBC (por exemplo, SQLDriverConnectW).

  • O parâmetro ColumnSize do SQLBindParameter refere-se ao número de caracteres no tipo SQL, enquanto BufferLength é o número bytes no buffer do aplicativo. No entanto, se o tipo de dados SQL for varchar(n) ou char(n), o aplicativo associar o parâmetro como SQL_C_CHAR para o tipo C e SQL_CHAR ou SQL_VARCHAR para o tipo SQL e a codificação de caracteres do cliente for UTF-8, você poderá receber um erro "Dados da cadeia de caracteres, truncamento à direita" do driver, mesmo se o valor de ColumnSize estiver alinhado com o tamanho do tipo de dados no servidor. Esse erro ocorre porque as conversões entre codificações de caracteres podem mudar o comprimento dos dados. Por exemplo, um caractere de apóstrofo reto (U+2019) é codificado em CP-1252 como o byte único 0x92, mas, em UTF-8, como a sequência de 3 bytes 0xe2 0x80 0x99.

Por exemplo, se a codificação for UTF-8 e você especificar 1 para BufferLength e para ColumnSize em SQLBindParameter para um parâmetro de saída e então tentar recuperar o caractere precedente armazenado em uma coluna char(1) no servidor (usando CP-1252), o driver tentará convertê-lo na codificação de 3 bytes UTF-8, mas não conseguirá colocar o resultado em um buffer de 1 byte. Na outra direção, ele compara ColumnSize com o BufferLength no SQLBindParameter antes de fazer a conversão entre as diferentes páginas de código no cliente e no servidor. Como um ColumnSize de valor 1 é menor que um BufferLength de valor 3 (por exemplo), o driver gerará um erro. Para evitar esse erro, verifique se o comprimento dos dados após a conversão se adapta à coluna ou ao buffer especificado. Observe que ColumnSize não pode ser maior que 8000 para o tipo varchar(n).

Solucionar problemas de conexão

Se não for possível estabelecer uma conexão com o SQL Server usando o driver ODBC, use as informações a seguir para identificar o problema.

O problema de conexão mais comum é ter duas cópias do gerenciador de driver UnixODBC instaladas. Pesquise por libodbc*.so* em /usr. Se houver mais de uma versão do arquivo, você (possivelmente) tem mais de um gerenciador de driver instalado. Seu aplicativo pode usar a versão errada.

Habilite o log de conexão editando seu arquivo /etc/odbcinst.ini para conter a seção a seguir com estes itens:

[ODBC]
Trace = Yes
TraceFile = (path to log file, or /dev/stdout to output directly to the terminal)

Se você receber outra falha de conexão e não vir um arquivo de log, (possivelmente) haverá duas cópias do gerenciador de driver no computador. Caso contrário, a saída do log será semelhante a:

[ODBC][28783][1321576347.077780][SQLDriverConnectW.c][290]
        Entry:
            Connection = 0x17c858e0
            Window Hdl = (nil)
            Str In = [DRIVER={ODBC Driver 18 for SQL Server};SERVER={contoso.com};Trusted_Connection={YES};WSID={mydb.contoso.com};AP...][length = 139 (SQL_NTS)]
            Str Out = (nil)
            Str Out Max = 0
            Str Out Ptr = (nil)
            Completion = 0
        UNICODE Using encoding ASCII 'UTF8' and UNICODE 'UTF16LE'

Se a codificação de caracteres ASCII não for UTF-8, por exemplo:

UNICODE Using encoding ASCII 'ISO8859-1' and UNICODE 'UCS-2LE'

Há mais de um gerenciador de driver instalado, e o seu aplicativo está usando um incorreto ou o gerenciador de driver não foi compilado corretamente.

Alguns usuários do macOS encontram o seguinte erro com a versão 17.8 ou mais antiga do driver:
(Esse erro foi resolvido na versão 17.9 e posteriores do driver)

[08001][Microsoft][ODBC Driver 17 for SQL Server]SSL Provider: [OpenSSL library could not be loaded, make sure OpenSSL 1.0 or 1.1 is installed]
[08001][Microsoft][ODBC Driver 17 for SQL Server]Client unable to establish connection (0) (SQLDriverConnect)

O erro pode ocorrer quando o OpenSSL 3.0 está instalado. O OpenSSL normalmente é instalado por meio do Brew e contém os binários openssl, openssl@1.1 e openssl@3.

Para resolver esse erro, altere o symlink do binário openssl para openssl@1.1:

rm -rf $(brew --prefix)/opt/openssl
version=$(ls $(brew --prefix)/Cellar/openssl@1.1 | grep "1.1")
ln -s $(brew --prefix)/Cellar/openssl@1.1/$version $(brew --prefix)/opt/openssl

Para obter mais informações sobre como resolver falhas de conexão, consulte:

Próximas etapas

Para obter instruções de instalação do driver ODBC, confira os seguintes artigos:

Para obter mais informações, confira as Diretrizes de programação e as Notas sobre a versão.