View a markdown version of this page

Diferenças entre as versões 2.x e 1.x do driver ODBC - Amazon Redshift
Principais diferenças a serem consideradasString de conexão e opções de DSNAlterações de tipo de dadosSolução de problemas pós-migraçãoAtualização de uma versão mais antiga do ODBC 2.xMais informações

O Amazon Redshift não permitirá mais a criação de UDFs do Python a partir do Patch 198. As UDFs do Python existentes continuarão a funcionar normalmente até 30 de junho de 2026. Para ter mais informações, consulte a publicação de blog .

Diferenças entre as versões 2.x e 1.x do driver ODBC

Esta seção descreve as diferenças entre o driver ODBC 1.x e o driver ODBC 2.x e fornece orientação sobre como migrar para o driver 2.x. Ela descreve as mudanças que podem afetar seu aplicativo e como resolvê-las.

Principais diferenças a serem consideradas

As ações a seguir resolvem os problemas de migração mais comuns. A maioria dos aplicativos precisa apenas de um subconjunto delas.

DSN e string de conexão

  • Revise seu DSN para ver as opções de driver que podem ter sido removidas ou renomeadas. Algumas opções de driver ODBC 1.x não são compatíveis com o driver ODBC 2.x. Outras foram renomeadas. Para mais detalhes, consulte String de conexão e opções de DSN.

  • Defina UseUnicode=true se seu aplicativo depender de códigos de tipo de caracteres largos (SQL_WVARCHAR, SQL_WCHAR). No driver ODBC 2.x, o padrão de UseUnicode é false, que relata tipos de caracteres estreitos.

  • Mova as configurações de registro para a seção [ODBC]. No Linux e no macOS, LogLevel e LogPath devem ser definidos na seção [ODBC] global de odbc.ini, não em uma seção DSN individual.

Consulta e esquema

  • Inclua EXTERNAL TABLE nos filtros de tipo SQLTables. No ODBC 2.x, tanto as tabelas do Amazon Redshift Spectrum quanto as tabelas de unidade de compartilhamento de dados são relatadas como EXTERNAL TABLE. Se você filtrar SQLTables por tipo, adicione EXTERNAL TABLE para continuar vendo esses objetos.

  • Converta INTERVAL em VARCHAR para aplicativos que não aceitam o tipo de dados de intervalo. Alguns clientes não oferecem suporte aos tipos de intervalo ODBC. Para esses clientes, coloque a coluna em sua consulta: SELECT col::VARCHAR FROM ...

Código da aplicação

  • Verifique as configurações de tempo limite da consulta. O ODBC 2.x aplica SQL_ATTR_QUERY_TIMEOUT corretamente de acordo com a especificação ODBC. O ODBC 1.x ignorava essa configuração. Consultas de longa execução que antes eram bem-sucedidas agora podem falhar com um erro de tempo limite. Revise e ajuste os valores de tempo limite conforme necessário.

  • Forneça o comprimento dos dados para os parâmetros de execução de dados. A versão 2.x relata SQL_NEED_LONG_DATA_LEN como Y (a versão 1.x relatava N). Os aplicativos que vinculam parâmetros SQL_DATA_AT_EXEC agora devem fornecer o tamanho total dos dados antes em StrLen_or_IndPtr.

String de conexão e opções de DSN

A tabela a seguir mostra as opções do driver ODBC 1.x que foram renomeadas ou têm equivalentes diretos no driver ODBC 2.x.

Opção 1.x Equivalente de 2.x Observações
MaxLongVarChar MaxLongVarcharSize Padrão alterado de 8190 para 65535.
ConnectionTimeout LoginTimeout Mesmo tempo limite de conexão, renomeado. O padrão é 0 (nenhum tempo limite).
VpcEndpointUrl vpc_endpoint_url
SSLCertPath TrustStore ou CaFile Caminho para um certificado CA usado para verificar o servidor. No Windows, defina isso no campo Armazenamento confiável da caixa de diálogo de configuração do DSN; a caixa de diálogo não tem o campo CaFile. Se ambos estiverem definidos, TrustStore terá prioridade.

As seguintes opções 1.x não são compatíveis com o driver 2.x atual. O driver 2.x as ignora, de modo que elas não afetam sua conexão. Removê-las do DSN é opcional, mas é recomendável para evitar confusão.

  • SingleRowMode: para limitar a memória do cliente, use StreamingCursorRows.

  • UseSystemTrustStore: incompatível. No Windows, o driver 1.x pode validar o certificado do servidor em relação ao armazenamento de certificados do sistema Windows. O driver 2.x é validado em relação a um arquivo de certificado CA: ele usa o certificado raiz do Amazon Redshift incluído por padrão ou o arquivo que você especifica em TrustStore ou CaFile.

  • BoolsAsChar: se o seu aplicativo dependia do retorno de colunas BOOLEAN como strings "0" e "1" (SQL_VARCHAR), converta a coluna em VARCHAR em sua consulta, por exemplo, SELECT col::VARCHAR FROM ....

  • TextAsLongVarchar, CheckCertRevocation, EnableAwsSdkLogs, UseLogPrefix, Locale, UseDeclareFetch, UseMultipleStatements, EnforceSingleStatement, EnableTableTypes: não há equivalente na versão atual. A equipe do Amazon Redshift está avaliando equivalentes ou alternativas para essas opções em versões futuras.

Para obter a lista completa das opções 2.x compatíveis, consulte Opções do driver ODBC.

Alterações de tipo de dados

A tabela a seguir mostra os mapeamentos de tipos de dados do Amazon Redshift que foram alterados no ODBC 2.x para estar em conformidade com a especificação ODBC. A maioria dos aplicativos não é afetada porque eles vinculam colunas por índice ou nome, em vez de por código de tipo.

Tipo de dados do Amazon Redshift ODBC 1.x ODBC 2.x
DOUBLE PRECISION SQL_FLOAT (6) SQL_DOUBLE (8)
INTERVAL YEAR TO MONTH SQL_VARCHAR (12), texto SQL_INTERVAL_YEAR_TO_MONTH (107), estrutura de intervalo
INTERVAL DAY TO SECOND SQL_VARCHAR (12), texto SQL_INTERVAL_DAY_TO_SECOND (110), estrutura de intervalo
VARCHAR / CHAR / TEXT Tipos largos (SQL_WVARCHAR, SQL_WCHAR, SQL_WLONGVARCHAR); padrão UseUnicode=true Tipos estreitos (SQL_VARCHAR, SQL_CHAR, SQL_LONGVARCHAR). Defina UseUnicode=true para restaurar tipos largos.
GEOMETRY / GEOGRAPHY (como SQL_C_BINARY) String ASCII com codificação hexadecimal Bytes binários brutos

Os valores COLUMN_SIZE retornados por SQLColumns também foram alterados para GEOMETRY, GEOGRAPHY e tipos de dados SUPER, que agora retornam NULL para indicar colunas não dimensionadas de acordo com a especificação ODBC. Os aplicativos que alocam buffers com base em COLUMN_SIZE devem manipular NULL usando um tamanho de buffer padrão.

Solução de problemas pós-migração

A tabela a seguir descreve os problemas comuns que você pode encontrar após a migração e como resolvê-los.

Sintomas Causa O que fazer
Tabelas externas não visíveis no navegador de esquemas As tabelas de espectro e unidade de compartilhamento de dados são relatadas como EXTERNAL TABLE Inclua EXTERNAL TABLE no filtro de tipo SQLTables.
erros pyodbc em colunas de intervalo pyodbc não suporta tipos de intervalo ODBC Transmita intervalos para VARCHAR em consultas.
Os dados dos caracteres são exibidos como caracteres inesperados (mojibake) Padrão de UseUnicode alterado para false. Os aplicativos que esperam dados de caracteres largos (UTF-16) podem interpretar erroneamente os bytes de caracteres estreitos como pares largos, produzindo uma saída distorcida. Os dados em si não são alterados. Defina UseUnicode=true no DSN ou atualize seu aplicativo para vincular colunas como SQL_C_CHAR em vez de SQL_C_WCHAR.
Consultas de longa execução retornam erros de tempo limite SQL_ATTR_QUERY_TIMEOUT agora está em vigor. O ODBC 1.x ignorava essa configuração. Aumente ou remova QueryTimeout do DSN ou defina SQL_ATTR_QUERY_TIMEOUT como 0 no seu aplicativo.
Definir SQL_ATTR_CURRENT_CATALOG retorna HY011 O atributo não pode ser definido em uma conexão aberta. Não há suporte para alternar bancos de dados em uma conexão aberta. Defina o atributo antes de se conectar ou feche e reabra a conexão no banco de dados de destino.
A conexão trava em ambientes de pilha dupla Limitação nas versões <= 2.1.16 Atualize para o 2.1.17 ou versão superior.
A análise de mensagens de erro retorna resultados inesperados Formato da mensagem alterado; códigos SQLSTATE inalterados Analise os códigos SQLSTATE em vez do texto da mensagem.
A vinculação de parâmetros de execução de dados em execução se comporta de maneira diferente SQL_NEED_LONG_DATA_LEN mudou de FALSE para TRUE; os aplicativos que usam SQL_DATA_AT_EXEC agora devem fornecer o tamanho total dos dados com antecedência Defina o valor do comprimento em StrLen_or_IndPtr ao vincular os parâmetros SQL_DATA_AT_EXEC.
Os logs do driver não são gerados LogLevel e LogPath devem estar na seção [ODBC] global de odbc.ini, não em seções DSN individuais Mova as configurações de registro do DSN para a seção [ODBC].

Atualização de uma versão mais antiga do ODBC 2.x

Se você já estiver executando uma versão mais antiga do ODBC 2.x, atualize para a versão mais recente. Para obter uma lista completa de aprimoramentos e correções de erros em todas as versões, consulte Log de alterações do driver ODBC do Amazon Redshift no GitHub.

Mais informações