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

Yêu cầu hệ thống

• Server Digiforce đang hoạt động
• MySQL phiên bản 5.7 trở lên hoặc MySQL 8.x
• Plugin data-source-manager đã được kích hoạt (bắt buộc)
• Mạng: server Digiforce có thể kết nối đến MySQL (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-mysql
3. Bật toggle để kích hoạt

Plugin đăng ký type mysql vào DataSourceManager.factory, cho phép tạo data source kết nối đến MySQL 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 MySQL
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 MySQL	localhost
Port	Có	Cổng kết nối	3306
Database	Có	Tên database	—
Username	Có	Tên đăng nhập MySQL	—
Password	Không	Mật khẩu	—
Table prefix	Không	Tiền tố bảng (để lọc)	—
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. Ví dụ: {{env.MYSQL_HOST}}.

Bước 3: Kiểm tra kết nối

Nhấn Test connection để xác nhận kết nối thành công. Plugin sử dụng driver mysql2 để kết nối đến MySQL.

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

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

1. Kết nối đến MySQL
2. Query INFORMATION_SCHEMA.TABLES để liệt kê bảng
3. Đọc cấu trúc cột, kiểu dữ liệu, index, primary key
4. Map bảng MySQL → collection Digiforce

Bạn có thể:

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

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

Kiểu MySQL	Field Type	Interface	Component
VARCHAR, CHAR	string	input	Input
TEXT, LONGTEXT, MEDIUMTEXT	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: ENUM('active','inactive') chuyển thành Select dropdown với options tương ứng.

Tạo user MySQL 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;

Cấu hình nâng cao

Table prefix

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

Character set

Mặc định MySQL plugin sử dụng utf8mb4 để hỗ trợ đầy đủ Unicode (tiếng Việt, emoji, ký tự đặc biệt). Đảm bảo database MySQL cũng dùng utf8mb4:

ALTER DATABASE my_database CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

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

Sau khi cấu hình:

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
4. Kiểm tra filter, sort, phân trang hoạt động đúng