pg-loader-cli

Một công cụ CLI bằng Node.js hiệu năng cao (tương tự như pgloader) giúp bạn dễ dàng import, load và migrate dữ liệu từ nhiều nguồn khác nhau (CSV/TSV, JSON/NDJSON, SQLite, MySQL) vào PostgreSQL mà không cần sử dụng Docker, Podman hay các sandbox tương tự.

Công cụ này sử dụng giao thức PostgreSQL COPY streams (thông qua pg-copy-streams) cho tốc độ load dữ liệu cực nhanh, thay thế cho các câu lệnh INSERT truyền thống chậm chạp.

✨ Tính năng chính

• Tốc độ cực nhanh (High Performance): Dữ liệu được stream trực tiếp từ nguồn và load vào PostgreSQL thông qua lệnh COPY FROM STDIN của PostgreSQL.
• Tự động suy luận kiểu dữ liệu (Auto-Schema / Type Inference): Nếu bảng đích chưa tồn tại trong Postgres, CLI sẽ tự động phân tích dữ liệu nguồn để tạo bảng với các kiểu dữ liệu thích hợp.
• Hỗ trợ đa nguồn (Multi-source):
  • CSV / TSV: Stream các tệp tin văn bản phân cách bằng dấu phẩy/tab, tự động suy luận kiểu dữ liệu.
  • JSON / NDJSON (JSON Lines): Hỗ trợ tệp JSON dạng mảng thông thường và NDJSON (Newline Delimited JSON) hiệu quả về bộ nhớ cho tệp lớn.
  • SQLite: Di chuyển toàn bộ database SQLite (.db, .sqlite) hoặc từng bảng cụ thể sang Postgres.
  • MySQL: Di chuyển toàn bộ database MySQL hoặc từng bảng cụ thể sang Postgres bằng cách streaming dữ liệu để tránh quá tải RAM.
• Không cần Sandbox: Chạy trực tiếp bằng Node.js trên Windows, macOS, Linux.
• Hỗ trợ Ghi đè/Làm sạch: Tùy chọn xóa tạo lại (--replace) hoặc xóa dữ liệu cũ (--truncate) trước khi ghi.

🚀 Cài đặt

Cài đặt global thông qua npm để sử dụng lệnh pg-loader ở bất kỳ đâu:

npm install -g pg-loader-cli

🛠 Hướng dẫn sử dụng

Cấu trúc lệnh cơ bản:

pg-loader <source> <target_postgres_uri> [options]

1. Import CSV hoặc TSV vào Postgres

# Tự động suy luận cột và import CSV vào bảng có tên trùng với tên file (ở đây là 'sales')
pg-loader ./sales.csv postgresql://postgres:password@localhost:5432/mydb

# Chỉ định tên bảng đích cụ thể và ghi đè nếu bảng đã tồn tại
pg-loader ./sales.csv postgresql://postgres:password@localhost:5432/mydb --table sales_data -r

# Sử dụng TSV (Tab Separated Values)
pg-loader ./data.tsv postgresql://postgres:password@localhost:5432/mydb

2. Import JSON hoặc NDJSON (JSON Lines) vào Postgres

NDJSON phù hợp cho các tệp dữ liệu lớn vì nó được đọc dòng-by-dòng, tối ưu RAM.

# Import JSON Array thông thường
pg-loader ./users.json postgresql://postgres:password@localhost:5432/mydb

# Import NDJSON (Newline Delimited JSON)
pg-loader ./logs.ndjson postgresql://postgres:password@localhost:5432/mydb

3. Migrate SQLite sang Postgres

# Di chuyển toàn bộ các bảng từ SQLite sang PostgreSQL
pg-loader sqlite://./local.db postgresql://postgres:password@localhost:5432/mydb -r

# Hoặc chỉ định trực tiếp đường dẫn file
pg-loader ./local.db postgresql://postgres:password@localhost:5432/mydb -r

# Di chuyển duy nhất một bảng cụ thể và ghi đè
pg-loader ./local.db postgresql://postgres:password@localhost:5432/mydb --table users -r

4. Migrate MySQL sang Postgres

# Di chuyển toàn bộ các bảng trong database từ MySQL sang Postgres (ghi đè nếu trùng)
pg-loader mysql://root:password@localhost:3306/my_mysql_db postgresql://postgres:password@localhost:5432/mydb -r

# Chỉ di chuyển duy nhất một bảng cụ thể
pg-loader mysql://root:password@localhost:3306/my_mysql_db postgresql://postgres:password@localhost:5432/mydb --table customers -r

5. Sử dụng tệp cấu hình .load (Giống pgloader)

Bạn có thể viết một file cấu hình .load (ví dụ migration.load) để định nghĩa kịch bản migration linh hoạt và gọn gàng:

LOAD DATABASE
     FROM postgresql://postgres:[email protected]:15432/source_db
     INTO postgresql://postgres:[email protected]:15432/target_db
 WITH include drop, create tables
 ALTER SCHEMA 'public' RENAME TO 'public_copy';

Sau đó thực thi một cách đơn giản:

pg-loader migration.load

(Lưu ý: Bạn cũng có thể ghi đè connection target từ CLI bằng cách truyền thêm đối số thứ hai: pg-loader migration.load postgresql://other_host...)

⚙️ Các Tùy chọn (Options)

| Option | Shortcut | Mô tả | |---|---|---| | --version | -V | Hiển thị phiên bản hiện tại của CLI | | --help | -h | Hiển thị hướng dẫn sử dụng | | --truncate | -t | Thực hiện TRUNCATE bảng đích trước khi load dữ liệu | | --replace | -r | Thực hiện DROP TABLE IF EXISTS và tạo mới bảng đích trước khi load | | --schema <schema> | -s | Định nghĩa schema đích của Postgres (mặc định: public) | | --table <name> | | Chỉ định tên bảng đích (với file) hoặc chọn bảng nguồn cụ thể cần di chuyển (với DB) | | --target-table <name>| | Chỉ định tên bảng đích trong PG (khi di chuyển một bảng cụ thể từ SQLite/MySQL) | | --delimiter <char> | | Chỉ định ký tự phân cách của CSV (mặc định: , hoặc \t đối với tsv) | | --env <path> | | Đường dẫn tới file .env tùy chỉnh để nạp biến môi trường |

📂 Cách thức hoạt động của COPY Streams

Lệnh INSERT INTO ... VALUES ... thông thường phải trải qua nhiều bước phân tích cú pháp SQL tại Postgres engine cho mỗi câu lệnh. pg-loader-cli sử dụng giao thức COPY, bằng cách biến đổi dữ liệu nguồn thành luồng văn bản định dạng CSV đã được escape an toàn theo chuẩn RFC 4180 và truyền trực tiếp vào cổng socket của PostgreSQL. Điều này giúp tận dụng tối đa băng thông mạng và hiệu năng đĩa của database, giúp import hàng triệu bản ghi chỉ trong vài giây.

📄 Giấy phép

Dự án này được phát hành dưới giấy phép MIT.