从补丁 198 开始，Amazon Redshift 将不再支持创建新的 Python UDF。现有的 Python UDF 将继续正常运行至 2026 年 6 月 30 日。有关更多信息，请参阅[博客文章](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/)。

# ODBC 驱动程序 2.x 版本与 1.x 版本之间的差异
<a name="odbc20-odbc10-driver-differences"></a>

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

## 需要解决的主要差异
<a name="odbc20-migrate-key-differences"></a>

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

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

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

### 应用程序代码
<a name="odbc20-migrate-application-code"></a>
+ **验证查询超时设置。**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 选项
<a name="odbc20-migrate-connection-options"></a>

下表显示了 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 驱动程序选项](odbc20-configuration-options.md)。

## 数据类型更改
<a name="odbc20-migrate-data-types"></a>

下表显示了 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。

## 迁移后故障排除
<a name="odbc20-migrate-troubleshooting"></a>

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


| 症状 | 原因 | 操作 | 
| --- | --- | --- | 
| 外部表在架构浏览器中不可见 | 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 版本升级
<a name="odbc20-migrate-upgrade-2x"></a>

如果您已经在运行较旧的 ODBC 2.x 版本，请升级到最新版本。有关所有版本的增强功能和错误修复的完整列表，请参阅 GitHub 上的 [Amazon Redshift ODBC 驱动程序更改日志](https://github.com/aws/amazon-redshift-odbc-driver/blob/main/CHANGELOG.md)。

## 更多信息
<a name="odbc20-migrate-more-info"></a>
+ [为 Amazon Redshift 配置 ODBC 驱动程序版本 2.x 连接](odbc20-install.md)
+ [ODBC 驱动程序选项](odbc20-configuration-options.md)
+ [Amazon Redshift ODBC 驱动程序更改日志](https://github.com/aws/amazon-redshift-odbc-driver/blob/main/CHANGELOG.md)