Giao diện
Kiến trúc
Tổng quan
plugin-data-source-main là cầu nối giữa metadata (định nghĩa collection/field lưu trong DB) và runtime ORM (Collection instances chạy trong bộ nhớ). Plugin quản lý toàn bộ lifecycle: lưu metadata → load vào runtime → sync bảng vật lý.
Meta-driven DDL
Plugin tuân theo mô hình meta-driven: admin định nghĩa collection/field qua UI → plugin tự động tạo/thay đổi bảng vật lý tương ứng.
Luồng tạo collection mới
Naming convention
Collection name được prefix t_ khi tạo bảng vật lý:
Metadata name | Bảng vật lý |
|---|---|
orders | t_orders |
orderItems | t_order_items |
Collection/Field lifecycle
CollectionRepository
Repository load tất cả collection từ DB theo topological sort — đảm bảo collection không phụ thuộc được load trước, collection có FK/inherit được load sau.
users (không phụ thuộc) → orders (FK → users) → orderItems (FK → orders)CollectionModel
| Method | Mô tả |
|---|---|
load() | Đọc metadata → tạo Collection instance trong Database ORM |
migrate() | Tạo/alter bảng vật lý (CREATE TABLE, ADD COLUMN, ALTER TYPE...) |
remove() | Xóa Collection instance khỏi ORM + DROP TABLE (nếu configured) |
FieldModel
| Method | Mô tả |
|---|---|
load() | Đọc field metadata → thêm field vào Collection instance |
| Sync | Đồng bộ unique index, default value, sort, FK constraint |
Field types
Plugin hỗ trợ nhiều field type, mỗi type mapping sang SQL column type:
| Field type | SQL type (PostgreSQL) | Ví dụ |
|---|---|---|
string | VARCHAR(255) | Tên, email |
text | TEXT | Mô tả dài |
integer | INTEGER | Số lượng |
bigInt | BIGINT | ID snowflake |
float / double | FLOAT / DOUBLE PRECISION | Giá |
boolean | BOOLEAN | Trạng thái |
date | DATE | Ngày sinh |
json / jsonb | JSON / JSONB | Options |
belongsTo | FK column | user_id → users |
hasMany | (không tạo column) | Liên kết ngược |
belongsToMany | Junction table | M2M qua bảng trung gian |
Hooks
Plugin đăng ký nhiều DB hooks xử lý các trường hợp đặc biệt:
| Hook | Thời điểm | Hành vi |
|---|---|---|
| View collections | afterSave | Tạo collection từ DB view, infer field types |
| Reverse fields | afterCreate (field) | Tự động tạo reverse field cho relation (VD: belongsTo → hasMany) |
| FK constraints | afterSave (field) | Tạo/sửa foreign key trên database |
| MySQL checks | beforeSave | Validate đặc thù MySQL (VARCHAR length, index prefix) |
| Validate | beforeSave | Kiểm tra name unique, reserved words, circular FK |
| Inherited collections | afterSave | Xử lý collection kế thừa (inherits) — PostgreSQL table inheritance |
Sync — Multi-instance
sendSyncMessage
Khi chạy cluster (nhiều instance), thay đổi collection/field trên instance A cần đồng bộ sang instance B. Plugin dùng sendSyncMessage qua message bus:
mainDataSource resource
| Action | Mô tả |
|---|---|
refresh | Reload tất cả collection từ metadata (clear + load lại) |
syncFields | Đồng bộ field từ database vật lý vào metadata (reverse engineering) |
Database views
Admin có thể tạo collection từ DB view có sẵn. Plugin infer field types từ view schema:
db2cm — Database to Collection Manager
Khi collection được tạo bằng code (không qua UI), db2cm tự động import metadata vào bảng collections/fields để hiển thị trên Collection Manager UI.