Giới thiệu typeorm-iris: TypeORM cho InterSystems IRIS từ Node.js

Dự án typeorm-iris cung cấp hỗ trợ thử nghiệm cho việc tích hợp TypeORM với InterSystems IRIS, giúp các nhà phát triển tương tác với IRIS bằng cách sử dụng các decorator và trừu tượng repository quen thuộc của TypeORM. Điều này mang lại trải nghiệm phát triển quen thuộc cho các nhà phát triển JavaScript và TypeScript khi xây dựng ứng dụng Node.js với IRIS làm cơ sở dữ liệu backend.

Mặc dù dự án thực hiện các điểm tích hợp chính với TypeORM và hỗ trợ các thao tác thực thể cơ bản, nhưng nó vẫn chưa được kiểm chứng trong môi trường sản xuất.

Tại Sao Chọn typeorm-iris?

Driver Node.js chính thức của InterSystems IRIS không cung cấp khả năng thực thi truy vấn SQL một cách tự nhiên giống như các driver cơ sở dữ liệu khác (ví dụ, cho PostgreSQL hoặc MySQL). Thay vào đó, bạn phải sử dụng một API dựa trên ObjectScript (ví dụ, %SQL.Statement) để chuẩn bị và thực thi các lệnh SQL.

Điều này trở thành vấn đề khi xây dựng các ứng dụng hiện đại mà dựa vào các công cụ Object-Relational Mapping (ORM) như TypeORM. TypeORM yêu cầu một driver cấp thấp hơn có khả năng chuẩn bị và thực thi SQL thô trong một phiên kết nối duy nhất, điều này hiện không khả thi với công cụ JavaScript của IRIS.

Để khắc phục những hạn chế này, typeorm-iris thực hiện các phần cần thiết để kết nối IRIS và TypeORM, sử dụng các giao diện thực thi SQL ObjectScript có sẵn.

Giai Đoạn Đầu & Các Vấn Đề Đã Biết

Dự án này vẫn đang trong giai đoạn đầu và chỉ được thử nghiệm với một số trường hợp hạn chế. Bạn có thể gặp phải sự không ổn định, thiếu tính năng và các thay đổi đột phá trong các phiên bản tương lai.

Một số hạn chế đáng chú ý trong quá trình phát triển bao gồm:

1. Số Lượng Gói Mạng Quá Nhiều

Thực thi SQL thông qua lớp %SQL.Statement từ JavaScript liên quan đến nhiều thông điệp mạng giữa quá trình Node.js và máy chủ IRIS. Ví dụ, một thao tác SQL logic có thể yêu cầu một số bước như:

• Chuẩn bị câu lệnh
• Thực thi truy vấn
• Lấy metadata
• Lấy hàng theo cách riêng lẻ

Mỗi bước này có thể dẫn đến các thông điệp riêng biệt qua mạng, dẫn đến quá tải đáng kể so với việc sử dụng một driver SQL gốc.

2. Không Hỗ Trợ Async/Parallel Thực Sự

Driver Node.js chính thức của IRIS không hỗ trợ sử dụng bất đồng bộ trong ngữ cảnh đa luồng hoặc dựa trên worker:

• Kết nối lại trong cùng một quá trình thường thất bại hoặc gây ra hành vi không thể đoán trước.
• Tạo các luồng worker và sử dụng driver bên trong chúng dẫn đến các vấn đề.
• Chỉ một kết nối trên mỗi quá trình hoạt động đáng tin cậy.

Những ràng buộc này khiến nó không phù hợp cho các ứng dụng Node.js hiện đại có tính đồng thời. Thực tế, điều này hạn chế khả năng mở rộng của driver với các khối lượng công việc đồng thời và giới hạn đáng kể các lựa chọn kiến trúc.

Hướng Dẫn Sử Dụng

Do việc sử dụng các tính năng SQL mới nhất của IRIS yêu cầu IRIS 2025.1+ để hoạt động.

Bạn có thể cài đặt typeorm-iris qua npm:

npm install typeorm-iris

Vì driver này không được hỗ trợ chính thức bởi TypeORM, việc sử dụng nó yêu cầu một giải pháp thay thế cho việc thiết lập DataSource. Bạn không thể sử dụng trực tiếp new DataSource() hoặc createConnection() như bạn đã làm với các driver chính thức.

Thiết lập DataSource Tùy Chỉnh

import { IRISDataSource, IRISConnectionOptions } from "typeorm-iris"

const dataSourceOptions: IRISConnectionOptions = {
    name: "iris",
    type: "iris",
    host: "localhost",
    port: 1972,
    username: "_SYSTEM",
    password: "SYS",
    namespace: "USER",
    logging: true,
    dropSchema: true,
}

export function createDataSource(options: any): IRISDataSource {
    // @ts-ignore
    const dataSource = new IRISDataSource({ ...dataSourceOptions, ...options })
    return dataSource
}

Khi đã được khởi tạo, bạn có thể sử dụng các decorator của TypeORM như thường lệ:

import { Entity, PrimaryGeneratedColumn, Column } from "typeorm"

@Entity()
export class User {
    @PrimaryGeneratedColumn()
    id: number

    @Column()
    name: string

    @Column()
    email: string
}

Việc sử dụng repositories cũng tương tự:

const userRepository = dataSource.getRepository(User)
const newUser = userRepository.create({ name: "Alice", email: "alice@example.com" })
await userRepository.save(newUser)

Dự Án Mẫu

Kho lưu trữ GitHub bao gồm thư mục sample/ với một số ví dụ hoàn chỉnh:

• sample1-simple-entity
• sample2-one-to-one
• sample3-many-to-one
• sample4-many-to-many
• sample16-indexes

Những ví dụ này bao gồm việc lưu trữ cơ bản, các mối quan hệ và các tính năng schema, cung cấp các minh họa sử dụng thực tế.

Kiểm Tra Đơn Vị

Kiểm tra ban đầu bao gồm các trường hợp sử dụng sau:

Mô Hình Thực Thể

• nên lưu thành công và sử dụng các phương thức tĩnh thành công
• nên tải lại thực thể đã cho thành công
• nên tải lại chính xác cùng một thực thể
• nên upsert thành công

Schema Thực Thể > Chỉ Mục

• cơ bản

Lưu Trữ

• chức năng cơ bản
• cập nhật thực thể
• chèn > cập nhật-các-cột-quan-hệ-sau-khi-chèn
• nhiều-nhiều
• một-một

Các bài kiểm tra này có phạm vi hạn chế và sẽ có thêm nhiều bài kiểm tra khi dự án trưởng thành.

Tính Năng Hỗ Trợ

• Decorator thực thể: @Entity(), @Column(), @PrimaryGeneratedColumn()
• Repositories: create, save, find, delete, v.v.
• Xóa và đồng bộ schema (thử nghiệm)
• Hỗ trợ một phần cho các mối quan hệ và truy vấn tùy chỉnh

Một lần nữa, những tính năng này vẫn còn ở giai đoạn đầu và có thể không bao quát tất cả các khả năng của TypeORM.

Ràng Buộc Thực Tế

Hạn Chế của Driver Node.js InterSystems IRIS

• Chỉ một kết nối có thể sử dụng trên mỗi quá trình
• Không hỗ trợ tốt cho các thao tác song song hoặc đa luồng
• Thiếu hỗ trợ API SQL gốc (thông qua giao thức SQL)
• Phụ thuộc nặng vào giao tiếp dựa trên tin nhắn sử dụng giao thức độc quyền

Cho đến khi InterSystems cập nhật driver chính thức với hỗ trợ thực thi SQL đúng cách và các thao tác đồng thời, dự án này sẽ bị hạn chế về hiệu suất và khả năng mở rộng.

Phản Hồi & Đóng Góp

Vì đây là một driver thử nghiệm, phản hồi của bạn rất quan trọng. Dù bạn đang thử nghiệm cho một dự án nhỏ hay đánh giá nó cho việc sử dụng rộng rãi hơn, hãy chia sẻ các vấn đề và đề xuất trên GitHub:

➡️ github.com/caretdev/typeorm-iris/issues

Các yêu cầu kéo, trường hợp kiểm tra và cải tiến tài liệu cũng được hoan nghênh.

Các Kế Hoạch Tiếp Theo

Các cải tiến trong tương lai dự kiến bao gồm:

• Mở rộng độ phủ kiểm tra cho các truy vấn và thiết kế schema trong thực tế
• Xử lý nhiều tính năng của trình xây dựng truy vấn TypeORM
• Nghiên cứu tối ưu hóa batching
• Cải tiến introspection schema cho các lần di chuyển

Kết Luận

typeorm-iris mang lại sự hỗ trợ TypeORM cần thiết cho các nhà phát triển InterSystems IRIS. Mặc dù hiện tại nó chưa sẵn sàng cho sản xuất và thừa hưởng những hạn chế nghiêm trọng từ hạ tầng driver hiện tại, nhưng nó cung cấp một nền tảng cho việc thử nghiệm thêm và có thể được áp dụng rộng rãi hơn trong cộng đồng phát triển IRIS.