openGauss 客户端工具：gs_loader（2）

使用环境

由用户自己将工具路径添加到PATH中。gs_loader支持SSL加密通信，使用方式同gsql方式，具体操作请参考《管理员指南》中“安全管理”章节。

新增系统表

新增gs_copy_summary表，记录COPY执行结果汇总，包括成功行数，出错行数，忽略行数，空行数。

新增函数：copy_summary_create用于创建gs_copy_summary表。

gs_copy_summary表格式如下：

relname     | public.sqlldr_tbl
begintime   | 2021-09-03 16:00:11.7129-04
endtime     | 2021-09-03 16:00:15.259908-04
id          | 21870
pid         | 47582725060352
readrows    | 100000
skiprows    | 0
loadrows    | 111
errorrows   | 0
whenrows    | 99889
allnullrows | 0
detail      | 111 Rows successfully loaded.
            | 0 Rows not loaded due to data errors.
            | 99889 Rows not loaded because all WHEN clauses were failed.
            | 0 Rows not loaded because all fields were null.
            | 

系统表gs_copy_summary字段说明

表 1 gs_copy_summary字段说明

字段名称	描述
relname	本次导入的目标表名
begintime	导入任务开始时间
endtime	导入任务结束时间
id	本次导入的事务id
pid	本次导入工作线程id
readrows	本次导入任务共计读取的数据行数
skiprows	本次导入任务共计跳过的数据行数
loadrows	本次导入任务成功导入的数据行数
errorrows	本次导入任务的错误数据行数
whenrows	本次导入任务违反when过滤条件的数据行数
allnullrows	全部字段都为空的数据行数
detail	本次导入任务的导入情况总结。主要包括成功导入行数、错误数据行数、违反when条件行数和字段全空行数等。

使用指导

1. （非三权分立）仅对于普通用户。

   1. （在管理员用户下）创建用户：

      CREATE USER load_user WITH PASSWORD '************';
      

   2. （在管理员用户下）将public schema权限赋给用户：

      GRANT ALL ON SCHEMA public TO load_user;
      

   3. （在管理员用户下）创建并给用户授权gs_copy_summary表：

      SELECT copy_summary_create() WHERE NOT EXISTS(SELECT * FROM pg_tables WHERE schemaname='public' AND tablename='gs_copy_summary');
      GRANT ALL PRIVILEGES ON  public.gs_copy_summary To load_user;
      

   4. （可选，在管理员用户下）创建并给用户授权错误表pgxc_copy_error_log：

      

       说明： 如果guc参数enable_copy_error_log未设置（默认为off），或者设置为off，则无需使用错误表，无需创建。否则需要创建该错误表。

      SELECT copy_error_log_create() WHERE NOT EXISTS(SELECT * FROM pg_tables WHERE schemaname='public' AND tablename='pgxc_copy_error_log');
      GRANT ALL PRIVILEGES ON  public.pgxc_copy_error_log To load_user;
      

   5. 切换用户。

      \c - load_user
      

2. （三权分立）对于普通用户和管理员用户。

   1. （在初始用户下）创建用户：

      CREATE USER load_user WITH PASSWORD '********';
      

   2. （在初始用户下）切换为load_user用户：

      \c - load_user
      

   3. 创建gs_copy_summary表并添加索引。

      CREATE TABLE load_user.gs_copy_summary(relname varchar, begintime timestamptz, endtime timestamptz, id bigint, pid bigint, readrows bigint, skiprows bigint, loadrows bigint, errorrows bigint, whenrows bigint, allnullrows bigint, detail text);
      CREATE INDEX gs_copy_summary_idx ON load_user.gs_copy_summary(id);
      

   4. （可选）创建pgxc_copy_error_log表并添加索引。

      

       说明： 如果guc参数enable_copy_error_log未设置（默认为off），或者设置为off，则无需使用错误表，无需创建。否则需要创建该错误表。

      CREATE TABLE load_user.pgxc_copy_error_log (relname varchar, begintime timestamptz, filename varchar, lineno int8, rawrecord text, detail text);
      CREATE INDEX copy_error_log_relname_idx ON load_user.pgxc_copy_error_log(relname);
      

3. 创建表和控制文件，准备数据文件。

   创建表loader_tbl。

   CREATE TABLE  loader_tbl
   (
       ID   NUMBER,
       NAME VARCHAR2(20),
       CON  VARCHAR2(20),
       DT   DATE
   );
   

   （在gs_loader客户端机器上）创建控制文件loader.ctl。

   LOAD DATA
   truncate into table loader_tbl
   WHEN (2:2) = ',' 
   fields terminated by ','
   trailing nullcols
   (
       id integer external,
       name char(32),
       con ":id || '-' || :name",
       dt date
   )
   

   （在gs_loader客户端机器上）创建guc参数文件guc.txt。

   set a_format_copy_version='s1';
   

   （在gs_loader客户端机器上）创建数据文件data.csv。

   1,OK,,2007-07-8
   2,OK,,2008-07-8
   3,OK,,2009-07-8
   4,OK,,2007-07-8
   43,DISCARD,,2007-07-8
   ,,,
   32,DISCARD,,2007-07-8
   a,ERROR int,,2007-07-8
   8,ERROR date,,2007-37-8
   ,,,,
    ,
   8,ERROR fields,,2007-37-8
   ,,,
   5,OK,,2021-07-30
   

4. 进行导入。

   （在gs_loader客户端机器上）执行导入前，先确认gs_loader工具有可执行权限。确保当前路径有文件写入权限（gs_loader在处理过程中会生成一些临时文件，导入完成后自动删除）。

   gs_loader control=loader.ctl data=data.csv db=testdb bad=loader.bad guc_param=guc.txt errors=5 port=8000 passwd=************ user=load_user
   

   执行结果：

   gs_loader: version 0.1
   
    5 Rows successfully loaded. 
   
   log file is: 
    loader.log
   

 说明： gs_copy_summary用于记录调用的copy语法及其详细情况，_[badfile]_bad.log_文件用于记录错误数据及其详细情况。为防止上一次导入时记录的错误数据以及详细情况被覆盖，建议每次执行导入时使用不同的bad参数。如果使用错误表pgxc_copy_error_log记录错误数据以及详细情况，请开启GUC参数enable_copy_error_log。如需删除表中的数据，可以对上述表执行truncate或者delete操作。