pg-local-cli

Một công cụ CLI bằng Node.js giúp bạn dễ dàng khởi tạo, khởi chạy và quản lý các database instance PostgreSQL trên localhost mà không cần sử dụng Docker, Podman hay cài đặt PostgreSQL toàn hệ thống.

Dự án này sử dụng các binary PostgreSQL portable chính thức được tải tự động tùy theo hệ điều hành (Windows, macOS, Linux) thông qua thư viện embedded-postgres.

✨ Tính năng chính

• Không cần Docker/Podman: Phù hợp cho máy yếu hoặc môi trường không cài được Docker.
• Không cần cài Postgres hệ thống: Tự động tải binary độc lập về thư mục home của user.
• Hỗ trợ đổi Host/Port: Dễ dàng đổi cổng hoặc địa chỉ IP lắng nghe để tránh xung đột cổng (ví dụ: cổng mặc định 5432 bị chiếm).
• Chạy ngầm (Daemon): Khi gõ start, Postgres sẽ chạy ngầm, bạn có thể tắt terminal đi mà database vẫn chạy bình thường.
• Hỗ trợ nhiều Instance: Tạo và cấu hình độc lập nhiều database khác nhau (ví dụ: my_app, dev_db).
• Đa nền tảng: Hỗ trợ đầy đủ Windows (x64), macOS (Intel, Apple Silicon) và Linux (x64, arm64, v.v.).

🚀 Cài đặt

Cài đặt global thông qua npm để sử dụng CLI ở mọi nơi:

npm install -g pg-local-cli

(Lưu ý: npm sẽ tự động tải phiên bản PostgreSQL binary phù hợp nhất với OS và kiến trúc CPU của bạn trong quá trình cài đặt).

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

Sau khi cài đặt, bạn sẽ có lệnh pg-local.

1. Khởi động PostgreSQL (Start)

Khởi chạy instance mặc định (tên là default):

pg-local start

Khởi chạy một instance với tên cụ thể:

pg-local start my_app

(Nếu đây là lần đầu chạy, CLI sẽ tự động khởi tạo database cluster - chạy initdb trước khi start).

2. Kiểm tra trạng thái (Status)

Xem thông tin chi tiết của instance đang chạy hay dừng:

pg-local status

Hoặc xem instance cụ thể:

pg-local status my_app

3. Dừng PostgreSQL (Stop)

Dừng instance một cách an toàn và giải phóng tài nguyên:

pg-local stop

Hoặc:

pg-local stop my_app

4. Liệt kê các instance (List)

Xem danh sách toàn bộ các database instance mà bạn đã tạo cùng trạng thái và cổng chạy của chúng:

pg-local list

5. Cấu hình Host / Port / User (Config)

Xem cấu hình hiện tại:

pg-local config show

Thay đổi các thông số cấu hình (Ví dụ thay đổi port thành 5433 để tránh xung đột cổng):

pg-local config set port 5433

Thay đổi port cho một instance cụ thể:

pg-local config set port 15432 my_app

Các khóa cấu hình hỗ trợ:

• port: Cổng TCP chạy database (mặc định: 5432).
• host: Địa chỉ IP lắng nghe (mặc định: 127.0.0.1).
• user: Tên tài khoản superuser (mặc định: postgres).
• password: Mật khẩu superuser (mặc định: password).
• database: Tên database cần tự động tạo và kết nối (mặc định sẽ giống với tên user).
• databaseDir: Đường dẫn lưu dữ liệu database (mặc định trong thư mục ~/.pg-local/instances/<name>/data).

6. Xem Log của PostgreSQL (Logs)

Xem toàn bộ log đã ghi:

pg-local logs

Theo dõi log thời gian thực (real-time stream) giống như lệnh tail -f:

pg-local logs -f
# Hoặc cho instance cụ thể
pg-local logs my_app -f

7. Xóa dữ liệu (Destroy)

Dừng database và xóa hoàn toàn thư mục chứa dữ liệu của instance đó:

pg-local destroy

🔌 Chuỗi kết nối (Connection String)

Mặc định, bạn có thể kết nối tới PostgreSQL bằng chuỗi kết nối:

postgresql://postgres:[email protected]:5432/postgres

(Hoặc cổng mới nếu bạn đã thay đổi trong cấu hình).

Bạn có thể kết nối từ bất kỳ công cụ quản lý nào như DBeaver, TablePlus, pgAdmin, hoặc các ORM như Prisma, Drizzle, TypeORM trong dự án của bạn.

📂 Nơi lưu trữ dữ liệu

Toàn bộ cấu hình và dữ liệu của công cụ được lưu trữ độc lập tại:

• Unix/macOS/Linux: ~/.pg-local/
• Windows: C:\Users\<Tên_User>\.pg-local\

📄 Giấy phép

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