操作场景

GaussDB 100逻辑复制代理解析包含逻辑日志信息的REDO日志和归档日志，将解析到的满足条件的数据发送给HDR工具，然后HDR再将数据回放到目标端数据库，实现将GaussDB 100的数据变化准实时复制到其它同构或异构数据源的能力。相对于物理复制对日志物理格式的强依赖，逻辑复制代理和HDR的使用更加灵活，可以实现GaussDB 100跨版本复制、GaussDB 100向其它异构数据库（如Oracle）复制，以及在源、目标数据库表结构不一致时的定制支持。逻辑复制代理可以应用在主备数据库间的增量数据备份、不同业务系统之间的数据同步、系统升级过程中在线数据迁移等场景。

前提条件

• 运行环境需安装JAVA JDK1.8以上版本。
• 已获取逻辑复制代理工具安装包GaussDB_100_1.0.1-LOGICREP-AGENT.tar.gz，该包位于GaussDB_100_1.0.1-TOOLS.tar.gz压缩包下。

注意事项

• 对于主备复制场景，需要为主机和备机分别安装、配置、启动逻辑复制代理。但是，同一时间，只有主机的逻辑复制代理处于工作模式。
• 不能复制SYS用户的表数据。
• 逻辑复制需要读取归档及在线日志，因此需要打开GaussDB 100的归档日志，并关闭GaussDB 100的归档日志自动清理功能，防止归档日志被误删除。
• 逻辑复制代理在单机模式下不具备告警功能，逻辑复制代理的run日志中出现的“cannot get $DM_AGENT_HOME env or DM_AGENT_HOME path is invalid.”异常信息不用关注，这个是因为没有DM导致的，不影响逻辑复制功能。
• 逻辑复制代理只会复制全局逻辑复制开关和表逻辑复制开关打开后更新的数据，逻辑复制代理开启之前的源表数据无法复制到目标数据库。
• 不支持全量基线+增量机制。
• 不支持分布式事务完整性。
• 不支持直接回放DDL。

操作流程

图1 配置并启动逻辑复制代理流程图

操作步骤-配置并启动逻辑复制代理

以下操作步骤中使用的数据库连接信息说明如下：

• omm是集群安装成功后生成的数据库管理员用户，gaussdb_123为其默认密码。为保证信息安全，请在成功安装集群并登录时，尽快修改数据库管理员omm的默认密码。
• 127.0.0.1表示本地登录DN，如果远程登录请输入要登录的DN所在主机的IP。
• 40000是DN端口号。

1. 在GaussDB 100所在服务器上，解压安装逻辑复制工具。
   1. 以数据库安装用户身份登录GaussDB 100所在服务器。
   2. 按规划创建存放逻辑复制代理工具的目录。

      mkdir -p /opt/software/tools

   3. 将逻辑复制代理工具安装包GaussDB_100_1.0.1-LOGICREP-AGENT上传至规划目录/opt/software/tools下。
   4. 进入逻辑复制代理工具的存放目录。

      cd /opt/software/tools

   5. 将逻辑复制代理工具安装包解压到已规划好的/opt/software/tools目录。

      安装包解压后生成文件夹GaussDB_100_1.0.1-LOGICREP-AGENT。

      tar -zxvf GaussDB_100_1..1-LOGICREP-AGENT.tar.gz -C /opt/software/tools

      [omm@plat tools]$ ll  
      total 7940 
      drwxr-xr-x. 3 omm dbgrp    4096 Apr  26 15:13 
      GaussDB_100_1..1-LOGICREP-AGENT
      -rw-r--r--. 1 omm dbgrp 8113682 Apr  29 16:24 
      GaussDB_100_1..1-LOGICREP-AGENT.tar.gz

   6. 进入GaussDB_100_1.0.1-LOGICREP-AGENT目录。

      cd GaussDB_100_1.0.1-LOGICREP-AGENT

      [omm@plat GaussDB_100_1..1-LOGICREP-AGENT]$ ll  
      total 4 
      drwx------. 5 omm dbgrp 4096 Apr 26 15:13 logicrep_agent

   7. （可选）进入logicrep目录，查看相关目录。

      cd logicrep_agent

      [omm@plat logicrep_agent]$ ll  
      total 12
      drwx------ 2 omm dbgrp 4096 Sep 11 09:41 bin
      drwx------ 4 omm dbgrp 4096 Sep 11 09:41 conf
      drwx------ 2 omm dbgrp 4096 Sep 11 09:41 lib

      相关目录说明如下：

      • conf：配置文件目录
      • repconf：复制关系定义文件目录
      • sec：秘钥配置文件目录
      • lib：依赖第三方库目录
      • bin : 逻辑复制代理工具启动和停止脚本存放目录

2. 在主机上，配置逻辑复制服务进程的启动参数。
   1. 进入conf目录。

      cd /opt/software/tools/GaussDB_100_1.0.1-LOGICREP-AGENT/logicrep_agent/conf

   2. 打开init.properties文件，并按i进入编辑模式。

      vi init.properties

   3. 修改进程启动参数的取值。

      所有改动需要重启逻辑复制服务生效。conf/init.properties文件模版如下，其中斜体表示用户可根据需要替换为实际值。

      #unit: number of slots
      #value range:[1024,20480]
      dispatch.queue.size=1024
      #unit: number of transactions
      #value range:[100,300]
      transaction.buffer.size=100
      #unit: MB
      #value range:[100,500]
      transaction.buffer.memory.size=100
      #unit: MB
      #value range:[300,800]
      logentry.buffer.size=500
      #byte order of redo logfiles to be extracted
      #    little - logfiles generated on little endian platform
      #    big - logfiles generated on big endian platform
      logfile.endian.type=little
      #path_to_keystore_file(for zenith)
      javax.net.ssl.keyStore=
      #encrypted keyStorePassword(for zenith)
      javax.net.ssl.keyStorePassword=
      #whether skips logs when one table's metadata can not be found.
      #    true - skip logs of the table, one probable scenario is:
      #           the table was dropped at the source db, logicrep restarted, and metadata lost.
      #    false - can not skip, logicrep throws an exception and exits.
      skip.table.without.metadata=false
      #unit: ms
      replay.batch.linger.ms=1000
      #should not be less than the number of rmid in kernel
      session.number=10240

      相关参数解释如下：

      • dispatch.queue.size

        工作队列大小。根据可并发事务大小评估，在性能要求不高的场景下，使用默认配置即可。

      • transaction.buffer.size

        事务缓存大存放事务个数。当缓存满时，将等待回放线程处理。初始时使用默认配置。后续可以通过观察性能日志的缓存高水位进行调整。

      • transaction.buffer.memory.size

        每个事务占用的大内存空间，当某个事务超过默认配置值的时候，会导致逻辑复制失败，这个时候可以调大该参数值，确保占用大内存的事务可以正确地进行逻辑复制。

      • logentry.buffer.size

        logentry缓存大小。初始时使用默认配置。后续可以通过观察性能日志的缓存高水位进行调整。

      • logfile.endian.type

        指定数据存储在内存中时采用大端模式还是小端模式，此处的大小端配置是指产生逻辑复制工具需要使用的日志文件的机器的大小端。采用大端模式存放数据时，数据的高字节保存在内存的低地址中，而数据的低字节保存在内存的高地址中；采用小端模式存放数据时，数据的高字节保存在内存的高地址中，而数据的低字节保存在内存的低地址中。

      • javax.net.ssl.keyStore

        指定keyStore文件路径，该路径中包括文件名。仅在配置“useSSL=true”时且需要认证客户端时使用该参数。

      • javax.net.ssl.keyStorePassword

        指定keyStore密码的密文。仅在配置“useSSL=true”时且需要认证客户端时使用该参数。该密文的生成方式请参见步骤4。

      • replay.batch.linger.ms

        批量回放延时时间

      • session.number

        数据库大session数

   4. 按Esc键并输入:wq保存退出。

3. 在源数据库上创建并配置逻辑复制代理工具使用的用户。
   1. 赋予数据库管理员读取相关系统表和视图的权限。
      1. 以数据库安装用户身份登录GaussDB 100所在服务器。
      2. 以sysdba身份本地登录DN数据库。

         zsql / as sysdba -D dn_data_dir

      3. 执行以下命令。

         GRANT SELECT ON SYS.SYS_TABLES TO omm with grant option;
         GRANT SELECT ON SYS.SYS_COLUMNS TO omm with grant option;
         GRANT SELECT ON SYS.SYS_USERS TO omm with grant option;
         GRANT SELECT ON SYS.SYS_CONSTRAINT_DEFS TO omm with grant option;
         GRANT SELECT ON SYS.SYS_LOGIC_REPL TO omm with grant option;
         GRANT SELECT ON SYS.DV_DATABASE TO omm with grant option;
         GRANT SELECT ON SYS.DV_LOG_FILES TO omm with grant option;
         GRANT SELECT ON SYS.DV_ARCHIVED_LOGS TO omm with grant option;

      4. 退出当前连接。

         EXIT

   2. 使用数据库系统管理员登录数据库。

      omm为安装后创建的系统管理员，其默认密码是gaussdb_123。

      假设使用的DN端口号是40000。

      zsql omm@127.0.0.1:40000
      Please enter password:
      ***********

   3. 通过执行以下SQL语句，创建逻辑复制代理工具所用的用户、并授予该用户CONNECT、CREATE TABLE角色，以及读取相关系统表和视图的权限。

      CREATE USER LREP IDENTIFIED BY database_234;
      GRANT CONNECT, CREATE TABLE TO LREP;
      GRANT SELECT ON SYS.SYS_TABLES TO LREP;
      GRANT SELECT ON SYS.SYS_COLUMNS TO LREP;
      GRANT SELECT ON SYS.SYS_USERS TO LREP;
      GRANT SELECT ON SYS.SYS_CONSTRAINT_DEFS TO LREP;
      GRANT SELECT ON SYS.SYS_LOGIC_REPL TO LREP;
      GRANT SELECT ON SYS.DV_DATABASE TO LREP;
      GRANT SELECT ON SYS.DV_LOG_FILES TO LREP;
      GRANT SELECT ON SYS.DV_ARCHIVED_LOGS TO LREP;
      CREATE TABLE LREP.LOGICREP_PROGRESS
      (
      	ID 		        VARCHAR(128),
      	COMMITTED_TX_SCN        BIGINT,
              COMMITTED_TX_TIME       TIMESTAMP,
      	LOGPOINT		VARCHAR(128),
      	UPDATE_TIME		TIMESTAMP
      );
      CREATE UNIQUE INDEX IX_LREP_PROGRESS ON LREP.LOGICREP_PROGRESS(ID);

4. 在GaussDB 100所在服务器上，为源数据库和目标数据库中逻辑复制代理工具使用的用户生成密码密文。

   该操作是在源数据库GaussDB 100上使用zencrypt工具完成的。

   1. 进入逻辑复制代理工具的密钥配置文件目录。

      cd /opt/software/tools/GaussDB_100_1.0.1-LOGICREP-AGENT/logicrep_agent/conf/sec 
      [omm@plat sec]$ ll 
      total 8 
      -rw-------. 1 omm dbgrp  38 Apr 26 15:13 key1.properties 
      -rw-------. 1 omm dbgrp 100 Apr 26 15:13 key2.properties

      key1.properties文件用于保存随机密钥因子，key2.properties文件用于保存工作密钥。

   2. 使用“vi key1.properties”命令查看保存在key1.properties文件中的随机密钥因子。
   3. 使用“vi key2.properties”命令查看保存在key2.properties文件中的工作密钥。
   4. 进入GaussDB 100安装目录下的bin目录。

      cd $GSDB_HOME/bin

   5. 用户可以使用key1.properties和key2.properties文件中的出厂默认的随机密钥因子和工作秘钥，也可以通过zencrypt生成新的随机密钥因子和工作秘钥，并分别配置到对应的文件中。

      ./zencrypt –g
      Key:            DmLILoFxlCRti8MtW2QlDw==
      WorkKey:        s0U9unwLKmU4KtieCzoqK0GRgu454GCCBElwd/WnpXJV1m0JxVgkLvarlgI8FcThXRwoYHAeQu+NHYDAXoRzWA==

   6. 使用zencrypt工具分别为源数据库和目标数据库中逻辑复制服务使用的用户生成密码密文。

      看到提示信息“Please enter password to encrypt:”时，输入源数据库中为逻辑复制创建的用户LREP的密码，则生成的是LREP用户密码的密文，在步骤5中将该密文配置在源数据库的参数ds.passwd中；输入目标数据库中为逻辑复制创建的用户logicuser的密码，则生成的是logicuser用户密码的密文，在步骤5中将该密文配置在目标数据库的参数ds.passwd中。

      ./zencrypt -e AES256 -f lCHMm1WvDKU97uVQDd8+ew== -k g/FMnXWyHkp+8TKMa8qm5j+Ojvuy5hHV/p3WloMhNl2DoUT6Dl90Tom5DKP+3J2M6s/jI0mMdUknmUYcOHQN+g==
      Please enter password to encrypt:  
      ********* 
      Please input password again:  
      ********* 
      Cipher:         jFB1xNaKybjU5kAD3gdJeJvdvEdjj0c87L1NBsSWZHA=

      • -e：指定加密算法。当前支持SCRAM_SHA256算法（用于加密用户密码）和AES256算法（用于加密SSL私钥密码）。
      • -f：指定随机密钥因子。仅在使用AES256算法或者生成工作密钥时有效。随机秘钥因子保存在key1.properties文件中，key1.properties文件的存储路径是/opt/software/tools/GaussDB_100_1.0.1-LOGICREP-AGENT/logicrep/conf/sec/key1.properties。
      • -k：指定工作密钥。仅在使用AES256算法时有效。工作秘钥保存在key2.properties文件中，key2.properties文件的存储路径是/opt/software/tools/GaussDB_100_1.0.1-LOGICREP-AGENT/logicrep_agent/conf/sec/key2.properties。

5. 在GaussDB 100所在服务器上，在conf/datasource.properties配置文件中定义逻辑复制服务相关的源数据库、目标数据库信息。
   1. 进入conf目录。

      cd /opt/software/tools/GaussDB_100_1.0.1-LOGICREP-AGENT/logicrep_agent/conf

      打开datasource.properties文件，并按i进入编辑模式。
      

   2. vi datasource.properties

   3. 定义源数据库、目标数据库信息。

      斜体表示需要替换为实际值。其中，用户密码密文的生成请参考步骤4，为逻辑复制服务创建用户在步骤3中完成。

      # properties of source/destination datasources defined here
      # note:
      #   1. section name - datasource name
      #   2. mandatory properties:
      #      ds.type - gauss/capture, needed for logicrep
      [srcdb]
      ds.type=gauss
      ds.url=jdbc:zenith:@127.0.0.1:1611?useSSL=false
      ds.username=lrep
      ds.passwd=
      ds.available.query.sql=select 1
      initial.size=5
      min.idle=1
      max.idle=10
      max.active=50
      max.wait=100000
      [dstCapture]
      ds.type=capture
      optimize.batch.send.buffer=3145728
      agent.monitor.address=10.134.254.240:1889

      以上示例包括逻辑复制代理当前支持的二种数据源类型的参数，均为必填字段。参数详细说明如下：

      • [srcdb]/[ dstCapture]：小节名称，即该小节描述的数据源名称，与repconf_db.xml文件中的srcName和dstName对应。其中，srcdb代表源数据源名称，dstCapture代表目标数据源名称。
      • ds.type：数据源类型。当前逻辑复制服务支持的类型包括：gauss、capture。gauss表示目标数据源为GaussDB 100；capture表示目标数据源为R7工具的capture
      • ds.url：数据库的url地址。
        • ds.type配置为gauss时，ds.url的格式为ds.url=jdbc:zenith:@127.0.0.1:1888?useSSL=false，其中使用“useSSL=false”时，逻辑复制速度较快，但是存在安全风险，“useSSL=true”时，使用SSL进行双向认证，都需要在JDBC客户端配置SSL证书，配置方法请参见《GaussDB 100 V300R001C00研发支持文档（单机）》中“数据库开发指南 > 基于JDBC开发 > 连接数据库”中的“配置JDBC客户端SSL证书”内容，如果使用单向认证（客户端不认证服务端），则无需在JDBC客户端配置SSL证书。
      • ds.type配置为capture时，配置ds.url之后还需配置的参数说明如下：
        • optimize.batch.send.buffer：逻辑复制批量发送消息给capture的缓存大小。
        • agent.monitor.address：逻辑复制agent服务监听的ip地址和端口号。
   4. 按Esc键并输入:wq保存退出。

6. 在GaussDB 100所在服务器上，在repconf_db.xml文件中定义复制关系。
   1. 进入repconf目录。

      cd /opt/software/tools/GaussDB_100_1.0.1-LOGICREP-AGENT/logicrep_agent/conf/repconf

      打开repconf_db.xml文件，并按i进入编辑模式。

   2. vi repconf_db.xml

   3. 定义复制关系。

      源数据库到目标数据库逻辑复制相关的所有信息均通过复制关系定义文件描述，并以xml格式存放在conf/repconf目录下。

      <?xml version="1.0" encoding="UTF-8" ?>
       <replicationConfig>        
       <repName>                 
      <repNameInfo name="logicrep"/>         
      </repName>          
      <datasource>                 
      <datasourceInfo srcName="srcdb" dstName=" dstCapture"/>         
      </datasource> 
      </replicationConfig>

      其中，相关标签解释如下：

      • repName

        复制关系的名称，作为复制关系的标识和复制进程启动时的命令行参数，以指定需要进行复制的内容。

        当conf/repconf目录下存在多个定义文件时，要求名称必须。

      • datasource

        指定复制的源数据库名称和目标数据库名称，该名称需在datasource.properties中存在定义。

   4. 按Esc键并输入:wq保存退出。

7. 在GaussDB 100所在服务器上，打开表逻辑复制开关和全局逻辑复制开关。
   1. 打开全局逻辑复制开关。

      zsql omm@127.0.0.1:40000 -c "ALTER DATABASE ENABLE_LOGIC_REPLICATION ON;"
      Please enter password:
      ***********

      omm为安装后创建的系统管理员，其默认密码是gaussdb_123。

   2. 打开表逻辑复制开关。

      zsql omm@127.0.0.1:40000 -c "ALTER TABLE [schema_name.]table_name ADD SUPPLEMENTAL LOG DATA (PRIMARY KEY) COLUMNS;"
      Please enter password:
      ***********

      omm为安装后创建的系统管理员，其默认密码是gaussdb_123。

   

   • 要复制的表必须有主键，否则，打开表的逻辑复制开关时会报错“GS-01213, error message = 'object index on table TRAINING does not exist'”。
   • 为保证源表和目的表中数据一致性，需要对源表主键字段在目的表中的对应字段设置主键属性。
   • 当前逻辑复制服务只支持基于主键复制，因此打开表逻辑复制开关时，COLUMNS只支持定义为PRIMARY KEY。
   • 只有当表逻辑复制开关和全局逻辑复制开关同时打开时，该表的数据才会被逻辑复制。

   用户可以使用数据库管理员账户登录源数据库查询全局逻辑复制开关的状态。操作步骤如下：

   1. 登录数据库。

      omm为安装后创建的系统管理员，其默认密码是gaussdb_123。

      假设使用的DN端口号是40000。

      zsql omm@127.0.0.1:40000
      Please enter password:
      ***********

   2. 查询全局逻辑复制开关的状态

      SELECT lrep_point, lrep_mode FROM sys.DV_DATABASE;
      --主机上全局逻辑复制开关状态查询结果如下：
      LREP_POINT           LREP_MODE
      -------------------- --------------------
      0-2-422-50b          ON
      1 rows fetched.

      用户可以使用数据库管理员账户登录源数据库，通过以下命令查询某张表的逻辑复制开关状态。omm为安装后创建的系统管理员，其默认密码是gaussdb_123。

      zsql omm/gaussdb_123@127.0.0.1:1888 -c "SELECT l.status FROM sys.sys_logic_repl l, sys.sys_tables t WHERE t.name='ORDERS' AND t.id=l.table#;" 
      SQL>  
      STATUS  
      ------------  
      1  
      1 rows fetched.

      

      使用zsql omm/gaussdb_123@127.0.0.1:1888 l.status FROM sys.sys_logic_repl l, sys.sys_tables t WHEREt.name='ORDERS' ANDt.id=l.table#;"查询某张表的逻辑复制开关时，表名必须使用大写，否则查询结果为空。

      STATUS 
      ------------  
      0 rows fetched.