동적 쿼리 빌딩

Drizzle의 모든 쿼리 빌더는 기본적으로 SQL에 최대한 맞추려고 하기 때문에, 대부분의 메서드는 한 번만 호출할 수 있습니다. 예를 들어, SELECT 문에서는 WHERE 절이 하나만 있을 수 있으므로 .where() 메서드는 한 번만 호출할 수 있습니다:

const query = db
    .select()
    .from(users)
    .where(eq(users.id, 1))
    .where(eq(users.name, 'John')); // ❌ 타입 에러 - where()은 한 번만 호출할 수 있음

이전 ORM 버전에서는 이러한 제한이 구현되지 않았기 때문에, 많은 사용자들이 여러 .where() 호출을 하나의 조건으로 “병합”할 것으로 기대하며 혼란을 겪었습니다.

이러한 동작은 일반적인 쿼리 빌딩, 즉 전체 쿼리를 한 번에 생성할 때 유용합니다. 하지만 쿼리를 동적으로 빌드하려는 경우, 예를 들어 쿼리 빌더를 받아서 추가 기능을 제공하는 공유 함수를 사용할 때 문제가 됩니다. 이 문제를 해결하기 위해 Drizzle은 쿼리 빌더에 특별한 ‘동적’ 모드를 제공하며, 이 모드에서는 메서드를 여러 번 호출할 수 있습니다. 이 모드를 활성화하려면 쿼리 빌더에서 .$dynamic()을 호출해야 합니다.

페이지 번호와 선택적인 페이지 크기를 기반으로 쿼리에 LIMIT과 OFFSET 절을 추가하는 간단한 withPagination 함수를 구현해 보겠습니다:

function withPagination(
    qb: T,
    page: number = 1,
    pageSize: number = 10,
) {
    return qb.limit(pageSize).offset((page - 1) * pageSize);
}

const query = db.select().from(users).where(eq(users.id, 1));
withPagination(query, 1); // ❌ 타입 에러 - 쿼리 빌더가 동적 모드가 아님

const dynamicQuery = query.$dynamic();
withPagination(dynamicQuery, 1); // ✅ 정상 동작

withPagination 함수는 제네릭 함수이기 때문에, 쿼리 빌더의 결과 타입을 수정할 수 있습니다. 예를 들어 조인을 추가할 수 있습니다:

function withFriends(qb: T) {
    return qb.leftJoin(friends, eq(friends.userId, users.id));
}

let query = db.select().from(users).where(eq(users.id, 1)).$dynamic();
query = withFriends(query);

이는 PgSelect와 같은 타입들이 동적 쿼리 빌딩을 위해 특별히 설계되었기 때문에 가능합니다. 이러한 타입들은 동적 모드에서만 사용할 수 있습니다.

다음은 동적 쿼리 빌딩에서 제네릭 매개변수로 사용할 수 있는 모든 타입 목록입니다:

import { QueryBuilder } from 'drizzle-orm/pg-core';

function withFriends(qb: T) {
    return qb.leftJoin(friends, eq(friends.userId, users.id));
}

const qb = new QueryBuilder();
let query = qb.select().from(users).where(eq(users.id, 1)).$dynamic();
query = withFriends(query);