gs_loader

概述

• gs_loader工具用于进行数据导入。gs_loader将控制文件支持的语法转换为\COPY语法，然后利用已有的\COPY功能，做主要数据导入工作，同时gs_loader将\COPY结果记录到日志中。
• 使用gs_loader前请确保gs_loader版本与gsql版本、数据库版本保持一致。

安装部署

在存放数据源文件的服务器上，安装并配置gs_loader客户端工具，以便后续使用gs_loader工具进行数据的导入。

1. 创建存放gs_loader工具包的目录

   mkdir -p /opt/bin

2. 将gsql工具包上传至上一步所创建的目录中

   以上传EULER Linux版本的工具包为例，将软件安装包中的gsql工具包"GaussDB-Kernel_数据库版本号_操作系统版本号_64bit_gsql.tar.gz"上传至上一步所创建的目录中。

3. 在工具包所在目录下，解压工具包

   cd /opt/bin
   tar -zxvf GaussDB-Kernel_数据库版本号_操作系统版本号_64bit_gsql.tar.gz
   source gsql_env.sh

4. 验证工具位置及版本信息

   which gs_loader

5. 验证客户端版本信息
   gs_loader工具版本与gsql工具版本相对应，直接查询gsql客户端版本即可。

   gsql -V

6. 验证数据库版本信息，确保与客户端工具版本保持一致
   使用gsql工具连接到数据库后输入：

   select version();

日志等级配置

设置日志级别，可以供开发者查看。设置后会在控制台打印工具运行的相应信息。

使用权限

使用场景分为三权分立场景下及非三权分立场景下的使用。使用者可以选择将guc参数enableSeparationOfDuty设置为on/off控制三权分立功能的开闭。

• 不开启三权分立时，即enableSeparationOfDuty=off：

  使用者可以是数据库普通用户或管理员用户。当使用者为普通用户的时候，需要管理员用户对普通用户赋权。管理员账户可以直接使用。

  创建用户。

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

  创建相关的表并授权。

  GRANT ALL ON FUNCTION copy_error_log_create() TO load_user;
  GRANT ALL ON SCHEMA public TO load_user;
  SELECT copy_error_log_create();
  SELECT copy_summary_create();
  GRANT ALL PRIVILEGES ON  public.pgxc_copy_error_log To load_user;
  GRANT ALL PRIVILEGES ON  public.gs_copy_summary To load_user;

• 开启三权分立时，即enableSeparationOfDuty=on：

  使用者可以是数据库普通用户或管理员用户。使用前需要到各自的schema下创建pgxc_copy_error_log表以及gs_copy_summary这两张表并添加索引，不需要再进行授权。

  创建用户。

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

  创建相关的表并添加索引。

  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);
  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);

使用环境

由用户自己将工具路径添加到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.
            | 

使用指导

1. 创建用户、相关表并添加索引。
   • （不开启三权分立）仅对于普通用户。

     创建用户。

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

     创建相关的表并授权。

     

     gs_copy_summary和pgxc_copy_error_log表中不能含有RULE、TRIGGER、索引函数、行级访问控制、CHECK约束、GENERATED列、DEFAULT列、ON UPDATE列等可能导致提权的对象，否则将认为是恶意用户创建而报错退出。

     GRANT ALL ON FUNCTION copy_error_log_create() TO load_user;
     GRANT ALL ON SCHEMA public TO load_user;
     SELECT copy_error_log_create();
     SELECT copy_summary_create();
     GRANT ALL PRIVILEGES ON  public.pgxc_copy_error_log To load_user;
     GRANT ALL PRIVILEGES ON  public.gs_copy_summary To load_user;

   • （开启三权分立）对于普通用户和管理员用户。

     创建用户。

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

     创建相关的表并添加索引。

     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);
     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);

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

   创建表loader_tbl。

   1 2 3 4 5 6 7

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

   创建控制文件loader.ctl。

   1 2 3 4 5 6 7 8 9 10 11

   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 )

   创建数据文件data.csv。

   1 2 3 4 5 6 7 8 9 10 11 12 13 14

   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

3. 进行导入。

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

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

   执行结果：

   1 2 3 4 5 6

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

参数说明

• 参数均为小写，不支持大写，同时兼容gsql登录方式：-p端口号，-h主机，-d数据库，-U用户名，-W密码方式。
• gs_loader使用bad文件来记录出错数据，该数据来自错误表的rawrecord字段，由于错误表对于以某种编码无法读取的错误不记录rawrecord，因此bad文件中遇到此情况时记录空行。

控制文件

• 语法说明：

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

  LOAD [ DATA ] [CHARACTERSET char_set_name] [INFILE [directory_path] [filename ] ] [BADFILE [directory_path] [filename ] ] [{ INSERT | APPEND | REPLACE | TRUNCATE }] INTO TABLE table_name [{ INSERT | APPEND | REPLACE | TRUNCATE }] [FIELDS CSV] [TERMINATED [BY] { 'string' }] [OPTIONALLY ENCLOSED BY { 'string' }] [TRAILING NULLCOLS] [ WHEN { (start:end) | column_name } {= | !=} ‘string’ ] [( col_name [ [ POSITION ({ start:end }) ] ["sql_string"] ] | [ FILLER [column_type [external] ] ] | [ CONSTANT "string" ] | [ SEQUENCE ( { COUNT | MAX | integer } [, incr] ) ]|[NULLIF (COL=BLANKS)] [, ...] )]