需要解决的主要差异连接字符串和 DSN 选项数据类型更改迁移后故障排除从较旧的 ODBC 2.x 版本升级更多信息

ODBC 驱动程序 2.x 版本与 1.x 版本之间的差异

本节介绍 ODBC 1.x 驱动程序和 ODBC 2.x 驱动程序之间的差异，并提供有关如何迁移到 2.x 驱动程序的指导。它介绍了可能影响应用程序的更改以及如何解决这些更改。

需要解决的主要差异

以下操作可以解决最常见的迁移问题。大多数应用程序只需要其中的一部分操作。

DSN 和连接字符串

查看您的 DSN，了解可能已移除或重命名的驱动程序选项。ODBC 2.x 驱动程序不支持某些 ODBC 1.x 驱动程序选项。其它选项已重命名。有关详细信息，请参阅连接字符串和 DSN 选项。
如果您的应用程序依赖于宽字符类型代码（SQL_WVARCHAR、SQL_WCHAR），请设置 UseUnicode=true。在 ODBC 2.x 驱动程序中，UseUnicode 默认为 false，这会报告窄字符类型。
将日志记录设置移至 [ODBC] 部分。在 Linux 和 macOS 上，必须在 odbc.ini 的全局 [ODBC] 部分中设置 LogLevel 和 LogPath，而不是在单个 DSN 部分中进行设置。

查询和架构

将 EXTERNAL TABLE 包含在 SQLTables 类型筛选条件中。在 ODBC 2.x 中，Amazon Redshift Spectrum 表和数据共享表均报告为 EXTERNAL TABLE。如果您按类型筛选 SQLTables，请添加 EXTERNAL TABLE 以继续查看这些对象。
对于不支持间隔数据类型的应用程序，将 INTERVAL 强制转换为 VARCHAR。某些客户端不支持 ODBC 间隔类型。对于这些客户端，请在您的查询中强制转换以下列：SELECT col::VARCHAR FROM ...

应用程序代码

验证查询超时设置。ODBC 2.x 按照 ODBC 规范正确执行 SQL_ATTR_QUERY_TIMEOUT。ODBC 1.x 无提示忽略了此设置。以前成功的长时间运行的查询现在可能会因超时错误而失败。根据需要查看并调整超时值。
为执行时数据参数提供数据长度。2.x 将 SQL_NEED_LONG_DATA_LEN 报告为 Y（1.x 报告 N）。绑定 SQL_DATA_AT_EXEC 参数的应用程序现在必须在 StrLen_or_IndPtr 中预先提供总数据长度。

连接字符串和 DSN 选项

下表显示了 ODBC 1.x 驱动程序选项，这些选项在 ODBC 2.x 驱动程序中要么已重命名，要么具有直接等效项。

1.x 选项	2.x 等效项	备注
`MaxLongVarChar`	`MaxLongVarcharSize`	默认值从 8190 更改为 65535。
`ConnectionTimeout`	`LoginTimeout`	相同的连接超时，已重命名。默认为 0（无超时）。
`VpcEndpointUrl`	`vpc_endpoint_url`
`SSLCertPath`	`TrustStore` 或 `CaFile`	用于验证服务器的 CA 证书的路径。在 Windows 上，在 DSN 设置对话框的“信任存储”字段中对此进行设置；该对话框没有 `CaFile` 字段。如果两者均已设置，则 `TrustStore` 优先。

当前的 2.x 驱动程序不支持以下 1.x 选项。2.x 驱动程序会忽略它们，因此它们不会影响您的连接。将它们从 DSN 中移除是可选的，但为了避免混淆，建议您这样做。

SingleRowMode：要限制客户端内存，请改用 StreamingCursorRows。
UseSystemTrustStore：不支持。在 Windows 上，1.x 驱动程序可以根据 Windows 系统证书存储验证服务器证书。2.x 驱动程序根据 CA 证书文件进行验证：默认情况下，它使用捆绑的 Amazon Redshift 根证书，或者使用您在 TrustStore 或 CaFile 中指定的文件。
BoolsAsChar：例如，如果您的应用程序依赖于 BOOLEAN 列以 "0" 和 "1" 字符串 (SQL_VARCHAR) 的形式返回结果，则在查询中将该列强制转换为 VARCHAR，例如 SELECT col::VARCHAR FROM ...。
TextAsLongVarchar、CheckCertRevocation、EnableAwsSdkLogs、UseLogPrefix、Locale、UseDeclareFetch、UseMultipleStatements、EnforceSingleStatement、EnableTableTypes：当前版本中没有等效项。Amazon Redshift 团队正在评估未来版本中这些选项的等效项或替代项。

有关支持的 2.x 选项的完整列表，请参阅 ODBC 驱动程序选项。

数据类型更改

下表显示了 Amazon Redshift 数据类型映射，这些映射在 ODBC 2.x 中进行了更改以符合 ODBC 规范。大多数应用程序不受影响，因为它们按索引或名称而不是按类型代码绑定列。

Amazon Redshift 数据类型	ODBC 1.x	ODBC 2.x
`DOUBLE PRECISION`	`SQL_FLOAT` (6)	`SQL_DOUBLE` (8)
`INTERVAL YEAR TO MONTH`	`SQL_VARCHAR` (12)，文本	`SQL_INTERVAL_YEAR_TO_MONTH` (107)，间隔构造
`INTERVAL DAY TO SECOND`	`SQL_VARCHAR` (12)，文本	`SQL_INTERVAL_DAY_TO_SECOND` (110)，间隔构造
`VARCHAR` / `CHAR` / `TEXT`	宽类型（`SQL_WVARCHAR`、`SQL_WCHAR`、`SQL_WLONGVARCHAR`）；默认 `UseUnicode=true`	窄类型（`SQL_VARCHAR`、`SQL_CHAR`、`SQL_LONGVARCHAR`）。设置 `UseUnicode=true` 以还原宽类型。
`GEOMETRY`/`GEOGRAPHY`（用作 `SQL_C_BINARY`）	十六进制编码的 ASCII 字符串	原始二进制字节

对于 GEOMETRY、GEOGRAPHY 和 SUPER 数据类型，SQLColumns 返回的 COLUMN_SIZE 值也发生了变化，它们现在根据 ODBC 规范返回 NULL 以表示未指定大小的列。基于 COLUMN_SIZE 分配缓冲区的应用程序必须使用默认缓冲区大小处理 NULL。

迁移后故障排除

下表描述了迁移后可能遇到的常见问题及其解决方法。

症状	原因	操作
外部表在架构浏览器中不可见	Spectrum 表和数据共享表报告为 `EXTERNAL TABLE`	将 `EXTERNAL TABLE` 包含在 `SQLTables` 类型筛选条件中。
间隔列上出现 pyodbc 错误	pyodbc 不支持 ODBC 间隔类型	在查询中将间隔强制转换为 `VARCHAR`。
字符数据显示为意外字符（乱码）	`UseUnicode` 默认值更改为 `false`。需要宽字符（UTF-16）数据的应用程序可能会将窄字符字节误解释为宽对，从而产生乱码输出。数据本身没有变化。	在您的 DSN 中设置 `UseUnicode=true`，或者更新您的应用程序以将列绑定为 `SQL_C_CHAR`，而不是 `SQL_C_WCHAR`。
长时间运行的查询返回超时错误	现已强制执行 `SQL_ATTR_QUERY_TIMEOUT`。ODBC 1.x 无提示忽略了此设置。	在 DSN 中增加或移除 `QueryTimeout`，或者在应用程序中将 `SQL_ATTR_QUERY_TIMEOUT` 设置为 0。
设置 `SQL_ATTR_CURRENT_CATALOG` 会返回 `HY011`	无法在打开的连接上设置该属性。不支持在打开的连接上切换数据库。	在连接之前设置该属性，或者关闭并重新打开目标数据库上的连接。
连接在双栈环境中挂起	版本 <= 2.1.16 时的限制	升级至 2.1.17 或更高版本。
错误消息解析返回意外结果	消息格式已更改；SQLSTATE 代码未更改	解析 SQLSTATE 代码而不是消息文本。
执行时数据参数绑定的行为不同	`SQL_NEED_LONG_DATA_LEN` 已从 FALSE 更改为 TRUE；使用 `SQL_DATA_AT_EXEC` 的应用程序现在必须预先提供总数据长度	当绑定 `SQL_DATA_AT_EXEC` 参数时，在 `StrLen_or_IndPtr` 中设置长度值。
未生成驱动程序日志	`LogLevel` 和 `LogPath` 必须位于 `odbc.ini` 的 `[ODBC]` 全局部分，而不是在各个 DSN 部分中	将日志记录设置从您的 DSN 移至 `[ODBC]` 部分。

从较旧的 ODBC 2.x 版本升级

如果您已经在运行较旧的 ODBC 2.x 版本，请升级到最新版本。有关所有版本的增强功能和错误修复的完整列表，请参阅 GitHub 上的 Amazon Redshift ODBC 驱动程序更改日志。