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

Yêu cầu hệ thống

• Server Digiforce đang hoạt động
• Microsoft SQL Server 2016 trở lên hoặc Azure SQL Database
• Plugin data-source-manager đã được kích hoạt (bắt buộc)
• Mạng: server Digiforce có thể kết nối đến SQL Server (mở firewall port 1433)
• SQL Server đã bật TCP/IP protocol (mặc định có thể bị tắt trên SQL Server Express)

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 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-mssql
3. Bật toggle để kích hoạt

Plugin đăng ký type mssql vào DataSourceManager.factory và đăng ký dialect MssqlDialect vào Database.

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 MSSQL
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 SQL Server	—
Port	Có	Cổng kết nối	1433
Database	Có	Tên database	—
Username	Có	Tên đăng nhập SQL Auth	—
Password	Không	Mật khẩu	—
Table prefix	Không	Tiền tố bảng (để lọc)	—
Encrypt connection	Không	Mã hóa kết nối TLS	false
Trust server certificate	Không	Tin tưởng certificate server (cho self-signed)	false
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.MSSQL_HOST}} thay vì hardcode.

Ngoài ra, biến môi trường MSSQL_TRUST_SERVER_CERTIFICATE nếu được set sẽ tự động bật trustServerCertificate.

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

Nhấn Test connection để xác nhận kết nối. Plugin sử dụng driver tedious (TDS protocol) để kết nối đến SQL Server.

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

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

1. Kết nối đến SQL Server
2. Query sys.tables, sys.columns để liệt kê bảng và cột
3. Map kiểu cột SQL Server sang field type Digiforce
4. Hiển thị danh sách bảng để chọn

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

Kiểu SQL Server	Field Type	Ghi chú
tinyint, smallint	integer	Cũng hỗ trợ map sang boolean, sort
int	integer	Hỗ trợ unixTimestamp, sort
bigint	bigInt	Hỗ trợ unixTimestamp, sort
bit	bit	Field type đặc biệt cho SQL Server
decimal, money, smallmoney	decimal	—
numeric	float	—
float, real	float	—
date	dateOnly	Chỉ ngày, không giờ
time	time	Chỉ giờ
datetime, datetime2	datetimeNoTz	Không timezone
datetimeoffset	datetimeTz	Có timezone
char, varchar	string	Cũng hỗ trợ uuid, nanoid
nchar, nvarchar	string	Unicode, hỗ trợ uuid, nanoid
text, ntext	text	—
json	json	Hỗ trợ array
uniqueidentifier	uuid	GUID native SQL Server

Các field type đặc biệt cho MSSQL

Plugin đăng ký ba field type riêng để xử lý đặc thù SQL Server:

Field Type	Class	Mô tả
date	MSSQLDateField	Xử lý kiểu date đúng format SQL Server
datetimeNoTz	MSSQLDatetimeNoTzField	Xử lý datetime2 không timezone
bit	MSSQLBitField	Xử lý kiểu bit (0/1) thành boolean

Cấu hình bảo mật kết nối

Mã hóa TLS

Bật Encrypt connection khi:

• Kết nối qua Internet (không cùng mạng nội bộ)
• Yêu cầu bảo mật compliance (PCI-DSS, HIPAA...)
• Kết nối đến Azure SQL Database (bắt buộc encrypt)

Trust Server Certificate

Bật khi:

• SQL Server dùng self-signed certificate
• Môi trường development/testing
• Không nên bật trên production với certificate chính thức

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

-- Chỉ đọc
CREATE LOGIN digiforce_ro WITH PASSWORD = 'StrongPassword123!';
USE my_database;
CREATE USER digiforce_ro FOR LOGIN digiforce_ro;
EXEC sp_addrolemember 'db_datareader', 'digiforce_ro';

-- Đọc và ghi
CREATE LOGIN digiforce_rw WITH PASSWORD = 'StrongPassword123!';
USE my_database;
CREATE USER digiforce_rw FOR LOGIN digiforce_rw;
EXEC sp_addrolemember 'db_datareader', 'digiforce_rw';
EXEC sp_addrolemember 'db_datawriter', 'digiforce_rw';

Kiểm tra SQL Server cho phép kết nối TCP/IP

Trên SQL Server Configuration Manager:

1. Mở SQL Server Network Configuration → Protocols for [instance]
2. Đảm bảo TCP/IP ở trạng thái Enabled
3. Kiểm tra tab IP Addresses → IPAll → TCP Port = 1433
4. Khởi động lại SQL Server service sau khi thay đổi