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設置，瞭解容許同時運行多少個讀取器線程。

參考資料

https://pgloader.readthedocs.io/en/latest/pgloader.html