Drizzle schema

Drizzle를 사용하면 기본 데이터베이스에서 지원하는 다양한 모델과 속성을 TypeScript로 스키마를 정의할 수 있습니다. 스키마를 정의하면, 이는 쿼리(Drizzle-ORM 사용)와 마이그레이션(Drizzle-Kit 사용)의 향후 수정에 대한 단일 소스로 작동합니다.

마이그레이션 프로세스에 Drizzle-Kit을 사용하는 경우, Drizzle-Kit이 이를 가져와서 마이그레이션 diff 프로세스에서 사용할 수 있도록 스키마 파일에 정의된 모든 모델을 내보내야 합니다.

스키마 파일 구성하기

SQL 스키마를 TypeScript에서 직접 선언할 수 있습니다. 단일 schema.ts 파일에 선언하거나, 여러 파일에 분산시킬 수 있습니다 — 원하는 대로 선택하세요. 완전한 자유입니다!

단일 파일 스키마

Drizzle로 스키마를 선언하는 가장 일반적인 방법은 모든 테이블을 하나의 schema.ts 파일에 넣는 것입니다.

참고: 스키마 파일의 이름은 원하는 대로 지정할 수 있습니다. 예를 들어 models.ts나 다른 이름도 가능합니다.

이 접근 방식은 정의된 테이블 모델이 너무 많지 않거나, 모든 테이블을 하나의 파일에 유지하는 것이 괜찮은 경우에 적합합니다

예시:

📦 <project root>
 └ 📂 src
    └ 📂 db
       └ 📜 schema.ts

drizzle.config.ts 파일에서 스키마 파일의 경로를 지정해야 합니다. 이 설정을 사용하면 Drizzle이 schema.ts 파일을 읽고 마이그레이션 생성 프로세스에서 이 정보를 사용합니다. drizzle.config.ts 파일과 Drizzle 마이그레이션에 대한 자세한 내용은 다음을 참조하세요: 링크

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: 'postgresql', // 'mysql' | 'sqlite' | 'turso'
  schema: './src/db/schema.ts'
})

여러 파일로 구성된 스키마

Drizzle 모델(테이블, 열거형, 시퀀스 등)을 하나의 파일뿐만 아니라 원하는 모든 파일에 배치할 수 있습니다. 단, Drizzle Kit이 이를 가져와서 마이그레이션에 사용할 수 있도록 해당 파일에서 모든 모델을 내보내야 합니다.

하나의 사용 사례는 각 테이블을 별도의 파일로 분리하는 것입니다.

📦 <project root>
 └ 📂 src
    └ 📂 db
       └ 📂 schema
          ├ 📜 users.ts
          ├ 📜 countries.ts
          ├ 📜 cities.ts
          ├ 📜 products.ts
          ├ 📜 clients.ts
          └ 📜 etc.ts

drizzle.config.ts 파일에서 스키마 폴더의 경로를 지정해야 합니다. 이 설정을 사용하면 Drizzle이 schema 폴더를 읽고 모든 파일을 재귀적으로 찾아서 모든 Drizzle 테이블을 가져옵니다. drizzle.config.ts 파일과 Drizzle 마이그레이션에 대한 자세한 내용은 다음을 참조하세요: 링크

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: 'postgresql', // 'mysql' | 'sqlite' | 'turso'
  schema: './src/db/schema'
})

원하는 방식으로 그룹화할 수도 있습니다. 예를 들어 사용자 관련 테이블, 메시징 관련 테이블, 제품 관련 테이블 등의 그룹을 생성할 수 있습니다.

📦 <project root>
 └ 📂 src
    └ 📂 db
       └ 📂 schema
          ├ 📜 users.ts
          ├ 📜 messaging.ts
          └ 📜 products.ts

데이터 스키마 정의하기

Drizzle 스키마는 사용 중인 데이터베이스의 여러 모델 유형으로 구성됩니다. Drizzle을 사용하면 다음을 지정할 수 있습니다:

열, 제약 조건 등이 있는 테이블
스키마(PostgreSQL만 해당)
열거형
시퀀스(PostgreSQL만 해당)
뷰
구체화된 뷰
기타

하나씩 살펴보면서 Drizzle로 스키마를 정의하는 방법을 확인해 보겠습니다

테이블 및 열 선언

Drizzle의 테이블은 데이터베이스에서와 마찬가지로 최소 1개의 열로 정의되어야 합니다. 알아야 할 중요한 점은 Drizzle에는 공통 테이블 객체와 같은 것이 없다는 것입니다. 사용 중인 방언(PostgreSQL, MySQL 또는 SQLite)을 선택해야 합니다.

PostgreSQL Table

MySQL Table

SQLite Table

import { pgTable, integer } from "drizzle-orm/pg-core"

export const users = pgTable('users', {
  id: integer()
});

import { mysqlTable, int } from "drizzle-orm/mysql-core"

export const users = mysqlTable('users', {
  id: int()
});

import { sqliteTable, integer } from "drizzle-orm/sqlite-core"

export const users = sqliteTable('users', {
  id: integer()
});

기본적으로 Drizzle은 데이터베이스 쿼리에서 열에 대해 TypeScript 키 이름을 사용합니다. 따라서 예제의 스키마와 쿼리는 아래와 같은 SQL 쿼리를 생성합니다.

이 예제는 db 객체를 사용하며, 그 초기화는 문서의 이 부분에서 다루지 않습니다. 데이터베이스 연결 방법을 알아보려면 연결 문서를 참조하세요.

TypeScript 키 = 데이터베이스 키

// schema.ts
import { integer, pgTable, varchar } from "drizzle-orm/pg-core";

export const users = pgTable('users', {
  id: integer(),
  first_name: varchar()
})

// query.ts
await db.select().from(users);

SELECT "id", "first_name" from users;

TypeScript 코드와 데이터베이스에서 다른 이름을 사용하려면 열 별칭을 사용할 수 있습니다.

// schema.ts
import { integer, pgTable, varchar } from "drizzle-orm/pg-core";

export const users = pgTable('users', {
  id: integer(),
  firstName: varchar('first_name')
})

// query.ts
await db.select().from(users);

SELECT "id", "first_name" from users;

카멜 케이스와 스네이크 케이스

데이터베이스 모델 이름은 종종 snake_case 규칙을 사용하는 반면, TypeScript에서는 모델 이름에 camelCase를 사용하는 것이 일반적입니다. 이로 인해 스키마에 많은 별칭 정의가 필요할 수 있습니다. 이를 해결하기 위해 Drizzle은 Drizzle 데이터베이스 초기화 시 하나의 선택적 매개변수를 포함하여 TypeScript의 camelCase를 데이터베이스의 snake_case로 자동 매핑하는 방법을 제공합니다.

이러한 매핑을 위해 Drizzle DB 선언에서 casing 옵션을 사용할 수 있습니다. 이 매개변수는 데이터베이스 모델 명명 규칙을 지정하는 데 도움이 되며 모든 JavaScript 키를 적절히 매핑하려고 시도합니다.

// schema.ts
import { drizzle } from "drizzle-orm/node-postgres";
import { integer, pgTable, varchar } from "drizzle-orm/pg-core";

export const users = pgTable('users', {
  id: integer(),
  firstName: varchar()
})

// db.ts
const db = drizzle({ connection: process.env.DATABASE_URL, casing: 'snake_case' })

// query.ts
await db.select().from(users);

SELECT "id", "first_name" from users;

고급 사용법

Drizzle ORM에서 사용할 수 있는 몇 가지 기법이 있습니다. Drizzle은 완전히 TypeScript 파일에 있으므로 일반 TypeScript 프로젝트에서 코드로 할 수 있는 모든 작업을 본질적으로 수행할 수 있습니다.

일반적인 기능 중 하나는 열을 서로 다른 위치로 분리한 다음 재사용하는 것입니다. 예를 들어 updated_at, created_at, deleted_at 열을 고려해보세요. 많은 테이블/모델이 시스템에서 엔티티의 생성, 삭제 및 업데이트를 추적하고 분석하기 위해 이 세 가지 필드를 필요로 할 수 있습니다.

이러한 열을 별도의 파일에 정의한 다음 가져와서 모든 테이블 객체에 전개할 수 있습니다.

// columns.helpers.ts
const timestamps = {
  updated_at: timestamp(),
  created_at: timestamp().defaultNow().notNull(),
  deleted_at: timestamp(),
}

// users.sql.ts
export const users = pgTable('users', {
  id: integer(),
  ...timestamps
})

// posts.sql.ts
export const posts = pgTable('posts', {
  id: integer(),
  ...timestamps
})

스키마

PostgreSQL

MySQL

SQLite

PostgreSQL에는 schema라는 엔티티가 있습니다(우리는 이를 folders라고 불러야 한다고 생각합니다). 이는 PostgreSQL에서 다음과 같은 구조를 만듭니다:

pgSchema로 PostgreSQL 스키마를 관리하고 그 안에 다른 모델을 배치할 수 있습니다.

Drizzle을 사용하여 관리하려는 스키마를 정의합니다.

import { pgSchema } from "drizzle-orm/pg-core"

export const customSchema = pgSchema('custom');

그런 다음 스키마 객체 안에 테이블을 배치합니다.

import { integer, pgSchema } from "drizzle-orm/pg-core";

export const customSchema = pgSchema('custom');

export const users = customSchema.table('users', {
  id: integer()
})

MySQL에는 Schema라는 엔티티가 있지만, MySQL 용어로는 이것이 Database와 동일합니다.

drizzle-orm으로 정의하고 쿼리에서 사용할 수 있지만 drizzle-kit에서 감지되거나 마이그레이션 흐름에 포함되지 않습니다.

Drizzle을 사용하여 관리하려는 스키마를 정의합니다.

import { mysqlSchema } from "drizzle-orm/mysql-core"

export const customSchema = mysqlSchema('custom');

그런 다음 스키마 객체 안에 테이블을 배치합니다.

import { int, mysqlSchema } from "drizzle-orm/mysql-core";

export const customSchema = mysqlSchema('custom');

export const users = customSchema.table('users', {
  id: int()
})

예제

기본 사항을 알았으니 실제 프로젝트에 대한 스키마 예제를 정의하여 더 나은 이해를 얻어보겠습니다.

모든 예제는 generateUniqueString을 사용합니다. 구현은 모든 스키마 예제 이후에 제공됩니다.

PostgreSQL

MySQL

SQLite

import { AnyPgColumn } from "drizzle-orm/pg-core";
import { pgEnum, pgTable as table } from "drizzle-orm/pg-core";
import * as t from "drizzle-orm/pg-core";

export const rolesEnum = pgEnum("roles", ["guest", "user", "admin"]);

export const users = table(
  "users",
  {
    id: t.integer().primaryKey().generatedAlwaysAsIdentity(),
    firstName: t.varchar("first_name", { length: 256 }),
    lastName: t.varchar("last_name", { length: 256 }),
    email: t.varchar().notNull(),
    invitee: t.integer().references((): AnyPgColumn => users.id),
    role: rolesEnum().default("guest"),
  },
  (table) => [
    t.uniqueIndex("email_idx").on(table.email)
  ]
);

export const posts = table(
  "posts",
  {
    id: t.integer().primaryKey().generatedAlwaysAsIdentity(),
    slug: t.varchar().$default(() => generateUniqueString(16)),
    title: t.varchar({ length: 256 }),
    ownerId: t.integer("owner_id").references(() => users.id),
  },
  (table) => [
    t.uniqueIndex("slug_idx").on(table.slug),
    t.index("title_idx").on(table.title),
  ]
);

export const comments = table("comments", {
  id: t.integer().primaryKey().generatedAlwaysAsIdentity(),
  text: t.varchar({ length: 256 }),
  postId: t.integer("post_id").references(() => posts.id),
  ownerId: t.integer("owner_id").references(() => users.id),
});

import { mysqlTable as table } from "drizzle-orm/mysql-core";
import * as t from "drizzle-orm/mysql-core";
import { AnyMySqlColumn } from "drizzle-orm/mysql-core";

export const users = table(
  "users",
  {
    id: t.int().primaryKey().autoincrement(),
    firstName: t.varchar("first_name", { length: 256 }),
    lastName: t.varchar("last_name", { length: 256 }),
    email: t.varchar({ length: 256 }).notNull(),
    invitee: t.int().references((): AnyMySqlColumn => users.id),
    role: t.mysqlEnum(["guest", "user", "admin"]).default("guest"),
  },
  (table) => [
    t.uniqueIndex("email_idx").on(table.email)
  ]
);

export const posts = table(
  "posts",
  {
    id: t.int().primaryKey().autoincrement(),
    slug: t.varchar({ length: 256 }).$default(() => generateUniqueString(16)),
    title: t.varchar({ length: 256 }),
    ownerId: t.int("owner_id").references(() => users.id),
  },
  (table) => [
    t.uniqueIndex("slug_idx").on(table.slug),
    t.index("title_idx").on(table.title),
  ]
);

export const comments = table("comments", {
  id: t.int().primaryKey().autoincrement(),
  text: t.varchar({ length: 256 }),
  postId: t.int("post_id").references(() => posts.id),
  ownerId: t.int("owner_id").references(() => users.id),
});

import { sqliteTable as table } from "drizzle-orm/sqlite-core";
import * as t from "drizzle-orm/sqlite-core";
import { AnySQLiteColumn } from "drizzle-orm/sqlite-core";

export const users = table(
  "users",
  {
    id: t.int().primaryKey({ autoIncrement: true }),
    firstName: t.text("first_name"),
    lastName: t.text("last_name"),
    email: t.text().notNull(),
    invitee: t.int().references((): AnySQLiteColumn => users.id),
    role: t.text().$type<"guest" | "user" | "admin">().default("guest"),
  },
  (table) => [
    t.uniqueIndex("email_idx").on(table.email)
  ]
);

export const posts = table(
  "posts",
  {
    id: t.int().primaryKey({ autoIncrement: true }),
    slug: t.text().$default(() => generateUniqueString(16)),
    title: t.text(),
    ownerId: t.int("owner_id").references(() => users.id),
  },
  (table) => [
    t.uniqueIndex("slug_idx").on(table.slug),
    t.index("title_idx").on(table.title),
  ]
);

export const comments = table("comments", {
  id: t.int().primaryKey({ autoIncrement: true }),
  text: t.text({ length: 256 }),
  postId: t.int("post_id").references(() => posts.id),
  ownerId: t.int("owner_id").references(() => users.id),
});

generateUniqueString 구현:

function generateUniqueString(length: number = 12): string {
  const characters =
    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
  let uniqueString = "";

  for (let i = 0; i < length; i++) {
    const randomIndex = Math.floor(Math.random() * characters.length);
    uniqueString += characters[randomIndex];
  }

  return uniqueString;
}

다음 단계

스키마 관리

열 타입 인덱스 및 제약 조건 데이터베이스 뷰 데이터베이스 스키마 시퀀스 확장

기초부터 시작

데이터베이스 연결 데이터 쿼리 마이그레이션