Diretrizes de programação

Baixar driver ODBC

Os recursos de programação do Microsoft ODBC Driver for SQL Server em macOS e Linux são baseados em ODBC no SQL Server Native Client (SQL Server Native Client (ODBC)). SQL Server Native Client é baseado em ODBC no Windows Data Access Components (Referência do Programador de ODBC).

Um aplicativo ODBC pode usar MARS (conjuntos de resultados ativos múltiplos) e outros recursos específicos do SQL Server, incluindo /usr/local/include/msodbcsql.h, após a inclusão dos cabeçalhos unixODBC (sql.h, sqlext.h, sqltypes.h e sqlucode.h). Em seguida, use os mesmos nomes simbólicos para os itens específicos do SQL Server que você usaria em seus aplicativos ODBC do Windows.

Recursos disponíveis

As seguintes seções da documentação do SQL Server Native Client para ODBC (SQL Server Native Client (ODBC)) são válidas ao usar o driver ODBC em macOS e Linux:

• Comunicando-se com o SQL Server (ODBC)
• Suporte de tempo limite de conexão e consulta
• Cursores
• Aprimoramentos de data/hora (ODBC)
• Executando consultas (ODBC)
• Tratamento de erros e mensagens
• Autenticação Kerberos
• Tipos de dados CLR grandes definidos pelo usuário (ODBC)
• Executando transações (ODBC) (exceto transações distribuídas)
• Resultados do processamento (ODBC)
• Executando procedimentos armazenados
• Suporte a colunas esparsas (ODBC)
• Usando criptografia sem validação
• Parâmetros com valor de tabela
• UTF-8 e UTF-16 para a API de comando e dados
• Usando funções de catálogo

Recursos sem suporte

Os seguintes recursos não foram verificados para funcionar corretamente nessa versão do driver ODBC em Linux e macOS:

• Conexão com cluster de failover
• Resolução IP de Rede Transparente (antes do ODBC Driver 17)
• Rastreamento BID do Driver ODBC do Linux e do macOS (antes do Driver ODBC 17.3)

Os seguintes recursos não estão disponíveis nessa versão do driver ODBC em macOS e Linux:

• Transações Distribuídas (não há suporte para o atributo SQL_ATTR_ENLIST_IN_DTC)
• Espelhamento de banco de dados
• FILESTREAM
• Criação de perfil de desempenho do driver ODBC, discutido em SQLSetConnectAttr, e dos seguintes 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 de C, como SQL_C_INTERVAL_YEAR_TO_MONTH (documentado em Identificadores e descritores de tipo de dados)
• O valor SQL_CUR_USE_ODBC do atributo SQL_ATTR_ODBC_CURSORS da função SQLSetConnectAttr.

Suporte a conjuntos de caracteres

Para o ODBC Driver 13 e 13.1, os dados SQLCHAR devem ser UTF-8. Não há suporte para nenhuma outra codificação.

Para o ODBC Driver 17, há suporte para dados SQLCHAR em um dos seguintes conjuntos/codificações de caracteres:

Após a conexão, o driver detecta a localidade atual do processo em que ele é carregado. Se usar uma das codificações acima, o driver usará essa codificação para dados SQLCHAR (de caractere estreito); caso contrário, usará UTF-8 por padrão. Como todos os processos se iniciam na localidade "C" por padrão (e, portanto, fazem o driver usar UTF-8 como padrão), se um aplicativo precisar usar uma das codificações acima, ele deverá usar a função setlocale para definir a localidade adequadamente antes de conectar-se, seja especificando explicitamente a localidade, seja usando uma cadeia de caracteres vazia, por exemplo setlocale(LC_ALL, ""), para usar as configurações de localidade do ambiente.

Portanto, em um ambiente macOS ou Linux típico no qual a codificação é UTF-8, os usuários do ODBC Driver 17 que atualizarem da versão 13 ou 13.1 não notarão nenhuma diferença. No entanto, aplicativos que usam uma codificação não UTF-8 na lista acima por meio de setlocale() precisam usar essa codificação para dados de/para o driver, em vez de UTF-8.

Os dados SQLWCHAR devem ser UTF-16LE (Little Endian).

Ao associar parâmetros de entrada com SQLBindParameter, se for especificado um tipo SQL de caractere não Unicode, como SQL_VARCHAR, o driver converterá os dados fornecidos da codificação do cliente para a codificação padrão do SQL Server (normalmente, a página de código 1252). Para parâmetros de saída, o driver converte da codificação especificada nas informações de agrupamento associadas aos dados para a codificação do cliente. No entanto, é possível haver perda de dados: os caracteres na codificação de origem não representáveis na codificação de destino serão convertidos em um ponto de interrogação ('? ').

Para evitar essa perda de dados ao associar parâmetros de entrada, especifique um tipo de caractere SQL Unicode, como SQL_NVARCHAR. Nesse caso, o driver converte da codificação do cliente em UTF-16, que pode representar todos os caracteres Unicode. Além disso, a coluna ou o parâmetro de destino no servidor também deve ser um tipo Unicode (nchar, nvarchar, ntext) ou um com ordenação/codificação que possa representar todos os caracteres dos dados de origem. Para evitar a perda de dados com parâmetros de saída, especifique um tipo SQL de Unicode e um Unicode tipo C (SQL_C_WCHAR), fazendo o driver retornar dados como UTF-16, ou um tipo C estreito, e verifique se a codificação do cliente pode representar todos os caracteres dos dados de origem (essa representação sempre é possível com UTF-8.)

Para obter mais informações sobre regras de agrupamento e codificações, consulte Suporte a regras de agrupamento e Unicode.

Há algumas diferenças de conversão de codificação entre o Windows e várias versões da biblioteca iconv no Linux e no macOS. Dados de texto na página de código 1255 (hebraico) têm um ponto de código (0xCA) que se comporta de forma diferente após a conversão em Unicode. No Windows, esse caractere é convertido para o ponto de código UTF-16 0x05BA. Em macOS e Linux com versões de libiconv anteriores à 1.15, ele converte em 0x00CA. Em Linux com bibliotecas iconv que não dão suporte para a revisão de 2003 de Big5/CP950 (chamada BIG5-2003), os caracteres adicionados com essa revisão não serão convertidos corretamente. Na página de código 932 (japonês, Shift-JIS), o resultado da decodificação de caracteres não originalmente definidos no padrão de codificação de caracteres também difere. Por exemplo, o byte 0x80 é convertido em U+0080 no Windows, mas pode se tornar U+30FB no Linux e no macOS, dependendo da versão iconv.

Nos drivers ODBC 13 e 13.1, quando caracteres multibyte UTF-8 ou pares substitutos UTF-16 são divididos entre buffers do SQLPutData, isso resulta em corrupção de dados. Use buffers para transmitir SQLPutData que não terminem em codificações parciais de caracteres. Essa limitação foi removida com o ODBC Driver 17.

Openssl

Da versão 17.4 em diante, o driver carrega o OpenSSL dinamicamente, o que permite que ele seja executado em sistemas com as versões 1.0 ou 1.1 sem precisar de arquivos de driver separados. A partir da versão 17.9, o driver dá suporte ao OpenSSL 3.0, além das versões anteriores. Quando várias versões do OpenSSL estiverem presentes, o driver tentará carregar a mais recente.

Linux alpino

No momento em que este texto foi escrito, o tamanho padrão da pilha no MUSL é de 128 K, o que é suficiente para a funcionalidade básica do driver ODBC; no entanto, dependendo do que o aplicativo faz, não é difícil exceder esse limite, especialmente ao chamar o driver a partir de várias threads. É recomendável que um aplicativo ODBC no Alpine Linux seja compilado com -Wl,-z,stack-size=<VALUE IN BYTES> para aumentar o tamanho da pilha. Para referência, o tamanho da pilha padrão na maioria dos sistemas GLIBC é de 2 MB.

Observações adicionais

• Você pode fazer uma conexão de administrador dedicada (DAC) usando autenticação do SQL Server e host,porta. Um membro da função Sysadmin precisa primeiro detectar a porta DAC. Veja Conexão de diagnóstico para administradores de banco de dados para descobrir como. Por exemplo, se a porta DAC fosse 33000, você poderia se conectar a ela com sqlcmd, da seguinte maneira:

  sqlcmd -U <user> -P <pwd> -S <host>,33000
  

  Observação

  As conexões DAC devem usar a Autenticação do SQL Server.

• O gerenciador de drivers UnixODBC retorna "identificador de atributo/opção inválido" para todos os atributos da instrução quando são passados via SQLSetConnectAttr. No Windows, quando o SQLSetConnectAttr recebe um valor de atributo de instrução, ele faz o driver definir esse valor em todas as instruções ativas que sejam filhos do identificador de conexão.

• Ao usar o driver com aplicativos com uso intenso de múltiplas threads, a validação de identificadores do unixODBC pode se tornar um gargalo de desempenho. Nesses cenários, um desempenho significativamente mais alto pode ser obtido com a compilação de unixODBC com a opção --enable-fastvalidate. No entanto, tenha em mente que essa opção pode fazer com que aplicativos que passem identificadores inválidos para APIs ODBC travem em vez de retornar SQL_INVALID_HANDLE erros.

Conteúdo relacionado

• Perguntas frequentes
• Problemas conhecidos para o driver ODBC no Linux e no macOS
• Notas de lançamento para o driver Microsoft ODBC para SQL Server em Linux e macOS