Hướng dẫn cài đặt và cấu hình — PostgreSQL Data Source

Yêu cầu hệ thống

Thành phần	Yêu cầu tối thiểu
Server Digiforce	Phiên bản >= 1.0, đã kích hoạt plugin data-source-manager
PostgreSQL	Phiên bản 10 trở lên (khuyến nghị 14+)
Mạng	Server Digiforce phải kết nối được đến PostgreSQL (mở firewall / port 5432)

Lưu ý

Plugin data-source-manager phải được bật trước. Nếu chưa bật, plugin PostgreSQL sẽ từ chối kích hoạt và báo lỗi plugin need data-source-manager plugin enabled.

Bước 1: Kích hoạt plugin

1. Truy cập Settings → Plugin Manager
2. Tìm plugin-data-source-external-postgres
3. Bật công tắc Enable
4. Khởi động lại server nếu hệ thống yêu cầu

Khi plugin được tải, nó đăng ký type postgres vào DataSourceManager factory — cho phép tạo data source loại PostgreSQL từ giao diện quản trị.

Bước 2: Tạo data source mới

1. Vào Settings → Data Sources
2. Nhấn nút Add new
3. Chọn loại PostgreSQL
4. Điền thông tin kết nối:

Trường	Bắt buộc	Mô tả	Giá trị mặc định
Data source name	Có	Tên định danh (chỉ chữ, số, gạch dưới)	—
Display name	Có	Tên hiển thị trên giao diện	—
Host	Có	Địa chỉ IP hoặc hostname của server PostgreSQL	localhost
Port	Có	Cổng kết nối PostgreSQL	5432
Database	Có	Tên database cần kết nối	—
Username	Có	Tên đăng nhập PostgreSQL	—
Password	Không	Mật khẩu (hỗ trợ biến môi trường)	—
Table prefix	Không	Tiền tố bảng, lọc bảng theo prefix	—
Schema	Không	PostgreSQL schema cần introspect	public

Bước 3: Kiểm tra kết nối

Nhấn nút Test connection để xác nhận kết nối thành công trước khi lưu.

Plugin sẽ thực hiện:

1. Xác thực thông tin đăng nhập qua sequelize.authenticate()
2. Nếu có chỉ định schema, kiểm tra schema tồn tại trong information_schema.schemata
3. Trả về kết quả thành công hoặc thông báo lỗi chi tiết

Lỗi thường gặp khi test

• Connection refused — PostgreSQL chưa chạy hoặc port sai
• Authentication failed — Sai username/password
• Schema not exists — Schema được chỉ định không tồn tại trong database

Bước 4: Chọn bảng (Tables)

Sau khi lưu, hệ thống tự động introspect schema và hiển thị danh sách bảng. Bạn có thể:

• Chọn từng bảng muốn sử dụng làm collection
• Nhấn Add all collections để thêm tất cả bảng
• Bảng được chọn sẽ xuất hiện trong Collection Manager của data source tương ứng

Cấu hình SSL/TLS

Với môi trường production, nên bật SSL để mã hóa dữ liệu truyền tải. Plugin hỗ trợ đầy đủ các chế độ SSL của PostgreSQL.

Chế độ SSL	Mô tả
DISABLED	Không sử dụng SSL (mặc định)
ALLOW	Cho phép SSL nếu server hỗ trợ
PREFER	Ưu tiên SSL, fallback về không SSL
REQUIRE	Bắt buộc SSL, không xác minh chứng chỉ
VERIFY-CA	Bắt buộc SSL + xác minh CA certificate
VERIFY-FULL	Bắt buộc SSL + xác minh CA + hostname

Khi chọn VERIFY-CA hoặc VERIFY-FULL, cần cung cấp thêm:

Trường	Mô tả
CA certificate path	Đường dẫn đến file CA certificate trên server
Client certificate path	Đường dẫn đến client certificate (nếu dùng mutual TLS)
Client key path	Đường dẫn đến client private key
Reject unauthorized	Từ chối kết nối nếu chứng chỉ không hợp lệ

Cấu hình nâng cao

Connection Pool

Plugin sử dụng Sequelize connection pool. Các tham số có thể điều chỉnh:

Tham số	Mô tả	Mặc định
Pool size	Số kết nối tối đa trong pool	10
Idle timeout	Thời gian đóng kết nối không hoạt động (ms)	10000
Acquire timeout	Thời gian chờ lấy kết nối từ pool (ms)	60000

Table Prefix

Nếu database chứa nhiều bảng từ nhiều ứng dụng, bạn có thể đặt Table prefix để chỉ introspect các bảng có tiền tố phù hợp. Ví dụ: đặt prefix erp_ sẽ chỉ hiển thị các bảng erp_orders, erp_customers, v.v.

Xác nhận hoạt động

Sau khi cấu hình xong:

1. Vào Collection Manager của data source vừa tạo
2. Kiểm tra danh sách bảng đã được map thành collection
3. Thử tạo bản ghi mới để kiểm tra CRUD hoạt động đúng
4. Kiểm tra filter và sort trên các trường khác nhau

Mẹo

Nên tạo user PostgreSQL riêng cho Digiforce với quyền tối thiểu cần thiết:

• Chỉ đọc: GRANT SELECT ON ALL TABLES IN SCHEMA public TO digiforce_readonly;
• Đọc/ghi: GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO digiforce_rw;