Drizzle 소프트 관계

Drizzle 관계의 유일한 목적은 관계형 데이터를 가장 간단하고 간결한 방식으로 쿼리할 수 있도록 하는 것입니다:

Relational queries

Select with joins

import * as schema from './schema';
import { drizzle } from 'drizzle-orm/…';

const db = drizzle(client, { schema });

const result = db.query.users.findMany({
  with: {
    posts: true,
  },
});

[{
  id: 10,
  name: "Dan",
  posts: [
    {
      id: 1,
      content: "SQL is awesome",
      authorId: 10,
    },
    {
      id: 2,
      content: "But check relational queries",
      authorId: 10,
    }
  ]
}]

import { drizzle } from 'drizzle-orm/…';
import { eq } from 'drizzle-orm';
import { posts, users } from './schema';

const db = drizzle(client);

const res = await db.select()
                    .from(users)
                    .leftJoin(posts, eq(posts.authorId, users.id))
                    .orderBy(users.id)
const mappedResult =

일대일

Drizzle ORM은 relations 연산자를 사용하여 테이블 간의 일대일 관계를 정의하는 API를 제공합니다.

사용자가 다른 사용자를 초대할 수 있는 사용자 간 일대일 관계의 예시입니다 (이 예시는 자기 참조를 사용합니다):

import { pgTable, serial, text, integer, boolean } from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';

export const users = pgTable('users', {
	id: serial('id').primaryKey(),
	name: text('name'),
	invitedBy: integer('invited_by'),
});

export const usersRelations = relations(users, ({ one }) => ({
	invitee: one(users, {
		fields: [users.invitedBy],
		references: [users.id],
	}),
}));

다른 예로는 사용자의 프로필 정보가 별도의 테이블에 저장되어 있는 경우입니다. 이 경우 외래 키가 “profile_info” 테이블에 저장되어 있기 때문에 사용자 관계에는 fields나 references가 없습니다. 이는 TypeScript에게 user.profileInfo가 nullable임을 알려줍니다:

import { pgTable, serial, text, integer, jsonb } from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';

export const users = pgTable('users', {
	id: serial('id').primaryKey(),
	name: text('name'),
});

export const usersRelations = relations(users, ({ one }) => ({
	profileInfo: one(profileInfo),
}));

export const profileInfo = pgTable('profile_info', {
	id: serial('id').primaryKey(),
	userId: integer('user_id').references(() => users.id),
	metadata: jsonb('metadata'),
});

export const profileInfoRelations = relations(profileInfo, ({ one }) => ({
	user: one(users, { fields: [profileInfo.userId], references: [users.id] }),
}));

const user = await queryUserWithProfileInfo();
//____^? type { id: number, profileInfo: { ... } | null  }

일대다

Drizzle ORM은 relations 연산자를 사용하여 테이블 간의 일대다 관계를 정의하는 API를 제공합니다.

사용자와 그들이 작성한 게시물 간의 일대다 관계 예시:

import { pgTable, serial, text, integer } from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';

export const users = pgTable('users', {
	id: serial('id').primaryKey(),
	name: text('name'),
});

export const usersRelations = relations(users, ({ many }) => ({
	posts: many(posts),
}));

export const posts = pgTable('posts', {
	id: serial('id').primaryKey(),
	content: text('content'),
	authorId: integer('author_id'),
});

export const postsRelations = relations(posts, ({ one }) => ({
	author: one(users, {
		fields: [posts.authorId],
		references: [users.id],
	}),
}));

이제 게시물에 댓글을 추가해 봅시다:

...

export const posts = pgTable('posts', {
	id: serial('id').primaryKey(),
	content: text('content'),
	authorId: integer('author_id'),
});

export const postsRelations = relations(posts, ({ one, many }) => ({
	author: one(users, {
		fields: [posts.authorId],
		references: [users.id],
	}),
	comments: many(comments)
}));

export const comments = pgTable('comments', {
	id: serial('id').primaryKey(),
	text: text('text'),
	authorId: integer('author_id'),
	postId: integer('post_id'),
});

export const commentsRelations = relations(comments, ({ one }) => ({
	post: one(posts, {
		fields: [comments.postId],
		references: [posts.id],
	}),
}));

다대다

Drizzle ORM은 소위 중간(junction) 또는 조인(join) 테이블을 통해 테이블 간의 다대다 관계를 정의하는 API를 제공합니다. 이들은 명시적으로 정의되어야 하며 관련 테이블 간의 연관성을 저장합니다.

사용자와 그룹 간의 다대다 관계 예시:

import { relations } from 'drizzle-orm';
import { integer, pgTable, primaryKey, serial, text } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  name: text('name'),
});

export const usersRelations = relations(users, ({ many }) => ({
  usersToGroups: many(usersToGroups),
}));

export const groups = pgTable('groups', {
  id: serial('id').primaryKey(),
  name: text('name'),
});

export const groupsRelations = relations(groups, ({ many }) => ({
  usersToGroups: many(usersToGroups),
}));

export const usersToGroups = pgTable(
  'users_to_groups',
  {
    userId: integer('user_id')
      .notNull()
      .references(() => users.id),
    groupId: integer('group_id')
      .notNull()
      .references(() => groups.id),
  },
  (t) => [
		primaryKey({ columns: [t.userId, t.groupId] })
	],
);

export const usersToGroupsRelations = relations(usersToGroups, ({ one }) => ({
  group: one(groups, {
    fields: [usersToGroups.groupId],
    references: [groups.id],
  }),
  user: one(users, {
    fields: [usersToGroups.userId],
    references: [users.id],
  }),
}));

외래 키

relations가 외래 키와 비슷해 보인다는 것을 눈치챘을 것입니다 — references 속성도 있습니다. 그렇다면 차이점은 무엇일까요?

외래 키는 테이블 간의 관계를 정의한다는 점에서 비슷한 목적을 가지고 있지만, relations와는 다른 수준에서 작동합니다.

외래 키는 데이터베이스 수준의 제약조건으로, 모든 insert/update/delete 작업에서 확인되며 제약조건이 위반되면 오류를 발생시킵니다. 반면에 relations는 더 높은 수준의 추상화로, 애플리케이션 수준에서만 테이블 간의 관계를 정의하는 데 사용됩니다. 데이터베이스 스키마에는 전혀 영향을 주지 않으며 외래 키를 암시적으로 생성하지도 않습니다.

이는 relations와 외래 키가 함께 사용될 수 있지만 서로 의존적이지 않다는 것을 의미합니다. 외래 키를 사용하지 않고 relations를 정의할 수 있으며 (그 반대도 마찬가지), 이를 통해 외래 키를 지원하지 않는 데이터베이스에서도 사용할 수 있습니다.

다음 두 예시는 Drizzle 관계형 쿼리를 사용하여 데이터를 쿼리하는 측면에서 정확히 동일하게 작동합니다.

schema1.ts

schema2.ts

export const users = pgTable('users', {
	id: serial('id').primaryKey(),
	name: text('name'),
});

export const usersRelations = relations(users, ({ one, many }) => ({
	profileInfo: one(users, {
		fields: [profileInfo.userId],
		references: [users.id],
	}),
}));

export const profileInfo = pgTable('profile_info', {
	id: serial('id').primaryKey(),
	userId: integer("user_id"),
	metadata: jsonb("metadata"),
});

export const users = pgTable('users', {
	id: serial('id').primaryKey(),
	name: text('name'),
});

export const usersRelations = relations(users, ({ one, many }) => ({
	profileInfo: one(users, {
		fields: [profileInfo.userId],
		references: [users.id],
	}),
}));

export const profileInfo = pgTable('profile_info', {
	id: serial('id').primaryKey(),
	userId: integer("user_id").references(() => users.id),
	metadata: jsonb("metadata"),
});

외래 키 작업

자세한 정보는 PostgreSQL 외래 키 문서를 확인하세요

부모 테이블의 참조된 데이터가 수정될 때 발생해야 하는 작업을 지정할 수 있습니다. 이러한 작업을 “외래 키 작업”이라고 합니다. PostgreSQL은 이러한 작업에 대한 여러 옵션을 제공합니다.

삭제/업데이트 작업

CASCADE: 부모 테이블의 행이 삭제되면 자식 테이블의 모든 해당 행도 삭제됩니다. 이는 자식 테이블에 고아 행이 존재하지 않도록 보장합니다.
NO ACTION: 기본 작업입니다. 자식 테이블에 관련 행이 있는 경우 부모 테이블의 행 삭제를 방지합니다. 부모 테이블의 DELETE 작업이 실패합니다.
RESTRICT: NO ACTION과 유사하게, 자식 테이블에 종속 행이 있는 경우 부모 행의 삭제를 방지합니다. 본질적으로 NO ACTION과 동일하며 호환성을 위해 포함되었습니다.
SET DEFAULT: 부모 테이블의 행이 삭제되면 자식 테이블의 외래 키 컬럼이 기본값으로 설정됩니다(기본값이 있는 경우). 기본값이 없으면 DELETE 작업이 실패합니다.
SET NULL: 부모 테이블의 행이 삭제되면 자식 테이블의 외래 키 컬럼이 NULL로 설정됩니다. 이 작업은 자식 테이블의 외래 키 컬럼이 NULL 값을 허용한다고 가정합니다.

ON DELETE와 유사하게 ON UPDATE도 있으며, 참조된 컬럼이 변경(업데이트)될 때 호출됩니다. 가능한 작업은 동일하지만 SET NULL과 SET DEFAULT에는 컬럼 목록을 지정할 수 없습니다. 이 경우 CASCADE는 참조된 컬럼의 업데이트된 값이 참조하는 행에 복사되어야 함을 의미합니다. drizzle에서는 references() 두 번째 인수를 사용하여 외래 키 작업을 추가할 수 있습니다.

작업 타입

export type UpdateDeleteAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';

// second argument of references interface
actions?: {
		onUpdate?: UpdateDeleteAction;
		onDelete?: UpdateDeleteAction;
	} | undefined

posts 스키마의 author 필드에 onDelete: 'cascade'를 추가하면 user를 삭제할 때 관련된 모든 Post 레코드도 삭제됩니다.

import { pgTable, serial, text, integer } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
	id: serial('id').primaryKey(),
	name: text('name'),
});

export const posts = pgTable('posts', {
	id: serial('id').primaryKey(),
	name: text('name'),
	author: integer('author').references(() => users.id, {onDelete: 'cascade'}).notNull(),
});

foreignKey 연산자로 지정된 제약조건의 경우 외래 키 작업은 다음 구문으로 정의됩니다:

import { foreignKey, pgTable, serial, text, integer } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
	id: serial('id').primaryKey(),
	name: text('name'),
});

export const posts = pgTable('posts', {
	id: serial('id').primaryKey(),
	name: text('name'),
	author: integer('author').notNull(),
}, (table) => [
	foreignKey({
		name: "author_fk",
		columns: [table.author],
		foreignColumns: [users.id],
	})
		.onDelete('cascade')
		.onUpdate('cascade')
]);

관계 명확화

Drizzle은 동일한 두 테이블 간에 여러 관계를 정의할 때 관계를 명확하게 구분하는 방법으로 relationName 옵션을 제공합니다. 예를 들어 author와 reviewer 관계를 가진 posts 테이블을 정의하는 경우입니다.

import { pgTable, serial, text, integer } from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';
 
export const users = pgTable('users', {
	id: serial('id').primaryKey(),
	name: text('name'),
});
 
export const usersRelations = relations(users, ({ many }) => ({
	author: many(posts, { relationName: 'author' }),
	reviewer: many(posts, { relationName: 'reviewer' }),
}));
 
export const posts = pgTable('posts', {
	id: serial('id').primaryKey(),
	content: text('content'),
	authorId: integer('author_id'),
	reviewerId: integer('reviewer_id'),
});
 
export const postsRelations = relations(posts, ({ one }) => ({
	author: one(users, {
		fields: [posts.authorId],
		references: [users.id],
		relationName: 'author',
	}),
	reviewer: one(users, {
		fields: [posts.reviewerId],
		references: [users.id],
		relationName: 'reviewer',
	}),
}));