将PostgreSQL迁移到TeleDB-分布式融合数据库HTAP-私有云产品-管理平台使用手册-数据传输服务操作指南-迁移指南-迁移配置

支持的源和目标数据库

支持的源和目标数据库如下表：

源数据库	目标数据库
PostgresSQL 12, 13, 14, 15	TeleDB

支持的迁移对象及SQL

迁移对象

结构迁移支持的对象：模式、表、索引、约束（外键、唯一、排他）、视图、物化视图、序列、存储过程、函数、规则、触发器、用户自定义类型、域。
支持的字段类型：数字类型、货币类型、字符类型、二进制数据类型、日期/时间类型、布尔类型、枚举类型、几何类型、网络地址类型、位串类型、文本搜索类型、UUID类型、JSON类型、复合类型、范围类型。

注意事项

每次至多同步一个库（database），同步多个库需要创建多个DTS任务。
模式：不支持pg_toast，pg_temp_1，pg_toast_temp_1，pg_catalog，information_schema等系统模式的迁移。
表：不支持临时表的迁移，表的索引、约束会一起迁移，表的触发器、规则在全量完成之后迁移。
序列：待迁移的表中有引用序列时，必须同时迁移相应的序列。
映射规则：
- 不包含增量时，可以对库、表、列名进行映射，若对表的列进行映射，则表中涉及到该列的约束将不会迁移。
- 包含增量时，不支持列名映射。
- 视图、存储过程、函数、域、自定义类型等对象依赖的表不支持做表名映射，否则视图、存储过程、函数将会失效。

增量数据迁移支持的SQL操作

DML INSERT、UPDATE、DELETE。
DDL 增量迁移的DDL操作仅支持CREATE TABLE、ALTER TABLE、DROP TABLE、CREATE SEQUENCE、ALTER SEQUENCE、DROP SEQUENCE、CREATE VIEW、ALTER VIEW、DROP VIEW、CREATE INDEX、ALTER INDEX、DROP INDEX。

注意
暂不支持 CREATE TABLE 表名 AS SELECT 语句。
RENAME表名之后，向更改名称后的表插入新的数据时，DTS不会同步新的数据到目标库，因可能会导致任务中断异常或数据不一致。
暂不支持以注释开头的DDL语句的同步。

数据库账号及权限

数据库	所需权限	参考赋权语句
源库	数据库的CONNECT权限，模式的USAGE权限，表的SELECT权限，序列的SELECT权限存在增量 REPLICATION连接权限对模式public的USAGE和CREATE权限用于增量抓取ddl ，这里也可以用户提前创建好	CREATE USER和GRANT语法。 -- 创建同步用户 (dts)CREATE USER dts WITH PASSWORD 'xxx'; -- 授权同步用户 (dts) 需要同步的 SCHEMA (public) 权限 GRANT SELECT,REFERENCES,TRIGGER ON ALL TABLES IN SCHEMA public TO dts; grant SELECT on ALL SEQUENCES IN SCHEMA public to dts; grant usage on schema public to dts; -- 开启同步用户 (dts) 的 REPLICATIONALTER USER dts REPLICATION; grant pg_read_all_settings to dts;
目标库	存在结构具有模式所在库的CONNECT权限、模式所在库上的CREATE权限、对象所在模式的USAGE权限、对象所在模式上的CREATE权限不存在结构迁移库表的INSERT, UPDATE, DELETE, DDL 权限	-- 创建同步用户 (dts)CREATE USER dts WITH PASSWORD 'xxx'; grant usage on schema public to dts; grant ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO dts; grant CREATE on DATABASE public to dts; grant CREATE on schema public to dts

操作须知

DTS迁移过程一般包含四个阶段：预检查阶段、结构迁移阶段、全量阶段、增量阶段。为了确保数据迁移各个阶段的平顺，在创建迁移任务前，请务必阅读以下使用须知。

任务开始前

源库要求

源数据库的分区表触发器不可以设置为disable。
全量同步支持源库备机状态，但需要设置hot_standby_feedback为on；增量同步不支持源库备机状态。
同步对象依赖和关联的对象也须一起同步，否则可能导致任务失败。
若要做增量同步，源数据库的“pg_hba.conf” 文件中包含如下的配置：
- host replication all 0.0.0.0/0 md5
- 源数据库参数wal_level必须配置为logical；
- 源数据库需提前安装Decoderbufs插件；
- 源数据库中无主键表的replica identity属性必须为full；
- 源数据库的max_replication_slots参数值必须大于当前已使用的复制槽数量；
- 源数据库的max_wal_senders参数值必须等于或大于max_replication_slots参数值；
- 源数据库中表的主键列toast属性为main、external、extended时，其replica identity属性必须为full。
- 同步对象依赖和关联的对象也须一起同步，否则可能导致任务失败。

目标库要求

目标数据库的block_size参数值必须大于或等于源库中的对应参数值。
如果存在money类型的字段，需要目标数据库和源数据库的lc_monetary参数值一致。
若要做增量同步，且同步对象包含外键、触发器或事件触发器，则目标数据库的session_replication_role参数必须设置为replica，同步结束后，此参数需改为origin。
目标库不可以包含与待同步对象类型相同且名称相同的对象，包括模式、表、序列等，否则任务可能出差。系统库、系统模式、系统表等除外。
选择表级对象迁移时，增量迁移过程中不建议对表进行重命名操作。
对于全量+增量和增量任务，启动前请确保源库中未启动长事务，启动长事务会阻塞逻辑复制槽的创建，进而引发任务失败。
若选择同步DDL，须注意源库执行DDL时，确保在目标库上是兼容的。
目标数据库关联TeleDB实例必须有足够的磁盘空间，磁盘大小建议取以下两种中的最小值:
- 源库待迁移数据量大小的1.5倍。
- 源库待迁移数据量大小加200GB。

结构、全量过程中

请勿修改源库和目标库的端口号，请勿修改、删除源库和目标库连接用户的密码、权限，否则可能导致任务失败。
请勿在源库执行任何DDL，否则可能导致数据不一致或任务失败。
请勿在目标库做写入操作，否则可能导致数据不一致。

增量过程中

请勿修改源库和目标库的端口号，请勿修改、删除源库和目标库连接用户的密码、权限，否则可能导致任务失败。
请勿修改源数据库表的主键或者唯一键（主键不存在时），否则可能导致增量数据不一致或任务失败。
请勿修改源数据库中表的replica identity属性，否则可能导致增量数据不一致或任务失败。
请勿在目标库做写入操作，否则可能导致数据不一致。
库级同步时，源库新增无主键表时，请务必同时将该无主键表的replica identity属性设置为full，然后再写入数据，否则可能导致数据不一致或任务失败。
库级同步时，源库新增主键表时，如果主键列toast属性为main、external、extended时，请务必同时将该表的replica identity属性设置为full，然后再写入数据，否则可能导致数据不一致或任务失败。
若选择同步DDL，须注意源库执行DDL时，确保在目标库上是兼容的。

数据稽核

建议在源库的业务低峰期进行数据比对，防止误报不一致数据，以及减少对源库和DTS任务的冲击。
在增量同步过程中做对比时，源库若存在写入，则对比结果可能不一致。

数据类型映射说明

PostgreSQL类型	Decoderbuf字段
BOOLOID	datum_boolean
INT2OID	datum_int32
INT4OID	datum_int32
INT8OID	datum_int64
OIDOID	datum_int64
FLOAT4OID	datum_float
FLOAT8OID	datum_double
NUMERICOID	datum_double
CHAROID	datum_string
VARCHAROID	datum_string
BPCHAROID	datum_string
TEXTOID	datum_string
JSONOID	datum_string
XMLOID	datum_string
UUIDOID	datum_string
TIMESTAMPOID	datum_string
TIMESTAMPTZOID	datum_string
BYTEAOID	datum_bytes
POINTOID	datum_point
PostGIS geometry	datum_point
PostGIS geography	datum_point

准备工作

登录自建PostgreSQL所属的服务器。
如果需要进行增量迁移，需要将配置文件中的wal_level设置为logical。

图片127.png

将DTS的IP地址加入至自建PostgreSQL的配置文件pg_hba.conf中。如下图：

如果您已将信任地址配置为0.0.0.0/0，可跳过本步骤。

图片128.png

如果任务包含增量迁移，需安装PostgreSQL的逻辑解码器输出插件Decoderbufs，建议安装v2.1.1.Final以上版本，低版本可能会导致PostgreSQL数据库出现coredump，详细的步骤可参考如下内容或PostgreSQL官网文档。

(1) 请自行前往github仓库获取Decoderbufs插件。

(2) 进行插件的配置。

① 进行插件的编译。

export PATH=/usr/lib/postgresql/9.6/bin:$PATH
make
make install

② 在postgresql.conf中配置逻辑复制。

MODULES
shared_preload_libraries = 'decoderbufs' # 解码插件配置
REPLICATION
wal_level = logical             # minimal, archive, hot_standby, 
or logical (change requires restart)
max_wal_senders = 100             # max number of walsender 
processes (change requires restart)
wal_keep_segments = 4           # in logfile segments, 16MB each;
0 disables
#wal_sender_timeout = 60s      # in milliseconds; 0 disables
max_replication_slots = 100       # max number of replication 
slots (change requires restart)

③ 重启PostgreSQL。

④ 验证配置是否生效。

#创建逻辑复制，使用逻辑复制插件decoderbufs
select * from 
pg_create_logical_replication_slot('decoderbufs_demo', 'decoderbufs');
#对相关表进行数据操作
#使用decoderbufs调试模式
SELECT data FROM 
pg_logical_slot_peek_changes('decoderbufs_demo', NULL, NULL, 'debug-mode', '1');
#使用decoderbufs获取wal变更，更新wal位置
SELECT data FROM pg_logical_slot_get_changes('decoderbufs_demo', NULL, NULL, 'debug-mode', '1');
#查看逻辑复制的wal位置
SELECT * FROM pg_replication_slots WHERE slot_type = 'logical';
#删除逻辑复制
select pg_drop_replication_slot("decoderbufs_demo");

创建源库DTS用户

如果仅做测试用，可以直接使用PostgreSQL的超级用户作为迁移用户，一般用户名为postgres。

如果需要授予精准的操作权限，则按照以下操作进行授权：

CREATE USER和GRANT语法。
-- 创建同步用户 (dts)
CREATE USER dts WITH PASSWORD 'xxx';
-- 授权同步用户 (dts) 需要同步的 SCHEMA (public) 权限
GRANT SELECT,REFERENCES,TRIGGER ON ALL TABLES IN SCHEMA public TO dts;  
grant SELECT on ALL SEQUENCES IN SCHEMA public to dts;
grant usage on schema public to dts;
-- 开启同步用户 (dts) 的 REPLICATION
ALTER USER dts REPLICATION;
grant pg_read_all_settings to dts;

创建目标库DTS用户

如果仅做测试用，可以直接使用TeleDB的root用户作为迁移用户。

如果需要TeleDB的精准迁移权限，可按照如下配置操作：

CREATE USER dts WITH PASSWORD 'xxx';
grant usage on schema public to dts;
grant ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO dts;
grant CREATE on DATABASE public to dts;
grant CREATE on schema public to dts;
如果要做增量迁移且迁移的表包含外键，那么除了上述权限外，还要保证该用户具有在会话级别执行SET session_replication_role = 'replica'的权限。可登录TeleDB控制台，将该参数设置并重启。

如果需要做增量DDL，则需要手动在源库创建用于增量DDL的元数据结构

执行如下语句，创建存储DDL信息的表。勾选增量DDL时，迁移对象中必须包含这张表以及它的序列。

DROPTABLE IF EXISTS public.dts_ddl_info;
DROP SEQUENCE IF EXISTS public.dts_ddl_info_id_seq;
CREATETABLE public.dts_ddl_info(
id bigserial primary key,
ddl text,
username varchar(64) default current_user,
txid varchar(16) default txid_current()::varchar(16),
tag varchar(64),
database varchar(64) default current_database(),
schema varchar(64) default current_schema,
client_address varchar(64) default inet_client_addr(),
client_port integer default inet_client_port(),
event_time timestamp default current_timestamp
);

执行如下语句，创建函数。

CREATEOR REPLACE FUNCTION public.dts_capture_ddl()
RETURNS event_trigger
LANGUAGE plpgsql
SECURITY INVOKER
AS $BODY$
declare ddl text;
declare real_num int;
declare max_num int:=50000;
begin
if (tg_tag in('CREATE TABLE','ALTER TABLE','DROP TABLE','CREATE 
SEQUENCE','ALTER SEQUENCE','DROP SEQUENCE','CREATE VIEW','ALTER VIEW','DROP VIEW','CREATE INDEX','ALTER INDEX','DROP INDEX')) then
select current_query()into ddl;
insertinto public.dts_ddl_info(ddl, username, txid, tag, database, schema, client_address, client_port, event_time)
values(ddl, current_user, cast(txid_current()asvarchar(16)), tg_tag, 
current_database(), current_schema, inet_client_addr(), 
inet_client_port(), current_timestamp);
selectcount(id)into real_num from public.dts_ddl_info;
if real_num > max_num then
if current_setting('server_version_num')::int<100000 then
deletefrom public.dts_ddl_info where id<(select min(id)+1000from 
public.dts_ddl_info)andnot exists (select0from pg_locks l join 
pg_database d on l.database=d.oid where d.datname=current_catalog and pid<>pg_backend_pid()and
 locktype='relation'and relation=to_regclass('public.dts_ddl_info_pkey')::oid 
and mode='RowExclusiveLock');
else
deletefrom public.dts_ddl_info where id<(select min(id)+1000from 
public.dts_ddl_info)and(xmax=0or 
coalesce(txid_status(xmax::text::bigint),'')<>'in progress');
end if;
end if;
end if;
end;
$BODY$;

将刚创建的函数的所有者修改为DTS连接源库的账号，以postgresql为例。

ALTER FUNCTION public.dts_capture_ddl() OWNER TO postgres;

执行下述命令，创建全局事件触发器。

CREATE EVENT TRIGGER dts_ddl_event ON ddl_command_end EXECUTE PROCEDURE public.dts_capture_ddl();

执行以下语句，将创建的事件触发器设置为enable。

ALTER EVENT TRIGGER dts_ddl_event ENABLE ALWAYS;

确认待迁移对象中是否包含触发器

如果将触发器作为结构的一部分，在DTS的调度逻辑上，触发器会先于全量迁移被迁移到TeleDB。这样可能会影响到全量迁移，导致数据不一致。

建议将触发器放到全量迁移之后，再新建一个迁移任务进行迁移。

数据及业务信息统计

如果为非测试任务，需要在迁移之前统计业务以及迁移信息，方便进行迁移任务规划。

资源信息	源库规格信息	例：4C8G + 500G + SSD
目标库磁盘信息	例：4C8G + 500G + SSD
网络情况	例：为测试环境纯内网传输，无复杂的网络拓补结构
数据信息	总数据量	例：30GB
总库表数量	例：40个库，8000张表，2000个视图，5个触发器
每日新增数据量级	例：一天的WAL日志新增大概100GB
是否所有表都有主键	建议迁移前完善主键，提高性能，方便运维。如果存在无主键的表，则增量阶段源端对应表的增、删、改操作不会同步至目标端，可能导致数据不一致，请谨慎评估。
业务类	规划迁移批次	例：规划分3次进行迁移，迁移时间每天晚上20:00-06:00，日期为2023-09-18至2023-09-20。实际迁移操作请与数据库全量备份操作错开，以免交叉影响，否则可能会导致备份失败，同时影响迁移效率。
数据迁移是否可停业务	例：能/不能
增量迁移情况	例：开启增量迁移，持续时间5天
可停业务时间长度	例：服务停机时间预计48小时
业务中是否存在百万级别的大事务	例：存在，涉及对表CLOUD.LOGS进行大事务操作，存在一个存储过程用不带where条件的delete语句定期清理该表。

操作步骤

订购DTS数据迁移实例。
进入实例配置页面。
1. DTS实例创建成功后，进入【数据迁移】实例列表页面，上一步骤购买成功的实例在实例列表中显示状态为“待配置”，进入实例配置页面进行配置：
配置源库及目标库信息。
1. 进入实例配置第一个步骤的【配置源库及目标库信息】页面，填入源库与目标库的相关配置信息，包括数据库类型、IP地址端口、数据库账号、数据库密码等信息。
2. 完成上述信息的填写后，单击源数据库和目标数据库的“测试连接”按钮进行数据库连接测试，检查数据库能否正常连接。

配置迁移对象及高级配置。

源库和目标库连通性测试成功后，点下一步按钮，进入实例配置第二个步骤的【配置迁移对象及高级配置】页面，在“源库对象”中选择要迁移的源库对象，包含：库、TABLE、VIEW、FUNCTION等，选中后单击“>”按钮，将待迁移对象移动到“已选择对象”中。
迁移对象配置说明：

配置	说明
任务步骤	如果只需要进行全量迁移，请同时勾选库表结构迁移和全量迁移。如果需要进行不停机迁移，请同时勾选库表结构迁移、全量迁移和增量迁移。注意：如果未选择增量迁移，为保障数据一致性，数据迁移期间请勿在源实例中执行DML和DDL操作。
迁移对象	源库为PostgreSQL的情况下，支持表、视图、函数、存储过程、物化视图、规则、触发器，域、自定义类型等对象的迁移。在迁移对象框中单击待迁移的对象，然后单击将其移动到已选择对象框；已选择对象可以通过单击将对象回退。选择迁移对象时，如不展开库的详细信息，则表示整库迁移，后续在增量任务过程中，可在源库创建新表，其他类型暂不支持。
映射名称更改	支持库表列三级名称映射，如需更改单个迁移对象在目标实例中的库名、表名和列名，选择对象，然后单击编辑按钮。如需批量更改迁移对象在目标实例中的库名、表名，请单击已选择对象方框右上方的“批量编辑”。若迁移任务仅包含结构迁移和全量迁移，支持列映射名称更改，若迁移任务包含增量迁移，不允许列映射名称更改。库表名仅支持字母、数字和下划线，长度不超过64个字符。注意：整库迁移时不建议做库表名映射。
过滤待迁移数据	支持设置where条件过滤数据，过滤条件不允许;和--字符，如需使用引号，请使用单引号(')，只有满足where条件的数据才会迁移到目标库。
增量迁移的DML	选择增量迁移DML操作，选中迁移对象，单击“编辑”，在弹跳框中选择所需增量迁移的DML操作。若在数据库级别和表级别都指定了DML操作，则表级别的设置会覆盖库级别的。
增量迁移的DDL	增量任务可选择是否迁移增量DDL。
是否定时开始任务	可选择任务开始的时间，默认单击开始任务后立即启动迁移任务。

注意
任务中存在整库迁移的情况下，则必须勾选增量DDL同步。
非整库迁移的情况下，若选择DDL同步，则只迁移待迁移对象的DDL语句。
非整库迁移的情况下，若未选择增量DDL同步，则增量阶段不会同步任何DDL语句。

图片131.png
图片132.png

预检查和启动迁移。

完成迁移对象和高级配置后，单击“下一步预检查”，进入实例配置第三个步骤的【预检查】页面。预检查会检查如下列表信息，并给出检查结果，用户可以依据检查结果进行下一步操作。

检查项	检查内容
lc_monetary参数配置一致性检查	检查源库与目标库的lc_monetary参数配置是否一致。
pg版本检查	检查源库和目标库的pg版本是不是符合要求。
同名对象存在性检查	检查目标库中是否存在和待迁移库同名的待迁移对象。
扩展插件兼容性检查	检查源库中安装的扩展插件，在目标库是否存在。
约束完整性检查	检查待迁移对象中子表依赖的父表是否被选中。
检查hot_standby_feedback参数配置	全量迁移源库pg为备节点时，hot_standby_feedback参数需配置为ON。
源库用户权限检查	检查源库用于DTS任务的用户是否具有相应的权限。
源库连通性检查	检查数据传输服务器能否连通源数据库。
源数据库的模式名表名是否合法	检查源数据库的模式名表名是否合法，名称不可以包含+"%'<>,.字符。
源库参数wal_level是否为logical	勾选增量迁移时，检查源库wal_level参数值是否为logical。
目标库用户权限检查	检查目标库用于DTS任务的用户是否具有相应的权限。
目标库连通性检查	检查数据传输服务器能否连通目标数据库。
源库参数max_replication_slots校验	勾选增量迁移时，检查源库max_replication_slots参数值是否大于当前已使用的复制槽数量。
源库参数max_wal_senders校验	勾选增量迁移时，检查源库max_wal_senders参数值是否大于当前已使用的复制槽数量。
逻辑解码插件安装校验	勾选增量迁移时，检查源库是否安装逻辑解码插件decoderbufs。
待迁移表是否存在主键检查	勾选增量迁移时，检查待迁移表中是否存在无主键的表。
无日志表存在性检查	勾选增量迁移时，检查当前选择的待同步对象中的表是否存在无日志表。
源库主备状态检查	勾选增量迁移时，检查源库是否为集群中的主库。
ddl同步元数据检查	勾选ddl同步时，检查源库是否有ddl同步所需的元数据对象。