Tham chiếu API — MariaDB Data Source

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

Plugin hỗ trợ đầy đủ các thao tác CRUD thông qua resource API chuẩn của Digiforce:

Thao tác	Phương thức	Mô tả
list	GET	Lấy danh sách bản ghi có phân trang, filter, sort
get	GET	Lấy một bản ghi theo Primary Key
create	POST	Tạo bản ghi mới
update	PUT	Cập nhật bản ghi
destroy	DELETE	Xóa bản ghi

Tạo Data Source qua API

await agent.resource('dataSources').create({
  values: {
    key: 'external-mariadb',
    type: 'mariadb',
    displayName: 'MariaDB Production',
    options: {
      host: '192.168.1.100',
      port: 3306,
      database: 'my_erp',
      username: 'app_user',
      password: '***',
    },
  },
});

Kiểm tra kết nối qua API

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

Introspect lại Schema

Sau khi tạo data source, hệ thống tự động introspect. Để introspect lại thủ công (khi schema MariaDB thay đổi):

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

Filter Operators

Hỗ trợ đầy đủ filter operators trên dữ liệu MariaDB:

Operator	Mô tả	Ví dụ
$eq	Bằng	{ name: { $eq: 'value' } }
$ne	Khác	{ status: { $ne: 'deleted' } }
$gt	Lớn hơn	{ age: { $gt: 18 } }
$gte	Lớn hơn hoặc bằng	{ age: { $gte: 18 } }
$lt	Nhỏ hơn	{ price: { $lt: 1000 } }
$lte	Nhỏ hơn hoặc bằng	{ price: { $lte: 1000 } }
$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	{ status: { $notIn: ['deleted'] } }
$empty	Rỗng/null	{ email: { $empty: true } }
$notEmpty	Không rỗng	{ email: { $notEmpty: true } }

Ví dụ filter kết hợp

await agent.resource('external-mariadb.orders').list({
  filter: {
    $and: [
      { status: { $eq: 'completed' } },
      { total: { $gt: 1000 } },
      { createdAt: { $gte: '2024-01-01' } },
    ],
  },
  sort: ['-createdAt'],
  page: 1,
  pageSize: 20,
});

Cấu trúc nội bộ Plugin

Kiến trúc class

Quy trình Introspect

1. MariaDatabaseIntrospector.getTableList() — gọi showAllTables() qua Sequelize QueryInterface
2. Với mỗi bảng, đọc cấu trúc cột qua describeTable()
3. Map kiểu cột MariaDB sang field type qua getFieldTypeMap() (từ @digiforce-nc/database)
4. Xác định interface UI qua getTypeInterfaceConfig() (từ type-interface-map.ts)
5. Đăng ký collection vào CollectionManager

Giới hạn và lưu ý

• Primary key bắt buộc: Bảng không có primary key sẽ không hỗ trợ CRUD đầy đủ
• Auto-increment: Trường auto-increment không thể ghi từ phía Digiforce
• Stored procedures: Không được hỗ trợ — chỉ truy vấn trực tiếp trên bảng
• Views: Hỗ trợ đọc (read-only), không ghi
• Phân trang mặc định: 20 bản ghi/trang, có thể thay đổi qua pageSize
• Kết nối: Sử dụng Sequelize connection pool mặc định