Tham chiếu API — Oracle Database Data Source

Các thao tác CRUD được hỗ trợ

Thao tác	Phương thức	Mô tả
list	GET	Lấy danh sách bản ghi có phân trang, filter, sort
get	GET	Lấy một bản ghi theo Primary Key
create	POST	Tạo bản ghi mới
update	PUT	Cập nhật bản ghi
destroy	DELETE	Xóa bản ghi

Tạo Data Source qua API

await agent.resource('dataSources').create({
  values: {
    key: 'external-oracle',
    type: 'oracle',
    displayName: 'Oracle HR Database',
    options: {
      host: '192.168.1.100',
      port: 1521,
      servername: 'orcl',
      username: 'hr_readonly',
      password: '***',
      connectionMode: 'thin',
    },
  },
});

Kiểm tra kết nối qua API

await agent.resource('dataSources').testConnection({
  values: {
    type: 'oracle',
    options: {
      host: '192.168.1.100',
      port: 1521,
      servername: 'orcl',
      username: 'hr_readonly',
      password: '***',
    },
  },
});

Introspect lại Schema

await agent.resource('dataSources').refresh({
  filterByTk: 'external-oracle',
});

Filter Operators

Hỗ trợ đầy đủ filter operators. Plugin đăng ký thêm hai operator đặc biệt cho Oracle:

Operator	Mô tả	Ví dụ
$eq	Bằng	{ name: { $eq: 'value' } }
$ne	Khác	{ status: { $ne: 'deleted' } }
$gt / $gte	Lớn hơn / Lớn hơn bằng	{ age: { $gt: 18 } }
$lt / $lte	Nhỏ hơn / Nhỏ hơn bằng	{ price: { $lt: 1000 } }
$like	Chứa (LIKE)	{ name: { $like: '%keyword%' } }
$in	Trong danh sách	{ status: { $in: ['active', 'pending'] } }
$empty	Rỗng/null (Oracle custom)	{ email: { $empty: true } }
$notEmpty	Không rỗng (Oracle custom)	{ email: { $notEmpty: true } }

Operator $empty và $notEmpty được đăng ký riêng vì Oracle xử lý NULL/empty string khác với các database khác (Oracle coi empty string là NULL).

Kiến trúc class

Đặc biệt: createDatabaseFromOptions()

Override phức tạp nhất trong các plugin data source:

1. Oracle Instant Client: Tự động tìm và khởi tạo nếu Thick mode
2. Connection string: Xây dựng host:port/servername
3. NLS format: Set NLS_DATE_FORMAT và NLS_TIMESTAMP_FORMAT qua afterConnect hook
4. SQL converter: Sử dụng OracleSqlConverter để chuyển đổi SQL chuẩn sang Oracle SQL
5. Custom operators: Đăng ký $empty và $notEmpty
6. Return values: Override generateReturnValues() để xử lý RETURNING ... INTO (đặc thù Oracle)
7. Date filter: Xử lý filter trên trường datetimeNoTz bằng TO_DATE()

SQL Converter

Oracle SQL có nhiều điểm khác biệt so với SQL chuẩn. Plugin sử dụng OracleSqlConverter để tự động chuyển đổi SQL sinh bởi Sequelize sang cú pháp Oracle tương thích.

Hỗ trợ Oracle cũ (11g)

Plugin hỗ trợ Oracle 11g thông qua Thick mode:

• Cần Oracle Instant Client 19.x
• Thick mode sử dụng OCI (Oracle Call Interface) native
• Hỗ trợ đầy đủ CRUD nhưng một số tính năng mới (JSON native) không khả dụng

Giới hạn và lưu ý

• Primary key bắt buộc để CRUD hoạt động
• Tên bảng/cột: Oracle mặc định viết HOA. Schema tự động chuyển thành uppercase
• BLOB, RAW, LONG, BFILE: Không hỗ trợ trong RETURNING clause — bị loại khỏi return values
• Stored procedures: Không hỗ trợ
• Views: Hỗ trợ đọc (read-only)
• Phân trang: Oracle sử dụng ROWNUM hoặc FETCH FIRST (12c+)
• Empty string = NULL: Oracle coi empty string là NULL — operator $empty/$notEmpty được tùy chỉnh cho phù hợp