Tham chiếu API — PostgreSQL Data Source

Tổng quan

Plugin plugin-data-source-external-postgres không tạo thêm API endpoint riêng mà tận dụng hệ thống resource API chuẩn của Digiforce. Khi bảng PostgreSQL được map thành collection, tất cả các thao tác CRUD đều hoạt động qua API giống như collection nội bộ.

Các thao tác CRUD được hỗ trợ

Thao tác	Phương thức HTTP	Endpoint	Mô tả
list	GET	/api/<collection>:list	Lấy danh sách bản ghi có phân trang, filter, sort
get	GET	/api/<collection>:get?filterByTk=<id>	Lấy một bản ghi theo primary key
create	POST	/api/<collection>:create	Tạo bản ghi mới
update	PUT	/api/<collection>:update?filterByTk=<id>	Cập nhật bản ghi
destroy	DELETE	/api/<collection>:destroy?filterByTk=<id>	Xóa bản ghi

Lưu ý

Primary key là bắt buộc để các thao tác get/update/destroy hoạt động. Bảng không có primary key chỉ hỗ trợ thao tác list.

Data Source API

Tạo data source qua API

await agent.resource('dataSources').create({
  values: {
    key: 'my-external-pg',
    type: 'postgres',
    displayName: 'PostgreSQL Production',
    options: {
      host: '192.168.1.100',
      port: 5432,
      database: 'my_erp',
      username: 'app_user',
      password: 'secret',
      schema: 'public',
    },
  },
});

Kiểm tra kết nối (Test Connection)

await agent.resource('dataSources').testConnection({
  values: {
    type: 'postgres',
    options: {
      host: '192.168.1.100',
      port: 5432,
      database: 'my_erp',
      username: 'app_user',
      password: 'secret',
    },
  },
});

Phương thức testConnection nội bộ thực hiện:

1. Tạo kết nối Database tạm thời với dialect postgres
2. Gọi sequelize.authenticate() để xác thực
3. Nếu có chỉ định schema, truy vấn information_schema.schemata để kiểm tra
4. Đóng kết nối và trả về kết quả

Làm mới schema (Refresh / Introspect lại)

await agent.resource('dataSources').refresh({
  filterByTk: 'my-external-pg',
});

Thao tác này kích hoạt DatabaseIntrospector quét lại cấu trúc bảng, cột, kiểu dữ liệu và primary key từ PostgreSQL.

Ánh xạ kiểu dữ liệu (Field Mapping)

Plugin tự động ánh xạ kiểu dữ liệu PostgreSQL sang field type của Digiforce thông qua fieldTypeMap['postgres']:

Kiểu PostgreSQL	Field Type Digiforce	Ghi chú
VARCHAR / TEXT / CHAR	string	Chuỗi văn bản
INTEGER / SMALLINT	integer	Số nguyên 32-bit
BIGINT	bigInt	Số nguyên 64-bit
REAL / FLOAT4	float	Số thực dấu phẩy động
DOUBLE PRECISION / FLOAT8	double	Số thực độ chính xác kép
DECIMAL / NUMERIC	decimal	Số thập phân chính xác
BOOLEAN	boolean	Giá trị true/false
DATE	date	Chỉ ngày tháng
TIMESTAMP / TIMESTAMPTZ	datetime	Ngày giờ có/không có timezone
JSON / JSONB	json	Dữ liệu JSON
ARRAY	array	Mảng (hỗ trợ xác định element type)
UUID	uuid	Chuỗi UUID

Xử lý đặc biệt cho ARRAY

Plugin có logic riêng để xác định kiểu phần tử của cột ARRAY. Nó truy vấn information_schema.element_types để lấy element_type, sau đó ánh xạ sang field type tương ứng.

Xử lý Auto-Increment và UUID

Cột có defaultValue khớp với pattern nextval(...) hoặc uuid_generate_v4(...) sẽ được đánh dấu autoIncrement: true, nghĩa là Digiforce sẽ không yêu cầu nhập giá trị khi tạo bản ghi.

Filter và Sort

Plugin hỗ trợ đầy đủ các filter operator của Digiforce:

Operator	Mô tả	Ví dụ
$eq	Bằng	{ name: { $eq: 'Nguyễn Văn A' } }
$ne	Khác	{ status: { $ne: 'deleted' } }
$gt / $gte	Lớn hơn / Lớn hơn hoặc bằng	{ age: { $gt: 18 } }
$lt / $lte	Nhỏ hơn / Nhỏ hơn hoặc bằng	{ price: { $lt: 1000000 } }
$like	Chứa (LIKE)	{ name: { $like: '%keyword%' } }
$notLike	Không chứa	{ name: { $notLike: '%spam%' } }
$in	Trong danh sách	{ status: { $in: ['active', 'pending'] } }
$notIn	Không trong danh sách	{ role: { $notIn: ['banned'] } }
$null	Giá trị NULL	{ email: { $null: true } }
$notNull	Không NULL	{ phone: { $notNull: true } }

Unique Index và Constraint

Plugin truy vấn PostgreSQL system catalog (pg_indexes) để xác định các unique index trên bảng. Thông tin này được sử dụng để:

• Đánh dấu trường có thuộc tính unique: true
• Hỗ trợ kiểm tra trùng lặp khi tạo/cập nhật bản ghi

Giới hạn kỹ thuật

Giới hạn	Chi tiết
Bảng không có primary key	Chỉ hỗ trợ đọc (list), không hỗ trợ get/update/destroy
Auto-increment	Không thể ghi giá trị từ phía Digiforce cho cột auto-increment
Stored procedures	Không hỗ trợ gọi stored procedure
Views	Hỗ trợ đọc (read-only), không thể ghi
Phân trang mặc định	20 bản ghi/trang, thay đổi qua tham số pageSize
Cross-datasource relation	Không hỗ trợ quan hệ giữa bảng từ data source khác nhau