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

Yêu cầu hệ thống

• Server Digiforce đang hoạt động
• MariaDB phiên bản 10.3 trở lên
• Plugin data-source-manager đã được kích hoạt (bắt buộc)
• Mạng: server Digiforce có thể kết nối đến MariaDB (mở firewall port 3306)

Lưu ý

Plugin yêu cầu data-source-manager phải được bật trước. Nếu chưa bật, hệ thống sẽ báo lỗi plugin need data-source-manager plugin enabled khi kích hoạt.

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

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

Plugin đăng ký type mariadb vào DataSourceManager.factory, cho phép tạo data source kết nối đến MariaDB bên ngoài.

Bước 2: Tạo Data Source mới

1. Vào Settings → Data sources
2. Nhấn Add new
3. Chọn loại MariaDB
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ữ, số, gạch dưới)	—
Data source display name	Có	Tên hiển thị	—
Host	Có	Địa chỉ server MariaDB	localhost
Port	Có	Cổng kết nối	3306
Database	Có	Tên database	—
Username	Có	Tên đăng nhập MariaDB	—
Password	Không	Mật khẩu	—
Table prefix	Không	Tiền tố bảng (để lọc bảng)	—
Enabled	—	Bật/tắt data source	true

Mẹo

Các trường cấu hình hỗ trợ biến môi trường thông qua component TextAreaWithGlobalScope. Bạn có thể dùng {{env.MARIADB_HOST}} thay vì hardcode giá trị.

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ẽ:

1. Tạo Database instance với dialect mariadb
2. Gọi sequelize.authenticate() để kiểm tra
3. Trả về kết quả thành công hoặc thông báo lỗi chi tiết

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

Sau khi lưu data source, plugin tự động introspect schema:

1. Kết nối đến MariaDB
2. Gọi showAllTables() để liệt kê bảng
3. Đọc cấu trúc từng bảng (cột, kiểu dữ liệu, index, primary key)
4. Map bảng MariaDB thành collection Digiforce

Bạn có thể:

• Chọn bảng muốn sử dụng làm collection
• Thêm tất cả bảng cùng lúc (option "Add all collections")
• Refresh để cập nhật khi schema MariaDB thay đổi

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

Plugin tự động map kiểu dữ liệu MariaDB sang field interface của Digiforce:

Kiểu MariaDB	Field Type	Interface	Component
VARCHAR, CHAR	string	input	Input
TEXT, LONGTEXT	text	textarea	Input.TextArea
INT, MEDIUMINT, SMALLINT	integer	integer	InputNumber
BIGINT	bigInt	integer	InputNumber
FLOAT	float	number	InputNumber
DOUBLE	double	number	InputNumber
DECIMAL	decimal	number	InputNumber
BOOLEAN, TINYINT(1)	boolean	checkbox	Checkbox
DATE	date	datetime	DatePicker
DATETIME	datetime	datetime	DatePicker
TIMESTAMP	datetimeTz	datetime	DatePicker
TIME	time	time	TimePicker
JSON	json	json	Input.JSON
ENUM(...)	string	select	Select (tự phát hiện enum values)
UUID	uuid	uuid	Input

Đặc biệt

Kiểu ENUM được tự động phát hiện và chuyển thành field select với danh sách giá trị lấy từ định nghĩa cột. Ví dụ: ENUM('active','inactive') → Select với options active, inactive.

Cấu hình nâng cao

Table prefix

Nếu database có nhiều bảng và bạn chỉ muốn hiển thị bảng với tiền tố nhất định (ví dụ: app_users, app_orders), đặt Table prefix = app_.

Tạo user MariaDB với quyền tối thiểu

-- Chỉ đọc
CREATE USER 'digiforce_ro'@'%' IDENTIFIED BY 'password';
GRANT SELECT ON my_database.* TO 'digiforce_ro'@'%';

-- Đọc và ghi
CREATE USER 'digiforce_rw'@'%' IDENTIFIED BY 'password';
GRANT SELECT, INSERT, UPDATE, DELETE ON my_database.* TO 'digiforce_rw'@'%';

FLUSH PRIVILEGES;

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

Sau khi cấu hình xong:

1. Vào Collection Manager → chọn data source vừa tạo
2. Xem danh sách bảng đã được map thành collection
3. Thử tạo, sửa, xóa bản ghi để kiểm tra CRUD hoạt động đúng