Giao diện
@digiforce-nc/plugin-workflow-sql
Plugin đăng ký node chạy SQL query trong workflow, mở rộng plugin-workflow. Thực thi câu lệnh SQL trực tiếp trên data source được cấu hình, trả về kết quả dưới dạng mảng rows.
Plugin này làm gì?
Node SQL cho phép viết và thực thi câu lệnh SQL tùy ý trên database. Phù hợp khi cần query phức tạp (JOIN, subquery, CTE) mà các node CRUD tiêu chuẩn không đáp ứng được. Kết quả trả về dưới dạng mảng object.
Sử dụng khi:
- Query JOIN nhiều bảng
- Subquery, CTE, window functions
- Bulk INSERT/UPDATE với logic phức tạp
- Query trên data source bên ngoài (không phải main DB)
Cấu hình
| Tham số | Kiểu | Mô tả |
|---|---|---|
dataSource | string | Tên data source (mặc định: main) |
sql | string | Câu lệnh SQL (hỗ trợ template biến) |
params | array | Parameterized values (chống SQL injection) |
Input / Output
| Hướng | Dữ liệu | Mô tả |
|---|---|---|
| Input | sql | Câu lệnh SQL với placeholders |
| Input | params | Giá trị cho placeholders (theo thứ tự) |
| Output | rows | Mảng object kết quả (SELECT) |
| Output | affectedRows | Số dòng bị ảnh hưởng (INSERT/UPDATE/DELETE) |
| Output | fields | Metadata các cột kết quả |
Tính năng chính
| # | Tính năng | Chi tiết |
|---|---|---|
| 1 | Full SQL | Hỗ trợ SELECT, INSERT, UPDATE, DELETE, JOIN, subquery |
| 2 | Parameterized | Chống SQL injection bằng parameterized queries |
| 3 | Template biến | SQL sử dụng biến từ workflow context |
| 4 | Multi data source | Chọn data source (main, external, ...) |
| 5 | Metadata | Trả về thông tin cột kết quả |
Trường hợp sử dụng
| # | Kịch bản | Mô tả |
|---|---|---|
| 1 | Báo cáo phức tạp | Query JOIN nhiều bảng, GROUP BY, HAVING cho dashboard |
| 2 | Bulk update | UPDATE hàng loạt bản ghi theo điều kiện phức tạp |
| 3 | Query CTE | Dùng WITH ... AS cho logic đệ quy (cây phòng ban) |
| 4 | Cross-database | Query trên external data source đã kết nối |
| 5 | Raw performance | Query tối ưu khi ORM không đáp ứng hiệu suất |
Lưu ý quan trọng
- LUÔN dùng parameterized query khi giá trị đến từ user input - tránh SQL injection
- Query DDL (CREATE TABLE, ALTER) không được khuyến khích trong workflow
- Kết quả SELECT trả về tối đa theo cấu hình server (thường 1000 rows)
- Transaction: mỗi SQL node chạy trong transaction riêng, không share với node khác
- SQL dialect phụ thuộc vào database engine (PostgreSQL, MySQL, SQLite)
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/plugin-workflow | Workflow engine (peer) |
@digiforce-nc/server | Server framework (peer) |
@digiforce-nc/database | Database ORM - connection management (peer) |