1.0到2.0迁移准备与常见问题_云原生数据库 PolarDB(PolarDB)-阿里云帮助中心

本文档详细说明了从1.0版本迁移至2.0版本的关键准备事项及常见问题解决方案。包括驱动程序、集群参数、Sequence序列值及存储过程OUT参数调用问题等问题，并提供了迁移最佳实践。以帮助您避免兼容性问题，确保迁移过程顺利进行。

驱动程序更换

重要

1.0版本与2.0版本使用完全不同的驱动程序体系。迁移时必须将应用程序中的1.0版本驱动完全替换为2.0版本专用驱动，以确保应用程序可正常运行。

2.0版本提供了全面的驱动程序支持，涵盖主流开发语言和平台：

JDBC驱动：适用于Java应用程序开发。
.NET驱动：支持.NET Framework和.NET Core应用。
其他语言驱动：支持多种编程语言的数据库访问需求。

数据库连接方式

1.0版本与2.0版本均采用标准的PostgreSQL协议进行数据库连接，实现了100%的PostgreSQL协议兼容性。您可以继续使用熟悉的数据库客户端工具进行连接和管理，无需额外处理。常用客户端工具包括：

DBeaver：功能强大的通用数据库管理工具。
Navicat Premium Lite：直观易用的数据库管理和开发工具。
其他PostgreSQL兼容客户端：支持PostgreSQL协议的各类客户端工具。

参数变更检查

在迁移完成后，必须对相关参数配置进行检查和确认，特别是对1.0版本中曾手动修改的参数设置。以下为关键参数变更对照表：

1.0参数名	1.0默认值	2.0参数名	2.0默认值	参数功能说明
`polar_comp_stmt_level_tx`	`off`	`polar_enable_stmt_transaction_rollback`	`on`	控制是否启用语句级别事务回滚功能。
`polar_empty_string_is_null_enable`	`on`	`polar_enable_empty_string_is_null`	`on`	控制是否将空字符串视为NULL值。

通过仔细检查和适当调整这些参数，可以确保迁移后的系统既能充分发挥2.0版本的新特性，又能保持与现有业务逻辑的兼容性。

常见问题及解决方案

Sequence序列值同步问题

问题描述：

迁移后目标库中的Sequence序列值可能落后于源库，导致序列生成的值出现重复或不连续的情况。

解决方案：通过手动同步的方式将源库的Sequence当前值复制到目标库：

获取源库Sequence：在源库执行以下SQL语句获取Sequence值。

DO LANGUAGE plpgsql $$
DECLARE
  nsp name;
  rel name;
  val int8;
BEGIN
  FOR nsp, rel IN 
    SELECT nspname, relname 
    FROM pg_class t2, pg_namespace t3 
    WHERE t2.relnamespace = t3.oid 
      AND t2.relkind = 'S' 
      AND t2.relowner != 10
  LOOP
    EXECUTE format($_$select last_value from %I.%I$_$, nsp, rel) into val;
    RAISE NOTICE '%',
    format($_$select setval('%I.%I'::regclass, %s);$_$, nsp, rel, val+1);
  END LOOP;
END;
$$;

执行同步操作：将上述结果复制到目标库执行。
验证同步结果：确认目标库中的Sequence值与源库保持一致。

存储过程OUT参数调用问题

问题描述：在2.0版本中，调用包含OUT参数的存储过程或函数时，必须在OUT参数位置传递一个值，否则会导致调用失败。

问题示例：

-- 存储过程定义
CREATE PROCEDURE p(a OUT INT) IS
BEGIN
  a := 1;
END;

-- PolarDB-O 1.0 中的调用方式（2.0中会失败）
CALL p();

-- PolarDB-O 2.0 和 Oracle 兼容的调用方式
CALL p(100); -- 参数值可以是任意整数，仅用于类型识别

解决方案：需要修改业务代码，这是内核层面的兼容性变更，无法通过配置解决，必须修改应用程序代码。在调用包含OUT参数的存储过程时，必须在OUT参数位置传递一个占位值（该值不会被实际使用，仅用于参数类型识别）。

对象查找和Search Path问题

问题描述：迁移后可能出现表、视图、存储过程等数据库对象找不到的情况，通常与search_path配置相关。

解决方案：

优先方案：设置数据库级别的search_path。
说明
若您使用JDBC连接数据库，则在JDBC连接串中需设置currentSchema=schema1来指定命名空间。
```
ALTER DATABASE database_name SET search_path = 'schema1,schema2,public';
```

保底方案：创建公共同义词当search_path调整无法解决问题时，可以通过创建公共同义词的方式解决对象访问问题：

-- 批量生成同义词创建语句的脚本
DO $$
DECLARE
    relation_name VARCHAR(100);
    relation_nsp VARCHAR(100);
BEGIN
    -- 查询指定用户创建的所有表和视图
    FOR relation_name, relation_nsp IN 
        SELECT relname, relnamespace::regnamespace 
        FROM pg_class 
        WHERE relkind IN ('r', 'v') 
        AND relowner = '<实际创建对象的用户名>'::regrole::oid 
    LOOP
        -- 生成创建公共同义词的SQL语句
        RAISE NOTICE 'CREATE PUBLIC SYNONYM % FOR %.%;', 
                     relation_name, relation_nsp, relation_name;
    END LOOP;
END $$;

说明

将上述脚本中的<实际创建对象的用户名>替换为实际的用户名。
执行脚本后，复制输出的CREATE PUBLIC SYNONYM语句，确认SQL语句无误后，手动执行这些语句创建同义词。

表和视图权限问题

问题描述：迁移后可能出现对表或视图的访问权限不足的问题。

解决方案：通过GRANT语句手动添加必要的权限：

-- 授予用户对表的查询权限
GRANT SELECT ON table_name TO user_name;

-- 授予用户对视图的查询权限
GRANT SELECT ON view_name TO user_name;

-- 授予用户对schema的使用权限
GRANT USAGE ON SCHEMA schema_name TO user_name;

大小写敏感问题

问题描述：如果您在1.0版本中使用了双引号加大小写交替的方式创建对象，在2.0版本中可能会出现对象找不到的问题。

重要

该问题较为罕见，若您不确定是否触发了该问题，请联系我们确认后再进行操作。

问题原因：应用代码依赖了1.0版本早期的一个BUG行为。

解决方案：在2.0版本中启用大小写忽略参数：

-- 启用大小写交替忽略功能
SET polar_enable_ignore_case_interleaving = on;

迁移最佳实践

为确保迁移过程顺利，建议遵循以下最佳实践：

充分测试：在生产环境迁移前，必须在测试环境完整验证所有功能。
逐步排查：按照上述问题清单逐一检查和解决。
备份重要数据：迁移前确保重要数据已完整备份。
兼容性测试：全面测试应用程序与新版本的兼容性。
性能优化：利用2.0版本的新特性，优化应用程序的数据库访问性能。
技术支持：遇到复杂问题时，请及时联系我们获取帮助。
文档记录：记录所有修改和调整，便于后续维护。

通过系统性地处理这些常见问题，可以确保版本迁移的顺利完成，并充分发挥2.0的新特性和性能优势。