Cài đặt và sử dụng — Collection FDW

Tổng quan

Plugin Collection FDW cho phép tạo collection từ bảng thuộc database bên ngoài thông qua cơ chế Foreign Data Wrapper (FDW) của PostgreSQL. Thay vì kết nối REST hay driver riêng, FDW biến bảng remote thành "foreign table" ngay trong PostgreSQL — cho phép SELECT, JOIN, thậm chí INSERT/UPDATE/DELETE trực tiếp.

Plugin hỗ trợ ba loại bridge:

Bridge	Mô tả
PgToPgBridge	PostgreSQL local ↔ PostgreSQL remote
MySQLToMySQLBridge	MySQL local ↔ MySQL remote
MariadbToMariadbBridge	MariaDB local ↔ MariaDB remote

Yêu cầu hệ thống

• Database chính phải là PostgreSQL (FDW là tính năng native của PostgreSQL) hoặc MySQL/MariaDB (dùng FEDERATED engine)
• Database bên ngoài phải cho phép kết nối từ server Digiforce (kiểm tra firewall, security group)
• Quyền SUPERUSER hoặc quyền CREATE FOREIGN TABLE trên PostgreSQL
• Extension FDW đã được cài (postgres_fdw, mysql_fdw...)

Lưu ý quan trọng

Plugin không hỗ trợ SQLite làm database chính. Nếu bạn đang dùng SQLite, hệ thống sẽ báo lỗi sqlite does not support foreign data wrapper khi kích hoạt plugin.

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

1. Vào Settings → Plugin Manager
2. Tìm plugin-collection-fdw
3. Bật toggle để kích hoạt
4. Khởi động lại ứng dụng nếu được yêu cầu

Bước 2: Tạo Database Server

Trước khi tạo FDW Collection, bạn cần đăng ký thông tin kết nối đến database bên ngoài. Plugin lưu trữ thông tin này trong collection databaseServers.

Trường	Kiểu	Mô tả
name	string (Primary Key)	Tên định danh cho server, ví dụ remote-orders-db
description	string	Mô tả ngắn gọn mục đích
options	json	Chứa host, port, database, username, password, dialect

Kiểm tra kết nối

Plugin cung cấp action databaseServers:testConnection để kiểm tra kết nối trước khi lưu. Khi gọi action này, hệ thống sẽ:

1. Tạo instance Database tạm với thông tin bạn cung cấp
2. Gọi sequelize.authenticate() để thử kết nối
3. Trả về { success: true } nếu thành công hoặc throw lỗi nếu thất bại

// Nội bộ plugin thực hiện test connection như sau:
const db = new Database({
  dialect: app.db.options.dialect,
  ...values,  // host, port, database, username, password
});
await db.sequelize.authenticate();

Bước 3: Tạo FDW Collection

1. Vào Collection Manager → Add new → Connect to foreign data
2. Điền Collection display name và Collection name
3. Chọn Database server đã tạo ở Bước 2
4. Chọn Remote table — hệ thống sẽ gọi databaseServers.tables:list để liệt kê bảng từ database bên ngoài
5. Xem trước các trường (fields) được import — hệ thống tự suy luận kiểu trường (field type) dựa trên kiểu cột của database remote
6. Nhấn Submit để tạo

Bước 4: Đồng bộ trường từ Remote

Khi cấu trúc bảng remote thay đổi (thêm/xóa cột), bạn có thể đồng bộ lại bằng action "Sync from remote table" trong cấu hình collection. Action này so sánh trường hiện tại với bảng remote và cập nhật tương ứng.

Các thành phần giao diện (Client)

Thành phần	Chức năng
DatabaseServerSelect	Dropdown chọn database server đã đăng ký
RemoteTableSelect	Dropdown chọn bảng từ server remote, tự động load khi chọn server
PreviewFields	Hiển thị danh sách trường sẽ được import với kiểu dữ liệu
PreviewTable	Xem trước dữ liệu mẫu từ bảng remote (phân trang, mỗi trang 10 dòng)
SyncFieldsAction	Nút đồng bộ trường từ bảng remote
CreateDatabaseServerAction	Form tạo mới database server
EditDatabaseServerAction	Form chỉnh sửa thông tin server

Quan hệ trường được hỗ trợ

FDW Collection hỗ trợ các loại quan hệ sau:

Interface	Mô tả
obo	One belongs to one
oho	One has one
o2m	One to many
m2o	Many to one
m2m	Many to many

Mẹo

FDW Collection không tự tạo id, createdAt, createdBy, updatedAt, updatedBy vì cấu trúc bảng được quyết định bởi database remote. Bạn cần đảm bảo bảng remote đã có primary key phù hợp.

Xóa FDW Collection

Khi xóa FDW Collection, hệ thống thực hiện:

• PostgreSQL: DROP FOREIGN TABLE IF EXISTS <table_name> CASCADE
• MySQL/MariaDB: Xóa bảng bình thường qua Sequelize

Lưu ý về hiệu năng

• Query qua FDW chịu thêm network latency giữa database chính và remote
• PostgreSQL tự động thực hiện query pushdown — đẩy điều kiện WHERE xuống remote để giảm dữ liệu truyền
• JOIN giữa foreign table và bảng nội bộ hoạt động nhưng hiệu năng phụ thuộc vào kích thước dữ liệu remote
• Nên đặt index trên bảng remote cho các cột thường xuyên được filter