Giao diện

Cài đặt và sử dụng — Collection SQL ​

Tổng quan ​

Plugin Collection SQL cho phép tạo collection ảo (virtual) từ câu lệnh SQL tùy chỉnh. Thay vì giới hạn trong một bảng đơn, bạn có thể viết SELECT với JOIN, GROUP BY, subquery hoặc WITH clause — kết quả trở thành collection chỉ đọc, có thể hiển thị trên giao diện với đầy đủ phân trang và bộ lọc.

Đặc điểm chính ​

Đặc điểmMô tả
Chỉ hỗ trợ SELECTKhông cho phép INSERT, UPDATE, DELETE hoặc bất kỳ thao tác ghi nào
Hỗ trợ WITH clauseCó thể dùng Common Table Expression (CTE)
Tự suy luận trườngPlugin phân tích SQL AST để xác định bảng nguồn và kiểu trường
Kiểm tra bảo mậtChặn các hàm nguy hiểm (pg_read_file, LOAD_FILE, BENCHMARK...)

Yêu cầu ​

  • Plugin đã được kích hoạt trong Plugin Manager
  • Người dùng cần quyền pm.data-source-manager.collection-sql (ACL snippet)
  • Câu lệnh SQL phải hợp lệ trên database đang sử dụng (PostgreSQL, MySQL hoặc SQLite)

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

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

Bước 2: Tạo SQL Collection ​

  1. Vào Collection Manager → Add new → SQL Collection
  2. Nhập câu lệnh SQL trong editor
  3. Nhấn Preview để xem 5 dòng kết quả mẫu
  4. Hệ thống tự động suy luận danh sách trường (fields) từ câu SQL
  5. Tùy chỉnh tên hiển thị, interface cho từng trường nếu cần
  6. Nhấn Submit để lưu

Ví dụ SQL hợp lệ ​

JOIN nhiều bảng:

sql
SELECT
  o.id,
  o.created_at,
  u.nickname AS customer_name,
  SUM(oi.quantity * oi.price) AS total_amount
FROM orders o
JOIN users u ON o.user_id = u.id
JOIN order_items oi ON o.id = oi.order_id
GROUP BY o.id, o.created_at, u.nickname

Dùng WITH clause (CTE):

sql
WITH monthly_revenue AS (
  SELECT
    DATE_TRUNC('month', created_at) AS month,
    SUM(total) AS revenue
  FROM orders
  GROUP BY DATE_TRUNC('month', created_at)
)
SELECT month, revenue
FROM monthly_revenue
ORDER BY month DESC

Bảo mật SQL ​

Plugin thực hiện kiểm tra bảo mật trước khi thực thi bất kỳ câu SQL nào thông qua hàm checkSQL():

1. Chỉ cho phép SELECT:

  • Câu SQL phải bắt đầu bằng SELECT hoặc WITH ... SELECT
  • Bất kỳ câu lệnh nào khác (INSERT, UPDATE, DROP...) đều bị từ chối

2. Chặn từ khóa nguy hiểm:

DatabaseTừ khóa bị chặn
PostgreSQLpg_read_file, pg_read_binary_file, pg_stat_file, pg_ls_dir, pg_terminate_backend, pg_cancel_backend, current_setting, set_config, pg_reload_conf, pg_sleep, generate_series
MySQLLOAD_FILE, BENCHMARK, @@global., @@session.
SQLitesqlite3_load_extension, load_extension

3. Chỉ lấy câu lệnh đầu tiên (tách theo ;) để tránh injection nhiều câu SQL.

Cảnh báo

Mặc dù plugin có cơ chế kiểm tra, SQL injection vẫn là rủi ro tiềm ẩn. Chỉ cấp quyền tạo SQL Collection cho admin đáng tin cậy.

Cơ chế suy luận trường (Field Inference) ​

Khi bạn viết SQL, plugin phân tích cú pháp SQL (AST) để xác định:

  1. Bảng nguồn từ mệnh đề FROM và JOIN
  2. Cột từ danh sách SELECT
  3. Ánh xạ trường: Nếu bảng nguồn tương ứng với một collection đã tồn tại, plugin kế thừa type, interface, uiSchema từ collection đó

Ví dụ: nếu SQL chọn users.nickname, và collection users có trường nickname với interface input, thì trường trong SQL Collection cũng sẽ có interface input.

Các action không khả dụng ​

SQL Collection là chỉ đọc. Các action sau bị vô hiệu hóa:

ActionTrạng thái
createKhông khả dụng
updateKhông khả dụng
destroyKhông khả dụng
importXlsxKhông khả dụng
destroyManyKhông khả dụng
updateManyKhông khả dụng

API Endpoints ​

EndpointPhương thứcMô tả
sqlCollection:executePOSTThực thi SQL và trả về dữ liệu mẫu (5 dòng) + danh sách trường
sqlCollection:setFieldsPOSTCập nhật danh sách trường cho SQL Collection
sqlCollection:updatePOSTCập nhật SQL và trường, tải lại collection

Cơ chế truy vấn nội bộ ​

Khi người dùng xem dữ liệu SQL Collection trên UI, plugin sinh câu query theo cấu trúc:

sql
SELECT <attributes>
FROM (<câu SQL gốc>) AS <tên_collection>
WHERE <điều kiện lọc từ UI>
ORDER BY <sắp xếp>
LIMIT <số dòng> OFFSET <vị trí>

Câu SQL gốc trở thành subquery, cho phép hệ thống thêm WHERE, ORDER BY, LIMIT/OFFSET mà không cần sửa đổi SQL của người dùng.

Lưu ý về hiệu năng ​

  • SQL chạy trực tiếp trên database chính — query phức tạp trên bảng lớn sẽ ảnh hưởng hiệu suất
  • Mỗi lần người dùng truy cập đều thực thi lại SQL (không có cache)
  • Nên tạo index phù hợp trên các bảng tham gia trong SQL
  • Tránh SELECT * nếu chỉ cần một số cột
  • Cân nhắc dùng EXPLAIN để kiểm tra query plan trước khi lưu