pgloader 学习（五）pgloader 参考手册
pgloader将各种来源的数据加载到PostgreSQL中。它可以转换动态读取的数据，并在加载前后提交原始SQL。
它使用COPY PostgreSQL协议将数据流式传输到服务器，并通过填充一对reject.dat和reject.log文件来管理错误
pgloader 的操作，可以使用命令行参数，或者通过读取文件中定义的dsl
格式：
pgloader commands.load
或者使用参数：
pgloader SOURCE TARGET
参数说明
pgloader参数可以根据需要加载文件，也可以是特定输入文件的几个连接字符串。
源连接字符串
格式：
format:///absolute/path/to/file.ext
format://./relative/path/to/file.ext
format 可以是 csv, fixed, copy, dbf, db3 或者ixf
db://user:pass@host:port/dbname
db 可以是sqlite、mysql、mssql
当使用基于文件的源格式时，pgloader还支持从http位置本地获取文件并在需要时解压缩存档。
在这种情况下，必须使用-type选项指定文件的预期格式
另请注意，某些文件格式需要描述一些实现细节，例如要读取的列和分隔符以及从csv加载时的引用。
对于更复杂的加载方案，您需要使用本文档后面描述的语法编写完整的fledge加载命令。
目标连接字符串
对于目标字符串会在后边详细介绍
工具选项
查询选项
-h，-help 显示命令用法摘要并退出。
-V，-version 显示pgloader版本字符串并退出。
-E，-list-encodings 列出此版本的pgloader中的已知编码。
-U，-upgrade-config 使用pgloader版本2.x中使用的INI语法将命令行中的给定文件解析为pgloader.conf文件 ，并在标准输出上输出pgloader的新命令语法。
常规选项
这些选项用于在加载数据时调整pgloader行为
-v，-verbose 显示比较可用信息
-q，-quiet 退出
-d，-debug 显示调试级别信息消息。
-D，-root-dir 设置根工作目录（默认为“/ tmp / pgloader”）。
-L，-logfile 设置pgloader日志文件（默认为“/tmp/pgloader/pgloader.log”）。
–log-min-messages 日志消息进入日志文件所需的最低级别的详细程度。关键，日志，错误，警告，通知，信息或调试之一。
–client-min-messages 日志消息进入控制台所需的最低级别详细程度。关键，日志，错误，警告，通知，信息或调试之一。
-S，-summary 用于复制摘要输出的文件名。相对时，文件名扩展为* root-dir *。
文件名的格式默认为人类可读。通过指定扩展名为resp的文件名，可以使用机器友好格式（如CSV， COPY（PostgreSQL自带的COPY格式）或JSON）输出。的.csv，.copy或以.json。
-l <file>， - load-lisp-file <file>
在读取命令之前指定lisp <file>进行编译并加载到pgloader映像中，允许定义额外的转换函数。这些函数应该在pgloader.transforms包中定义。此选项可在命令行中出现多次。
-dry-run
允许测试.load文件而不实际尝试加载任何数据。调试它直到它没问题是有用的，特别是修复连接字符串。
-on-error-stop
改变pgloader行为：而不是试图聪明地处理错误处理并继续加载好的数据，分离掉坏的数据，只要PostgreSQL拒绝发送给它的任何东西就停止。用于调试数据处理，转换功能和特定类型转换。
-self-upgrade <directory>
指定一个<directory>在哪里找到pgloader源，这样它所做的第一件事就是动态加载（并编译成机器代码）另一个版本的自身，通常是一个像最新的git checkout这样的新版本。
–no-ssl-cert-verification
使用OpenSSL选项接受本地颁发的服务器端证书，避免以下错误消息：
SSL verify error: 20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY
解决SSL问题的正确方法是使用可信证书。有时虽然在修复信任证书链的同时使用pgloader设置取得进展是有用的，但也许是由另一个团队。这个选项很有用。
命令行操作选项
参数仅在，使用命令行运行数据加载操作时生效
–with "option"
允许从命令行设置选项。您可以根据需要多次使用该选项。option参数必须遵循SOURCE规范 的源类型的WITH子句
–set "guc_name='value'"
允许从命令行设置PostgreSQL配置。请注意，选项解析与从SET命令子句中使用时相同，特别是必须使用单引号将guc值括起来
–field "…"
允许设置源字段定义。字段按命令行中给出的顺序累积。可以 在源文件中的每个字段使用-field选项，或者用逗号分隔字段定义，就像在HAVING FIELDS子句中那样
–cast "…"
允许设置特定的强制转换规则以加载数据。
–type csv|fixed|db3|ixf|sqlite|mysql|mssql
如果SOURCE解析不满意，则允许强制源类型。
–encoding <encoding>
设置源文件的编码以从中加载数据。
–before <filename>
解析SQL查询的给定文件名，并在从源加载数据之前对目标数据库运行它们。查询由pgloader本身解析：它们需要以分号（;）结束，文件可能包含i或ir命令以包含另一个文件
–after <filename>
解析SQL查询的给定文件名，并在从源加载数据后对目标数据库运行它们。查询的解析方式与-before选项相同
批量以及重试操作
要将数据加载到PostgreSQL，pgloader使用COPY流协议。虽然这是加载数据的更快方式，但COPY有一个重要的缺点：
一旦PostgreSQL发送任何数据发送到它的错误，无论出现什么问题，PostgreSQL都会拒绝整个数据集
为了解决这个问题，pgloader将数据分成每批 25000行，这样当出现问题时，它只影响那么多行数据。当COPY流发生时，
每个批处理都保存在内存中，以便能够在某些情况发生时处理错误
当PostgreSQL拒绝整个批处理时，pgloader会记录错误消息，然后通过以较小批量重试批处理行来将坏行与已接受的行隔离。
为此，pgloader 从失败的COPY中解析CONTEXT错误消息，因为消息包含批处理中发现错误的行号，格式如下：
CONTEXT: COPY errors, line 3, column b: "2006-13-11"
使用该信息，pgloader将在错误之前重新加载批处理中的所有行，将错误的行记录为拒绝，然后尝试在单次尝试中加载剩余的批次，
这可能包含或可能不包含其他错误数据。
在包含被拒绝行的加载结束时，您将在root-dir位置找到两个文件，这两个文件位于与安装程序的目标数据库相同的目录下。文件名是目标表，
对于被拒绝的数据，它们的扩展名为.dat;对于包含有关被拒绝数据的完整PostgreSQL客户端日志的文件，它们的扩展名为.log。
可以使用以下WITH选项来控制pgloader批处理行为：
- on error stop, on error resume next
此选项控制pgloader是否正在使用构建批量数据。批处理实现允许pgloader通过发送PostgreSQL再次接受的数据并通过保留PostgreSQL拒绝
的数据来恢复错误。要启用重试数据并加载好的部件，请使用下一个错误恢复选项，这是基于文件的数据加载（例如CSV，IXF或DBF）的默认选项 。
从其他RDMBS技术迁移时，最好具有可重现的加载过程。在这种情况下，可以在错误停止时使用并修复转换规则，数据转换功能或输入数据，
直到迁移完成。这就是on error stop, on error resume next是SQLite，MySQL和MS SQL源类型的默认值。
关于性能的注意事项
它使用的基本架构是旧的Unix管道模型，其中一个线程负责加载数据（读取CSV文件，查询MySQL等）并将预处理的数据填充到队列中。
另一个线程从队列中提取，对输入数据应用更多转换，并使用COPY协议将最终结果传输到PostgreSQL。
关于并行处理
pgloader使用几个并发任务来处理正在加载的数据：
- 读取器任务读入数据并将其推送到队列中，
- 最后一个写入任务从队列中提取并将raw格式化为批处理的PostgreSQL COPY格式（这样就可以重新尝试失败的批处理，而无需再次从源读取数据），
然后使用COPY将数据发送到PostgreSQL协议。
我们允许worker同时在单个表的上下文中同时处于活动状态。单个工作单元由几种worker组成： - 一个
reader从源头获取原始数据， - N个
worker准备并将数据发送到PostgreSQL。
这里的N设置为并发参数：CONCURRENCY为2，我们启动（+ 1 2）= 3个并发任务，并发为4我们启动（+ 1 4）= 5个并发任务，其中只有worker可以同时活跃。
默认值为workers = 4，从数据库源加载时concurrency = 1，worker = 8，从其他东西（当前是文件）加载时concurrency = 2。这些默认值是任意的
由于pgloader启动的CREATE INDEX线程只等到PostgreSQL完成实际工作，因此这些线程不计入并发级别
默认情况下，在源架构中找到与每个表的最大索引数一样多的CREATE INDEX线程。可以将max parallel create index WITH选项设置为另一个数字，
以防其中有太多要创建的数字。
pgloader 命令语法
pgloader实现了一种特定于域的语言，允许设置复杂的数据加载脚本，处理计算列和输入数据的动态清理。对于更复杂的数据加载方案，
需要了解DSL的语法
语法规则：
LOAD <source-type>
FROM <source-url>
[ HAVING FIELDS <source-level-options> ]
INTO <postgresql-url>
[ TARGET TABLE [ "<schema>" ]."<table name>" ]
[ TARGET COLUMNS <columns-and-options> ]
[ WITH <load-options> ]
[ SET <postgresql-settings> ]
[ BEFORE LOAD [ DO <sql statements> | EXECUTE <sql file> ]
[ AFTER LOAD [ DO <sql statements> | EXECUTE <sql file> ]
;
主要子句是每个命令实现的LOAD，FROM，INTO和WITH子句。然后，某些命令会实现SET命令或某些特定子句，例如CAST子句
使用Mustache
pgloader 实现了Mustache 模版引擎，可以方便的进行动态配置
pgloader 具有一个特性就是可以获取os 系统的环境变量，参考如下：
export DBPATH=sqlite/sqlite.db
pgloader ./test/sqlite-env.load
模版使用环境变量
load database
from '{{DBPATH}}'
into postgresql:///pgloader;
通用子句
- from
该FROM子句指定在何处读取从数据 - into
PostgreSQL连接URI必须包含要将数据加载到的目标表的名称。该表必须已在PostgreSQL中创建，并且名称可能是模式限定的。
然后INTO选项还支持可选的逗号分隔的目标列列表，它们是输入字段的名称或目标列名称的空格分隔列表，其PostgreSQL数据
类型和 USING表达式
在使用表达可以是任何有效的Common Lisp形式，并且将与当前包设置要被读取pgloader.transforms，这样就可以使用在包中定义的功能，
例如与动态加载功能-load命令行参数。
每个USING表达式在运行时编译为本机代码。
此功能允许pgloader使用该投影的自定义代码将CSV文件中的任意数量的字段加载到数据库中可能不同数量的列中 - with
应用于命令的一组选项，使用以下任一的全局语法：
格式
key = value
use option
do not use option
所有数据源特定命令都支持以下选项：
on error stop, on error resume next
batch rows = R
batch size = … MB
prefetch rows = …
此外，还提供以下设置：
workers = W
concurrency = C
max parallel create index = I
- set
此子句允许指定要为pgloader打开的所有会话设置的会话参数。它需要一个参数名称列表，等号，然后单引号值作为逗号分隔列表。
pgloader不验证参数的名称和值，它们按原样给予PostgreSQL。 - BEFORE LOAD DO
在从CSV文件加载数据之前，您可以对数据库运行SQL查询。最常见的SQL查询是CREATE TABLE IF NOT EXISTS，以便可以加载数据。
每个命令必须以美元引用：它必须以双美元符号$$开头和结尾。然后用美元引用的查询以逗号分隔。在最后一次SQL查询后，不应该有
额外的标点符号。 - BEFORE LOAD EXECUTE
与BEFORE LOAD DO子句中的行为相同。允许您从SQL文件中读取SQL查询。实现对PostgreSQL美元引用的支持以及i和ir包括psql批
处理模式中的特性（它们是相同的东西） - AFTER LOAD DO
与BEFORE LOAD DO格式相同，在加载完成后，将执行该部分中找到的美元引用查询。此处是创建索引和约束或重新启用触发器的最佳时机。 - AFTER LOAD EXECUTE
与AFTER LOAD DO子句中的行为相同。允许您从SQL文件中读取SQL查询。实现对PostgreSQL美元引用的支持以及i和ir包括psql批处理模式
中的特性（它们是相同的东西） - AFTER CREATE SCHEMA DO
与BEFORE LOAD DO相同的格式，在该部分中找到的美元引用的查询在pgloader创建模式之后，以及在加载数据之前执行。此处是ALTER
TABLE的最佳时机，或者在pgloader的基础上做一些自定义实现，比如分区与BEFORE LOAD DO相同的格式，在该部分中找到的美元引用的
查询在pgloader创建模式之后，以及在加载数据之前执行。此处是ALTER TABLE的最佳时机，或者在pgloader的基础上做一些自定义实现，
比如分区 - AFTER CREATE SCHEMA EXECUTE
与AFTER CREATE SCHEMA DO子句中的行为相同。允许您从SQL文件中读取SQL查询。实现对PostgreSQL美元引用的支持以及i和ir包括
psql批处理模式中的特性（它们是相同的东西）。 - 连接字符串
参考格式：
postgresql://[user[:password]@][netloc][:port][/dbname][?option=value&...]
- 注释
可以包含以下格式的注释
以 – 定界符开始与当前行的结尾结束的评论,
定界符 /* and */ 分别开始和结束注释，可以在命令中间找到或跨越几行
- 批处理操作选项
支持以下配置
batch rows
将数值作为参数，用作批处理中允许的最大行数。默认值为25 000，可以更改为尝试具有更好的性能特征或控制pgloader内存使用情况;
batch size
将内存单元作为参数，例如20 MB，即其默认值。可接受的乘数是kB，MB，GB，TB和PB。这种情况很重要，以免混淆位与字节，我们这里只讨论字节。
prefetch rows
将数值作为参数，默认为100000。这是允许pgloader在每个读者线程的内存中读取的行数。请参阅workers设置，了解允许同时运行多少个读取器线程。
