Diretrizes de programação

Baixar driver ODBC

Este artigo descreve considerações de programação para aplicações que utilizam o Driver Microsoft ODBC para SQL Server no Linux ou macOS. Alguns links apontam para material do SQL Server Native Client. Essas páginas fornecem contexto histórico da API.

Escolha uma versão de driver

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. O ODBC Driver 13, que foi lançado com o SQL Server 2017, é elegível para suporte estendido até 12 de outubro de 2027, apenas sob um acordo de suporte estendido.

Especifique o nome do driver instalado na sua cadeia de conexão, entre chaves:

Driver={ODBC Driver 18 for SQL Server}

Driver={ODBC Driver 17 for SQL Server}

Em um nome de fonte de dados (DSN) em odbc.ini, use o nome sem chaves, por exemplo Driver = ODBC Driver 18 for SQL Server. Para a sintaxe DSN, veja Palavras-chave de string de conexão e nomes de fontes de dados (DSNs).

Para configurações de conexão específicas de cada versão, veja Diferenças principais de versão. Para datas de suporte e compatibilidade do sistema operacional, veja Ciclo de vida de Suporte e requisitos do sistema.

Construa uma aplicação

Para obter as localizações de cabeçalhos, a ordem de inclusão, os comandos do compilador, os nomes das bibliotecas e um exemplo em C++, veja Desenvolver aplicativos C e C++ com o driver ODBC e Conectar e consultar com C++ e ODBC.

Uma aplicação ODBC pode usar Múltiplos Conjuntos de Resultados Ativos (MARS) e outros recursos específicos do SQL Server ao incluir msodbcsql.h após os cabeçalhos unixODBC (sql.h, sqlext.h, sqltypes.h, e sqlucode.h). Use os mesmos nomes simbólicos para os itens específicos do SQL Server que você usaria em seus aplicativos ODBC do Windows.

Encontrar recursos do driver

Comece com a Referência do Programador ODBC para a interface padrão de programação de aplicações (API). Depois, use a documentação atual do driver para o comportamento específico do driver.

A visão geral do driver Microsoft ODBC para SQL Server faz links para a documentação do driver. Os seguintes artigos do SQL Server Native Client fornecem contexto de API para aplicações que utilizam o driver no Linux e macOS:

Limitations

Os seguintes recursos não foram verificados para funcionar corretamente no driver ODBC no Linux e macOS:

Recursos sem suporte

Os seguintes recursos não estão disponíveis no driver ODBC no Linux e macOS:

  • Transações distribuídas por meio do atributo SQL_ATTR_ENLIST_IN_DTC. O driver suporta transações XA por meio do Coordenador de Transações Distribuídas da Microsoft (DTC). Para mais informações, veja Usar transações XA com DTC.

  • Espelhamento de banco de dados.

  • FILESTREAM.

  • Criação de perfil do desempenho do driver ODBC, discutido em SQLSetConnectAttr, e estes atributos de conexão relacionados ao desempenho:

    • SQL_COPT_SS_PERF_DATA
    • SQL_COPT_SS_PERF_DATA_LOG
    • SQL_COPT_SS_PERF_DATA_LOG_NOW
    • SQL_COPT_SS_PERF_QUERY
    • SQL_COPT_SS_PERF_QUERY_INTERVAL
    • SQL_COPT_SS_PERF_QUERY_LOG

  • SQLBrowseConnect antes da versão 17.2.

  • Tipos de intervalo C como SQL_C_INTERVAL_YEAR_TO_MONTH, documentados em Identificadores e Descritores de Tipo de Dados.

  • O valor SQL_CUR_USE_ODBC do atributo SQL_ATTR_ODBC_CURSORS de SQLSetConnectAttr.

Manipular dados de caracteres

No Linux e macOS, use buffers UTF-16 SQLWCHAR com APIs ODBC de caractere amplo em vez do tipo nativo wchar_t . A interface do controlador utiliza unidades de código de 16 bits.

Codificações de caracteres

Para os drivers ODBC 13 e 13.1, você deve usar UTF-8 para SQLCHAR dados. Essas versões não suportam outras codificações.

A partir do Driver ODBC 17, conjuntos de caracteres e codificações suportados para dados SQLCHAR incluem:

Observação

Devido a diferenças de iconv entre musl e glibc, muitos desses locais não são compatíveis com o Alpine Linux. Para mais informações, veja Diferenças funcionais em relação ao glibc.

Nome Descrição
UTF-8 Unicode
CP437 MS-DOS Latim EUA
CP850 MS-DOS Latim 1
CP874 Latim/tailandês
CP932 Japonês (página de código do Windows 932)
CP936 Chinês simplificado, GBK
CP949 Coreano (página de código do Windows 949)
CP950 Chinês tradicional, Big5
CP1250 Europeu Central
CP1251 Cirílico
CP1252 Europa Ocidental
CP1253 Grego
CP1254 Turco
CP1255 Hebraico
CP1256 Árabe
CP1257 Báltico
CP1258 Vietnamita
ISO-8859-1 Latim-1
ISO-8859-2 Latim-2
ISO-8859-3 Latim-3
ISO-8859-4 Latim-4
ISO-8859-5 Latim/cirílico
ISO-8859-6 Latim/árabe
ISO-8859-7 Latim/grego
ISO-8859-8 Hebraico
ISO-8859-9 Turco
ISO-8859-13 Latim-7
ISO-8859-15 Latim-9

Ao conectar, o driver detecta a localidade atual do processo em que ele é carregado. Se a localidade usar uma das codificações listadas, o driver usa essa codificação para dados SQLCHAR (caracteres estreitos). Caso contrário, usa UTF-8 por padrão. Os processos começam no C locale por padrão, o que faz com que o driver use UTF-8 por padrão. Se uma aplicação precisar de uma das codificações listadas, chame setlocale antes de conectar. Especifique explicitamente a localidade ou use uma string vazia (por exemplo, setlocale(LC_ALL, "")) para usar as configurações de localidade do ambiente.

Em um ambiente típico de Linux ou macOS onde a codificação é UTF-8, usuários do ODBC Driver 17 que atualizam do 13 ou 13.1 não notarão diferenças. Aplicações que usam uma codificação setlocale listada que não seja UTF-8 precisam usar essa codificação para dados de e para o driver em vez de UTF-8.

Você deve usar UTF-16LE (little endian) para dados SQLWCHAR .

Quando você vincula parâmetros de entrada usando SQLBindParameter, se você especificar um tipo SQL de caractere estreito, como SQL_VARCHAR, o driver converte os dados fornecidos da codificação do cliente para a codificação do lado do servidor para esse parâmetro. A codificação depende da ordenação; nem sempre é a página de código 1252. Para parâmetros de saída, o driver converte da codificação especificada nas informações de ordenação associadas aos dados na codificação do cliente. Caracteres na codificação de origem que não são representáveis na codificação de destino convertem-se em um ponto de interrogação (?).

Para evitar essa perda de dados ao vincular parâmetros de entrada, especifique um tipo de caractere SQL Unicode, como SQL_WVARCHAR. O driver converte a codificação do cliente para UTF-16, que pode representar todos os caracteres Unicode. A coluna ou parâmetro alvo também deve ser um tipo Unicode (nchar, nvarchar ou ntext) ou um tipo com uma colação ou codificação que possa representar todos os dados de origem originais. Para parâmetros de saída, especifique um tipo Unicode SQL e ou um tipo Unicode C (SQL_C_WCHAR), que faz o driver retornar dados como UTF-16, ou um tipo C não Unicode com uma codificação cliente que pode representar os dados de origem. O UTF-8 sempre pode representar esses dados.

Para obter mais informações sobre ordenações e codificações, confira Compatibilidade com ordenação e Unicode.

Existem diferenças de conversão entre versões de Windows e Linux ou macOSiconv:

  • Para a página de código 1255, byte 0xCA converte para ponto 0x05BA de código UTF-16 no Windows e 0x00CA no macOS e Linux com libiconv versões anteriores à 1.15.
  • Bibliotecas Linux iconv sem a revisão de 2003 do Big5/CP950 (BIG5-2003) não convertem corretamente os caracteres adicionados nessa revisão.
  • Para a página de código 932 (japonês, Shift-JIS), a decodificação de caracteres não definidos no padrão de codificação é diferente. Por exemplo, o byte 0x80 é convertido em U+0080 no Windows e pode se tornar U+30FB no Linux e no macOS, dependendo da versão do iconv.

Nos drivers ODBC 13 e 13.1, a divisão de caracteres multibyte UTF-8 ou substitutos UTF-16 entre buffers SQLPutData resulta em corrupção de dados. Use buffers de transmissão que não terminem em codificações parciais de caracteres. Essa limitação foi removida no Driver 17 do ODBC.

Para orientações de codificação de caracteres, conversão, vinculação de parâmetros e tamanho de buffer, veja Problemas conhecidos.

Openssl

A partir do Driver ODBC 17.4, o driver carrega o OpenSSL dinamicamente, o que permite que ele rode em sistemas com versões 1.0 ou 1.1 sem arquivos separados do driver. A partir da versão 17.9, o driver dá suporte ao OpenSSL 3.0, além das versões anteriores. Quando múltiplas versões do OpenSSL estão presentes, o driver tenta carregar uma versão suportada a partir de seus caminhos de pesquisa de biblioteca.

Versão do driver Suporte às versões do OpenSSL
17,4 a 17,8 1.0, 1.1
versões 17.9 e posteriores da série 17.x, e todas as versões do Driver 18 1.0, 1.1, 3.0

OpenSSL 4 não é suportado. No macOS, um link Homebrew openssl que aponta para o OpenSSL 4 pode impedir que o driver carregue o OpenSSL mesmo com o OpenSSL 3 instalado. Verifique o caminho da biblioteca, assim como as versões instaladas.

Observação

Um conflito potencial pode ocorrer se a aplicação que usa o driver, ou um de seus componentes, se vincular a ou carregar dinamicamente uma versão diferente do OpenSSL. Se várias versões do OpenSSL estiverem presentes no sistema e o aplicativo o usar, certifique-se de que a versão carregada pelo aplicativo e a do driver correspondam entre si. Os erros podem corromper a memória e podem não se manifestar de maneiras óbvias ou consistentes.

Linux alpino

Em musl, o tamanho padrão da pilha para novas threads é 128 KB, a menos que o executável solicite um valor padrão maior. Uma thread pode exceder esse limite quando chama o driver. Vincule um aplicativo ODBC no Alpine Linux com -Wl,-z,stack-size=<size_in_bytes> para solicitar uma pilha padrão de thread maior. Aplicações que criam threads com um tamanho de pilha explícito também devem escolher um tamanho adequado para essas threads.

A pilha da thread principal e a pilha padrão para novas threads não têm a mesma configuração. Em glibc sistemas, o padrão para novas threads normalmente segue o limite de recursos da pilha do processo, com uma alternativa específica da arquitetura quando esse limite é ilimitado. Não presuma um padrão fixo de 2 MB em sistemas Linux.

Observações adicionais

Para criar uma conexão dedicada de administrador (DAC) a partir de uma aplicação ODBC, defina Server=tcp:<server>,<dac_port> na sua cadeia de conexão. Use a porta descoberta do DAC, não a porta de conexão normal da instância. Por exemplo, se a porta DAC for 33000, defina Server=tcp:<server>,33000. Esses fragmentos de string de conexão especificam apenas o endpoint, não a autenticação. Configure a autenticação e a validação do certificado do servidor separadamente.

O login deve ser membro da função de servidor sysadmin. O acesso remoto exige que a opção de conexões de administrador remoto do servidor esteja ativada. Para requisitos de acesso, configuração do servidor e procedimentos de administração na linha de comando, veja Conexão de diagnóstico para administradores de banco de dados. Para descoberta de portas, veja porta DAC.

O gerenciador de drivers unixODBC lida com atributos de instruções passados por SQLSetConnectAttr da mesma forma que o Gerenciador de Drivers do Windows. As opções de instruções ODBC 2.x, como SQL_ATTR_QUERY_TIMEOUT e SQL_ATTR_MAX_ROWS, aplicam-se a instruções existentes e novas na conexão. Atributos apenas de instrução ODBC 3.x, como SQL_ATTR_ROW_ARRAY_SIZE e SQL_ATTR_PARAMSET_SIZE, retornam SQLSTATE HY092. Atributos definidos tanto no nível de conexão quanto na instrução, como SQL_ATTR_METADATA_ID, podem ser definidos em qualquer nível. Definir atributos apenas de instrução no nível de conexão está obsoleto no ODBC 3.x, então chame SQLSetStmtAttr em seu lugar. Para mais informações, veja a função SQLSetConnectAttr.

Em aplicações altamente multithread, a validação de identificadores unixODBC pode se tornar um gargalo de desempenho. Compilar unixODBC com --enable-fastvalidate pode melhorar o desempenho. No entanto, essa opção pode fazer com que aplicações que passam handles inválidos para APIs ODBC travem em vez de retornar SQL_INVALID_HANDLE.

Para etapas de instalação e configuração da plataforma, veja:

Conteúdo relacionado

  • Última atualização em