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

Yêu cầu hệ thống

Server Digiforce đang hoạt động
Oracle Database 12.1 trở lên (Thin mode) hoặc Oracle 11g+ (Thick mode, cần Oracle Instant Client)
Plugin data-source-manager đã được kích hoạt (bắt buộc)
Mạng: server Digiforce có thể kết nối đến Oracle Database (mở firewall port 1521)

Lưu ý

Plugin yêu cầu data-source-manager phải được bật trước. Ngoài ra, nếu kết nối Oracle Database phiên bản cũ (< 12.1), cần cài đặt Oracle Instant Client trên server.

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

Vào Settings → Plugin Manager
Tìm plugin-data-source-external-oracle
Bật toggle để kích hoạt

Plugin đăng ký type oracle vào DataSourceManager.factory và dialect OracleDialect vào Database.

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

Vào Settings → Data sources
Nhấn Add new
Chọn loại Oracle
Đ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	—
Data source display name	Có	Tên hiển thị	—
Host	Có	Địa chỉ server Oracle	`localhost`
Port	Có	Cổng Oracle Listener	`1521`
ServerName	Có	Service Name của Oracle instance	—
Username	Có	Tên đăng nhập Oracle	—
Password	Có	Mật khẩu	—
Connection mode	Có	Thin (>= 12.1) hoặc Thick (< 12.1)	`thin`
Client directory	Điều kiện	Đường dẫn Oracle Instant Client (chỉ khi Thick mode)	—
Table prefix	Không	Tiền tố 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 qua component TextAreaWithGlobalScope. Ví dụ: {{env.ORACLE_HOST}}.

Chế độ kết nối (Connection Mode)

Chế độ	Phiên bản Oracle	Yêu cầu	Mô tả
Thin	>= 12.1	Không cần client library	Kết nối trực tiếp qua JavaScript, nhẹ và nhanh
Thick	< 12.1 (11g)	Cần Oracle Instant Client	Sử dụng OCI (Oracle Call Interface), hỗ trợ đầy đủ tính năng Oracle cũ

Khi chọn Thick mode, trường Client directory xuất hiện. Plugin tự động tìm Oracle Instant Client trong:

storage/libs/oracle-client/instantclient_19_23
storage/libs/oracle-client/instantclient_19_25

Nếu không tìm thấy, cần chỉ định đường dẫn thủ công.

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

Nhấn Test connection để xác nhận. Plugin kết nối qua connect string host:port/servername sử dụng driver oracledb.

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

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

Kết nối đến Oracle
Query ALL_TABLES, ALL_TAB_COLUMNS để liệt kê bảng và cột
Schema mặc định là username (viết hoa) — Oracle phân biệt schema theo owner
Map kiểu cột Oracle → field type Digiforce

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

Kiểu Oracle	Field Type	Ghi chú
`NUMBER`	`integer`, `float`, `boolean`, `bigInt`	Tùy precision/scale
`BINARY_FLOAT`	`float`	—
`BINARY_DOUBLE`	`float`	—
`FLOAT`	`float`	—
`INTEGER`, `SMALLINT`	`integer`	—
`CHAR`, `NCHAR`	`string`	Hỗ trợ `uuid`, `nanoid`
`VARCHAR2`, `NVARCHAR2`	`string`	Hỗ trợ `uuid`, `nanoid`
`LONG`	`string`, `text`	—
`CLOB`, `NCLOB`	`string`, `text`	Large text
`JSON`	`json`	Oracle 21c+ native JSON
`DATE`	`datetimeNoTz`	Oracle DATE bao gồm cả giờ
`TIMESTAMP`	`datetimeNoTz`	—
`TIMESTAMP WITH TIME ZONE`	`datetimeTz`	—
`TIMESTAMP WITH LOCAL TIME ZONE`	`datetimeTz`	—
`ROWID`, `UROWID`	`string`	Row identifier

Lưu ý về kiểu DATE

Oracle DATE khác với SQL tiêu chuẩn — nó bao gồm cả ngày và giờ. Plugin cấu hình session NLS_DATE_FORMAT = 'YYYY-MM-DD HH24:MI:SS' và NLS_TIMESTAMP_FORMAT = 'YYYY-MM-DD HH24:MI:SS' tự động.

Cài đặt Oracle Instant Client (Thick mode)

Nếu cần kết nối Oracle Database phiên bản cũ (11g), cần cài Oracle Instant Client:

Plugin cung cấp command để cài đặt:

bash

yarn digiforce-nc install-oracle-client

Hoặc cài thủ công:

Tải Oracle Instant Client từ oracle.com
Giải nén vào thư mục, ví dụ: storage/libs/oracle-client/instantclient_19_25
Chỉ định đường dẫn trong cấu hình data source

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

sql

-- Tạo user
CREATE USER digiforce_ro IDENTIFIED BY "StrongPassword123";

-- Cấp quyền kết nối
GRANT CREATE SESSION TO digiforce_ro;

-- Chỉ đọc
GRANT SELECT ANY TABLE TO digiforce_ro;

-- Đọc và ghi (trên schema cụ thể)
GRANT SELECT, INSERT, UPDATE, DELETE ON hr.employees TO digiforce_rw;

Connection Pool

Plugin cấu hình connection pool mặc định:

Tham số	Giá trị
`maxConnections`	50
`minConnections`	5
`maxIdleTime`	30000ms (30 giây)

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

Sau khi cấu hình:

Vào Collection Manager → chọn data source vừa tạo
Xem danh sách bảng đã được map
Thử CRUD để kiểm tra hoạt động