openGauss 客户端工具：gs_loader（3）

参数说明

表 2 gs_loader参数说明

参数	参数说明	参数类型 : 取值范围
help	查看帮助信息。	-
user	数据库链接用户（与-U等价）。	字符串
-U	数据库链接用户（与user等价）。	字符串
passwd	用户密码（与-W等价）。	字符串
-W	用户密码（与passwd等价）。	字符串
db	数据库名称（必选，与-d等价）。	字符串
-d	数据库名称（必选与db等价）。	字符串
host	指定正在运行服务器的主机名、Unix域套接字的路径、或者域名。接受以“,”分隔的字符串来指定多个主机地址，支持指定多个主机地址（与-h等价）。 当指定多个主机地址时，默认选择连接到主节点。	参考gsql --host参数
-h	指定正在运行服务器的主机名、Unix域套接字的路径、或者域名。接受以“,”分隔的字符串来指定多个主机地址，支持指定多个主机地址（与host等价）。 当指定多个主机地址时，默认选择连接到主节点。	参考gsql --host参数
port	指定数据库服务器的端口号。可以配置一个或多个，当配置一个时，所有的IP都使用同一个端口连接；当配置多个时，顺序与IP顺序相同，个数必须与IP数相等，当不相等时会报错（与-p等价）。	参考gsql --port参考
-p	指定数据库服务器的端口号。可以配置一个或多个，当配置一个时，所有的IP都使用同一个端口连接；当配置多个时，顺序与IP顺序相同，个数必须与IP数相等，当不相等时会报错（与port等价）。	参考gsql --port参考
create	是否创建pgxc_copy_error_log和gs_copy_summary表。	[true, false]，默认true
clean	是否清除本次错误记录。	[true, false]，默认false
data	数据文件，可以指定多个，或者通配符多字符通配(*)以及单字符通配(?)（必选）。	字符串
control	控制文件名称（必选）。	字符串
log	日志文件名称。	字符串
bad	出错行以及详细情况记录文件名称，也可以指定目录，不指定时根据数据文件名生成。	字符串
discard	WHEN匹配失败行记录文件名称，也可以指定目录，根据数据文件名生成。	字符串
errors	允许数据文件中出现多少出错行。	整数，默认0
skip	允许跳过数据文件的前多少行。	整数，默认0
limit	指定最多导入的行数。	整数，默认无限大
bindsize	仅做语法兼容不实现功能。	-
rows	多行提交参数，指定导入多少行数据后进行一次提交。	整数，取值范围[1, 2147483647]
compatible_nul	是否开启数据中nul字符(0x00)兼容，开启后当数据文件中存在nul字符时，会先将nul字符转换成为空格字符' '(0x20)，再进行判断，加工和导入。	[true, false]，默认true。
compatible_illegal_chars	是否开启非法字符容错功能，与COPY语法中的COMPATIBLE_ILLEGAL_CHARS容错规则和限制相同，详见《开发者指南》的“SQL 语法 > COPY”章节的COPY_OPTION中COMPATIBLE_ILLEGAL_CHARS参数说明。	[true, false]，默认false。
parallel	指定并行导入的并发度。当并发度大于1时，表示开启并行导入模式。当并发度等于1时，转化为串行导入。并发度最大值限定不超过客户端CPU核数的两倍。当客户端运行在容器中时，由于获取到的是主机的cpu数量，可能比容器实际能使用的多，并发度建议由用户自行控制在实际能使用的客户端cpu数量的两倍范围内。另外该能力通过多线程并发多个事务实现，实际并发度会受限于服务端的线程池模型，也同时会给服务端增加压力，请按实际情况合理设置并发度。	整数，取值范围[1, CPU核数两倍]，默认1
binary	数据文件是否为通过copy的binary模式导出的二进制文件。	[true, false]，默认false。

 注意：

• 参数均为小写，不支持大写，同时兼容gsql登录方式：-p端口号，-h主机，-d数据库，-U用户名，-W密码方式。
• 使用rows参数时，提交次数不要超过1000次，否则会对性能产生影响。提交次数约等于数据文件中数据行数除以rows参数取值。不指定rows参数时，rows无默认取值，表现为只进行一次提交，即所有数据都导入表中后进行一次事务提交。
• 小数据量频繁的提交会影响导入数据的性能，推荐合理配置rows参数的取值，保证每次提交的数据量大于5MB。对于常用的16U128G规格机器，一主两备部署场景下，向5个字段的表内导入13GB数据，排除网络影响，多次提交和单次提交（每次提交5MB数据）的速率基本持平，为10MB/s左右。
• compatible_nul参数实际控制guc参数loader_support_nul_character值的设置：
• compatible_nul=true对应session级set loader_support_nul_charchter='s2'。
• compatible_nul=false对应session级set loader_support_nul_character='s1'。 建议通过命令行设置此参数且通过compatible_nul设置优先级高于guc_param中设置。
• 当前gs_loader仅支持数据文件中存在nul字符时的兼容，不支持ctl控制文件中存在nul字符。ctl文件中存在nul字符会存在不可预期的问题。
• 指定binary参数为true后，有以下行要求：
• 数据文件必须为通过\COPY中BINARY模式导出的二进制格式数据文件，但是该模式导出的数据文件通常兼容性及可移植性较差，建议直接使用\COPY语句进行导入。
• gs_loader会将控制文件中语法转换为\COPY中BINARY模式下最简单的语法，即\COPY table_name FROM 'binary_file_path' BINARY; 语句。只解析控制文件中导入模式，表名信息和命令行中的control、data、binary、guc_param及数据库连接参数信息，不对其他参数语法进行解析和生效。
• 对于gs_loader的命令行及控制文件中有以下要求：
  • 不支持字符集配置。
  • 不支持WHEN条件过滤及DISCARD生成。
  • 不支持enable_copy_error_log = off下将错误数据直接写入bad文件。errors默认取值unlimited，会默认记录编码异常数据。
  • 不支持配置CSV模式，不支持指定分隔符及包裹符，不支持TRAILING NULLCOLS语法。
  • 不支持数据类型配置、POSITION配置及列表达式使用。
  • 不支持FILLER、CONSTANT、SEQUENCE、NULLIF参数。
  • 不支持skip、rows、compatible_nul、compatible_illegal_chars参数。
• 指定parallel大于1时：
• 当同时设置binary参数为true时，parallel参数失效，按串行导入。
• 不支持在控制文件中设置OPTIONALLY ENCLOSED BY或者FIELDS CSV。
• 不支持在控制文件中设置SEQUENCE列。
• 无法保证数据按数据文件中的顺序导入。如果表中存在自增列，导入后自增列值的顺序无法保证与数据文件中顺序一致。
• 同时使用errors参数时，errors参数的意义为每个子任务允许出现的最大错误行数。
• 同时使用skip参数时，skip参数的意义是在整个数据文件开头跳过的行数。
• 同时使用rows参数时，分批提交的批次各子任务独立计算。
• 在客户端CPU、内存和服务端CPU、内存、空闲线程以及网络带宽不存在瓶颈时，相比于串行导入，并发度为2/4/8时的性能提升不低于1.5/3/5倍。
• 并发度每增加1，大约增加客户端10MB内存，服务端大约35MB内存。
• 当设置GUC参数support_zero_character为on时，表示数据库支持0x00字符的写入和读取，gs_loader导入数据时，会将0x00按照原始样式导入，而不是受其他兼容性参数影响转换成0x20。