Drizzle 쿼리

PostgreSQL

SQLite

MySQL

SingleStore

Drizzle ORM은 SQL 위에 얇은 타입 계층으로 설계되었습니다. 우리는 TypeScript에서 SQL 데이터베이스를 운영하는 최고의 방법을 설계했다고 진심으로 믿으며, 이를 더욱 개선할 때입니다.

관계형 쿼리는 여러 조인과 복잡한 데이터 매핑을 피하면서 SQL 데이터베이스에서 중첩된 관계형 데이터를 쿼리할 수 있는 훌륭한 개발자 경험을 제공하기 위한 것입니다.

이것은 기존 스키마 정의 및 쿼리 빌더의 확장입니다. 필요에 따라 선택적으로 사용할 수 있습니다. 최고 수준의 개발자 경험과 성능을 모두 보장합니다.

index.ts

schema.ts

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

const db = drizzle({ schema });

const result = await 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 { integer, serial, text, pgTable } from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';

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

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

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

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

⚠️ 여러 파일에 SQL 스키마를 선언한 경우 다음과 같이 할 수 있습니다

index.ts

schema1.ts

schema2.ts

import * as schema1 from './schema1';
import * as schema2 from './schema2';
import { drizzle } from 'drizzle-orm/...';

const db = drizzle({ schema: { ...schema1, ...schema2 } });

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

// schema declaration in the first file

// schema declaration in the second file

모드

Drizzle 관계형 쿼리는 항상 데이터베이스에서 실행할 정확히 하나의 SQL 문을 생성하며, 몇 가지 주의사항이 있습니다. 모든 데이터베이스에 대한 최고 수준의 지원을 제공하기 위해 **모드**를 도입했습니다.

Drizzle 관계형 쿼리는 내부적으로 하위 쿼리의 측면 조인(lateral joins)을 사용하며, 현재 PlanetScale은 이를 지원하지 않습니다.

일반 MySQL 데이터베이스와 함께 mysql2 드라이버를 사용하는 경우 — mode: "default"를 지정해야 합니다 PlanetScale과 함께 mysql2 드라이버를 사용하는 경우 — mode: "planetscale"을 지정해야 합니다

import * as schema from './schema';
import { drizzle } from "drizzle-orm/mysql2";
import mysql from "mysql2/promise";

const connection = await mysql.createConnection({
  uri: process.env.PLANETSCALE_DATABASE_URL,
});

const db = drizzle({ client: connection, schema, mode: 'planetscale' });

쿼리하기

관계형 쿼리는 Drizzle의 원래 **쿼리 빌더**의 확장입니다. 스키마 파일에서 모든 tables와 relations를 drizzle() 초기화 시 제공하고 db.query API를 사용하면 됩니다.

drizzle 임포트 경로는 사용 중인 **데이터베이스 드라이버**에 따라 다릅니다.

index.ts

schema.ts

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

const db = drizzle({ schema });

await db.query.users.findMany(...);

// if you have schema in multiple files
import * as schema1 from './schema1';
import * as schema2 from './schema2';
import { drizzle } from 'drizzle-orm/...';

const db = drizzle({ schema: { ...schema1, ...schema2 } });

await db.query.users.findMany(...);

	import { type AnyPgColumn, boolean, integer, pgTable, primaryKey, serial, text, timestamp } from 'drizzle-orm/pg-core';

	import { relations } from 'drizzle-orm';

	export const users = pgTable('users', {
		id: serial('id').primaryKey(),
		name: text('name').notNull(),
		verified: boolean('verified').notNull(),
		invitedBy: integer('invited_by').references((): AnyPgColumn => users.id),
	});

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

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

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

	export const usersToGroups = pgTable('users_to_groups', {
		id: serial('id').primaryKey(),
		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] }),
	}));

	export const posts = pgTable('posts', {
		id: serial('id').primaryKey(),
		content: text('content').notNull(),
		authorId: integer('author_id').references(() => users.id),
		createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
	});

	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(),
		content: text('content').notNull(),
		creator: integer('creator').references(() => users.id),
		postId: integer('post_id').references(() => posts.id),
		createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
	});

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

	export const commentLikes = pgTable('comment_likes', {
		id: serial('id').primaryKey(),
		creator: integer('creator').references(() => users.id),
		commentId: integer('comment_id').references(() => comments.id),
		createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
	});

	export const commentLikesRelations = relations(commentLikes, ({ one }) => ({
		comment: one(comments, { fields: [commentLikes.commentId], references: [comments.id] }),
		author: one(users, { fields: [commentLikes.creator], references: [users.id] }),
	}));

Drizzle는 .findMany() 및 .findFirst() API를 제공합니다.

여러 개 찾기

const users = await db.query.users.findMany();

// result type
const result: {
	id: number;
	name: string;
	verified: boolean;
	invitedBy: number | null;
}[];

첫 번째 찾기

.findFirst()는 쿼리에 limit 1을 추가합니다.

const user = await db.query.users.findFirst();

// result type
const result: {
	id: number;
	name: string;
	verified: boolean;
	invitedBy: number | null;
};

관계 포함하기

With 연산자를 사용하면 여러 관련 테이블의 데이터를 결합하고 결과를 적절히 집계할 수 있습니다.

댓글과 함께 모든 게시물 가져오기:

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

댓글과 함께 첫 번째 게시물 가져오기:

const post = await db.query.posts.findFirst({
	with: {
		comments: true,
	},
});

필요한 만큼 중첩된 with 문을 연결할 수 있습니다. 중첩된 with 쿼리의 경우 Drizzle은 Core Type API를 사용하여 타입을 추론합니다.

게시물과 함께 모든 사용자 가져오기. 각 게시물에는 댓글 목록이 포함되어야 합니다:

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

부분 필드 선택

columns 매개변수를 사용하면 데이터베이스에서 가져올 컬럼을 포함하거나 생략할 수 있습니다.

Drizzle은 쿼리 수준에서 부분 선택을 수행하므로 데이터베이스에서 추가 데이터가 전송되지 않습니다.

Drizzle은 단일 SQL 문을 출력한다는 점을 기억하세요.

id, content만 포함하고 comments도 포함하는 모든 게시물 가져오기:

const posts = await db.query.posts.findMany({
	columns: {
		id: true,
		content: true,
	},
	with: {
		comments: true,
	}
});

content 없이 모든 게시물 가져오기:

const posts = await db.query.posts.findMany({
	columns: {
		content: false,
	},
});

true와 false 선택 옵션이 모두 있는 경우 모든 false 옵션은 무시됩니다.

name 필드를 포함하고 id 필드를 제외하면 id 제외는 중복됩니다. 어차피 name을 제외한 모든 필드가 제외됩니다.

동일한 쿼리에서 필드 제외 및 포함:

const users = await db.query.users.findMany({
	columns: {
		name: true,
		id: false //ignored
	},
});

// result type
const users: {
	name: string;
};

중첩된 관계의 컬럼만 포함:

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

// result type
const res: {
	posts: {
		id: number,
		text: string
	}
}[];

중첩된 부분 필드 선택

**부분 선택**과 마찬가지로 중첩된 관계의 컬럼을 포함하거나 제외할 수 있습니다:

const posts = await db.query.posts.findMany({
	columns: {
		id: true,
		content: true,
	},
	with: {
		comments: {
			columns: {
				authorId: false
			}
		}
	}
});

선택 필터

SQL과 유사한 쿼리 빌더와 마찬가지로, 관계형 쿼리 API를 사용하면 연산자 목록으로 필터와 조건을 정의할 수 있습니다.

drizzle-orm에서 가져오거나 콜백 구문을 사용할 수 있습니다:

import { eq } from 'drizzle-orm';

const users = await db.query.users.findMany({
	where: eq(users.id, 1)
})

const users = await db.query.users.findMany({
	where: (users, { eq }) => eq(users.id, 1),
})

특정 날짜 이전에 생성된 댓글과 함께 id=1인 게시물 찾기:

await db.query.posts.findMany({
	where: (posts, { eq }) => (eq(posts.id, 1)),
	with: {
		comments: {
			where: (comments, { lt }) => lt(comments.createdAt, new Date()),
		},
	},
});

Limit 및 Offset

Drizzle ORM은 쿼리 및 중첩된 엔티티에 대한 limit 및 offset API를 제공합니다.

5개의 게시물 찾기:

await db.query.posts.findMany({
	limit: 5,
});

게시물을 찾고 최대 3개의 댓글 가져오기:

await db.query.posts.findMany({
	with: {
		comments: {
			limit: 3,
		},
	},
});

IMPORTANT

offset은 최상위 쿼리에서만 사용할 수 있습니다.

await db.query.posts.findMany({
	limit: 5,
	offset: 2, // correct ✅
	with: {
		comments: {
			offset: 3, // incorrect ❌
			limit: 3,
		},
	},
});

5번째부터 10번째 게시물까지의 댓글과 함께 게시물 찾기:

await db.query.posts.findMany({
	limit: 5,
  offset: 5,
	with: {
		comments: true,
	},
});

Order By (정렬)

Drizzle은 관계형 쿼리 빌더에서 정렬을 위한 API를 제공합니다.

동일한 정렬 **core API**를 사용하거나 임포트 없이 콜백에서 order by 연산자를 사용할 수 있습니다.

import { desc, asc } from 'drizzle-orm';

await db.query.posts.findMany({
	orderBy: [asc(posts.id)],
});

await db.query.posts.findMany({
	orderBy: (posts, { asc }) => [asc(posts.id)],
});

asc + desc로 정렬:

await db.query.posts.findMany({
	orderBy: (posts, { asc }) => [asc(posts.id)],
	with: {
		comments: {
			orderBy: (comments, { desc }) => [desc(comments.id)],
		},
	},
});

커스텀 필드 포함

관계형 쿼리 API를 사용하면 커스텀 추가 필드를 추가할 수 있습니다. 데이터를 검색하고 추가 함수를 적용해야 할 때 유용합니다.

IMPORTANT

현재 extras에서는 집계가 지원되지 않습니다. 이를 위해서는 **core queries**를 사용하세요.

import { sql } from 'drizzle-orm';

await db.query.users.findMany({
	extras: {
		loweredName: sql`lower(${users.name})`.as('lowered_name'),
	},
})

await db.query.users.findMany({
	extras: {
		loweredName: (users, { sql }) => sql`lower(${users.name})`.as('lowered_name'),
	},
})

키로서 lowerName은 반환된 객체의 모든 필드에 포함됩니다.

IMPORTANT

.as("<name_for_column>")를 명시적으로 지정해야 합니다

그룹과 함께 모든 사용자를 검색하되 fullName 필드(firstName과 lastName의 연결)를 포함하려면, Drizzle 관계형 쿼리 빌더를 사용하여 다음 쿼리를 사용할 수 있습니다.

const res = await db.query.users.findMany({
	extras: {
		fullName: sql<string>`concat(${users.name}, " ", ${users.name})`.as('full_name'),
	},
	with: {
		usersToGroups: {
			with: {
				group: true,
			},
		},
	},
});

// result type
const res: {
	id: number;
	name: string;
	verified: boolean;
	invitedBy: number | null;
	fullName: string;
	usersToGroups: {
			group: {
					id: number;
					name: string;
					description: string | null;
			};
	}[];
}[];

댓글과 함께 모든 게시물을 검색하고 게시물 내용의 크기와 각 댓글 내용의 크기를 계산하는 추가 필드를 추가하려면:

const res = await db.query.posts.findMany({
	extras: (table, { sql }) => ({
		contentLength: (sql<number>`length(${table.content})`).as('content_length'),
	}),
	with: {
		comments: {
			extras: {
				commentSize: sql<number>`length(${comments.content})`.as('comment_size'),
			},
		},
	},
});

// result type
const res: {
	id: number;
	createdAt: Date;
	content: string;
	authorId: number | null;
	contentLength: number;
	comments: {
			id: number;
			createdAt: Date;
			content: string;
			creator: number | null;
			postId: number | null;
			commentSize: number;
	}[];
};

준비된 문(Prepared statements)

준비된 문은 쿼리 성능을 대폭 향상시키도록 설계되었습니다 — 여기를 참조하세요.

이 섹션에서는 Drizzle 관계형 쿼리 빌더를 사용하여 플레이스홀더를 정의하고 준비된 문을 실행하는 방법을 배울 수 있습니다.

`where`의 플레이스홀더

PostgreSQL

MySQL

SQLite

const prepared = db.query.users.findMany({
	where: ((users, { eq }) => eq(users.id, placeholder('id'))),
	with: {
		posts: {
			where: ((users, { eq }) => eq(users.id, placeholder('pid'))),
		},
	},
}).prepare('query_name');

const usersWithPosts = await prepared.execute({ id: 1 });

const prepared = db.query.users.findMany({
	where: ((users, { eq }) => eq(users.id, placeholder('id'))),
	with: {
		posts: {
			where: ((users, { eq }) => eq(users.id, placeholder('pid'))),
		},
	},
}).prepare();

const usersWithPosts = await prepared.execute({ id: 1 });

const prepared = db.query.users.findMany({
	where: ((users, { eq }) => eq(users.id, placeholder('id'))),
	with: {
		posts: {
			where: ((users, { eq }) => eq(users.id, placeholder('pid'))),
		},
	},
}).prepare();

const usersWithPosts = await prepared.execute({ id: 1 });

`limit`의 플레이스홀더

PostgreSQL

MySQL

SQLite

const prepared = db.query.users.findMany({
	with: {
		posts: {
			limit: placeholder('limit'),
		},
	},
}).prepare('query_name');

const usersWithPosts = await prepared.execute({ limit: 1 });

`offset`의 플레이스홀더

PostgreSQL

MySQL

SQLite

const prepared = db.query.users.findMany({
	offset: placeholder('offset'),
	with: {
		posts: true,
	},
}).prepare('query_name');

const usersWithPosts = await prepared.execute({ offset: 1 });

여러 플레이스홀더

PostgreSQL

MySQL

SQLite

const prepared = db.query.users.findMany({
	limit: placeholder('uLimit'),
	offset: placeholder('uOffset'),
	where: ((users, { eq, or }) => or(eq(users.id, placeholder('id')), eq(users.id, 3))),
	with: {
		posts: {
			where: ((users, { eq }) => eq(users.id, placeholder('pid'))),
			limit: placeholder('pLimit'),
		},
	},
}).prepare('query_name');

const usersWithPosts = await prepared.execute({ pLimit: 1, uLimit: 3, uOffset: 1, id: 2, pid: 6 });

const prepared = db.query.users.findMany({
	limit: placeholder('uLimit'),
	offset: placeholder('uOffset'),
	where: ((users, { eq, or }) => or(eq(users.id, placeholder('id')), eq(users.id, 3))),
	with: {
		posts: {
			where: ((users, { eq }) => eq(users.id, placeholder('pid'))),
			limit: placeholder('pLimit'),
		},
	},
}).prepare();

const usersWithPosts = await prepared.execute({ pLimit: 1, uLimit: 3, uOffset: 1, id: 2, pid: 6 });

const prepared = db.query.users.findMany({
	limit: placeholder('uLimit'),
	offset: placeholder('uOffset'),
	where: ((users, { eq, or }) => or(eq(users.id, placeholder('id')), eq(users.id, 3))),
	with: {
		posts: {
			where: ((users, { eq }) => eq(users.id, placeholder('pid'))),
			limit: placeholder('pLimit'),
		},
	},
}).prepare();

const usersWithPosts = await prepared.execute({ pLimit: 1, uLimit: 3, uOffset: 1, id: 2, pid: 6 });

Drizzle 쿼리

모드

쿼리하기

여러 개 찾기

첫 번째 찾기

관계 포함하기

부분 필드 선택

중첩된 부분 필드 선택

선택 필터

Limit 및 Offset

Order By (정렬)

커스텀 필드 포함

준비된 문(Prepared statements)

where의 플레이스홀더

limit의 플레이스홀더

offset의 플레이스홀더

여러 플레이스홀더

`where`의 플레이스홀더

`limit`의 플레이스홀더

`offset`의 플레이스홀더