Kyrage: Công cụ di chuyển cơ sở dữ liệu cho lập trình viên TypeScript

Khi làm việc trên các dự án cá nhân với CockroachDB, những công cụ phổ biến như Drizzle và Prisma đã gặp phải một số thách thức không lường trước được. Hỗ trợ CockroachDB của Drizzle vẫn đang trong giai đoạn lập kế hoạch và trong khi khả năng tương thích với PostgreSQL có vẻ hứa hẹn, các nỗ lực di chuyển đã dẫn đến lỗi liên quan đến kiểu dữ liệu. Prisma cũng gặp phải những vấn đề riêng biệt với CockroachDB.

Hầu hết các công cụ di chuyển cơ sở dữ liệu truyền thống cho Node.js yêu cầu viết thủ công các tệp di chuyển SQL. Điều thiếu sót là một công cụ có thể tự động tạo ra các di chuyển dựa trên sự khác biệt giữa các sơ đồ trong khi vẫn giữ mọi thứ trong hệ sinh thái TypeScript - một công cụ có thể cung cấp phương pháp tuyên bố tương tự như Ruby's ridgepole hoặc Atlas, nhưng với sự tích hợp tốt hơn cho các dự án Node.js.

Tạo ra Kyrage

Khoảng trống này đã dẫn đến sự ra đời của Kyrage (kirāju) - một dự án cá nhân được thiết kế để lấp đầy nhu cầu cụ thể này.

Kyrage: Công cụ di chuyển cơ sở dữ liệu đơn giản, dựa trên sơ đồ cho hệ sinh thái Node.js

Kyrage tự động tạo và áp dụng các di chuyển cơ sở dữ liệu bằng cách so sánh các định nghĩa sơ đồ TypeScript của bạn với trạng thái thực tế của cơ sở dữ liệu. Không còn cần phải viết các tệp di chuyển bằng tay!

Tại sao chọn Kyrage?

Các di chuyển cơ sở dữ liệu truyền thống yêu cầu viết thủ công các tệp di chuyển lên/xuống mỗi khi bạn thay đổi sơ đồ. Điều này dễ dẫn đến lỗi và tốn thời gian.

Kyrage có cách tiếp cận khác:

1. ✍️ Định nghĩa sơ đồ mong muốn của bạn trong TypeScript
2. 🔍 Kyrage so sánh nó với cơ sở dữ liệu thực tế của bạn
3. 🚀 Tự động tạo ra các di chuyển cần thiết
4. ✅ Áp dụng di chuyển chỉ với một lệnh

Đây là một phong cách quản lý sơ đồ cơ sở dữ liệu được gọi là Viết di chuyển theo phiên bản bởi Atlas.

📦 Cài đặt

# Cài đặt toàn cục
npm install -g @izumisy/kyrage

# Hoặc sử dụng với npx
npx @izumisy/kyrage --help

🚀 Bắt đầu nhanh

1. Tạo tệp cấu hình

Tạo một tệp kyrage.config.ts trong thư mục gốc của dự án:

import { defineConfig } from "@izumisy/kyrage";
export default defineConfig({});

2. Cách Kyrage hoạt động

Kyrage tự động tạo và áp dụng các di chuyển cơ sở dữ liệu bằng cách so sánh các định nghĩa sơ đồ TypeScript của bạn với trạng thái thực tế của cơ sở dữ liệu.

Công cụ này tuân theo cách tiếp cận mà Atlas gọi là "Viết di chuyển theo phiên bản":

1. Kết nối đến cơ sở dữ liệu của bạn và kiểm tra sơ đồ hiện tại
2. So sánh định nghĩa sơ đồ TypeScript của bạn với trạng thái hiện tại
3. Tạo một tệp di chuyển (dưới dạng JSON) dựa trên sự khác biệt
4. Áp dụng di chuyển tự động

Tính năng chính

Định nghĩa sơ đồ

Định nghĩa sơ đồ cơ sở dữ liệu của bạn bằng cú pháp TypeScript trực quan. Định nghĩa sơ đồ được hưởng lợi từ hệ thống kiểu của Kysely, cung cấp khả năng tự động hoàn thành IDE tuyệt vời và an toàn kiểu.

import { column as c, defineTable as t } from "@izumisy/kyrage";

export const members = t("members", {
  id: c("uuid", { primaryKey: true }),
  email: c("text", { unique: true }),
  name: c("text", { unique: true }),
  age: c("integer", { nullable: true }),
  createdAt: c("timestamptz"),
});

export const posts = t("posts", {
  id: c("uuid", { primaryKey: true }),
  author_id: c("uuid"),
  title: c("text"),
  content: c("text"),
  published: c("boolean", { default: false }),
  published_at: c("timestamptz", { nullable: true }),
});

Kyrage cũng hỗ trợ chỉ mục, ràng buộc khóa ngoại, khóa chính tổng hợp và ràng buộc duy nhất tổng hợp:

export const posts = t(
  "posts",
  {
    id: c("uuid"),
    author_id: c("uuid"),
    slug: c("text", { notNull: true }),
    title: c("text"),
    content: c("text", { notNull: true }),
  },
  (t) => [
    t.primaryKey(["id", "author_id"]),
    t.unique(["author_id", "slug"], {
      name: "unique_author_slug",
    }),
    t.reference("author_id", members, "id", {
      onDelete: "cascade",
      name: "posts_author_fk"
    }),
    t.index(["slug", "title"], { unique: true })
  ]
);

Hỗ trợ cơ sở dữ liệu phát triển

Kyrage bao gồm cơ chế tích hợp để khởi chạy cơ sở dữ liệu tạm thời cho phát triển dưới dạng container Docker. Điều này giải quyết các thách thức thường gặp trong môi trường phát triển nhóm.

Để sử dụng tính năng này, thêm cấu hình dev vào tệp cấu hình kyrage:

export default defineConfig({
  database: {
    dialect: "postgres",
    connectionString: "postgres://postgres:password@localhost:5432/mydb",
  },
  dev: {
    container: {
      image: "postgres:17"
    }
  },
  tables: [members, posts],
});

Quy trình cơ bản

# Tạo di chuyển
$ npx @izumisy/kyrage generate
# Xem trước SQL trước khi áp dụng
$ npx @izumisy/kyrage apply --plan
# Áp dụng di chuyển
$ npx @izumisy/kyrage apply

Thực hành tốt nhất

• Kiểm tra thường xuyên: Hãy chắc chắn rằng bạn kiểm tra các di chuyển của mình thường xuyên để tránh lỗi trong quá trình phát triển.
• Sử dụng môi trường phát triển tách biệt: Sử dụng cơ sở dữ liệu phát triển tạm thời để tránh xung đột trong nhóm.
• Tài liệu hóa quy trình: Ghi chép lại quy trình di chuyển để các thành viên trong nhóm có thể dễ dàng theo dõi.

Những cạm bẫy thường gặp

• Quên áp dụng di chuyển: Đảm bảo thực hiện lệnh áp dụng di chuyển sau khi tạo.
• Lỗi kiểu dữ liệu: Kiểm tra kỹ các kiểu dữ liệu để tránh lỗi khi áp dụng.

Mẹo hiệu suất

• Tối ưu hóa cấu trúc sơ đồ: Tạo sơ đồ rõ ràng và dễ dàng kiểm soát có thể tối ưu hóa hiệu suất.
• Sử dụng chỉ mục hợp lý: Đảm bảo rằng các chỉ mục được sử dụng đúng cách để tăng tốc độ truy vấn.

Giải quyết sự cố

• Không thể kết nối đến cơ sở dữ liệu: Kiểm tra thông tin xác thực và URL kết nối.
• Lỗi khi áp dụng di chuyển: Xem xét lại các di chuyển đã tạo và đảm bảo rằng chúng không chứa lỗi.

Kết luận

Kyrage là một công cụ mạnh mẽ cho các lập trình viên TypeScript, giúp đơn giản hóa quy trình di chuyển cơ sở dữ liệu. Với khả năng tự động hóa và dễ dàng tích hợp vào dự án hiện tại, Kyrage là một lựa chọn tuyệt vời cho bất kỳ ai làm việc với CockroachDB. Hãy bắt đầu sử dụng Kyrage ngay hôm nay để nâng cao hiệu quả làm việc của bạn!

Câu hỏi thường gặp

Kyrage có hỗ trợ các cơ sở dữ liệu khác không?

Kyrage hiện tại chủ yếu hỗ trợ CockroachDB và PostgreSQL.

Tôi có thể sử dụng Kyrage trong môi trường sản xuất không?

Có, nhưng hãy đảm bảo rằng bạn kiểm tra kỹ lưỡng các di chuyển trong môi trường phát triển trước khi áp dụng chúng trong sản xuất.

Tôi cần cài đặt những gì để sử dụng Kyrage?

Bạn chỉ cần Node.js và npm được cài đặt trên máy tính của mình để bắt đầu với Kyrage.