데이터베이스

Puri 쿼리 빌더

Puri는 Promise를 직접 구현하나요?

네, Puri는 Promise 인터페이스를 직접 구현합니다.

// puri.ts 내부 구현
export class Puri<TSchema, TTables, TResult> implements Promise<TResult[]> {
  then<TResult1 = TResult[], TResult2 = never>(
    onfulfilled?: ((value: TResult[]) => TResult1 | PromiseLike<TResult1>) | null,
    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
  ): Promise<TResult1 | TResult2> {
    return this.knexQuery.then(onfulfilled, onrejected);
  }

  catch<TResult2 = never>(...): Promise<TResult[] | TResult2> { }
  finally(onfinally?: (() => void) | null): Promise<TResult[]> { }
}

사용 방법:

// ✅ await를 직접 사용 (배열 반환)
const users = await UserModel.getPuri("r").table("users").select("id", "name");

// ✅ .first()로 단일 객체 조회
const user = await UserModel.getPuri("r").table("users").select("id", "name").where({ id: 1 }).first();

// ✅ Puri.count()로 카운트
const result = await UserModel.getPuri("r")
  .table("users")
  .select({ count: Puri.count() })
  .where({ status: "active" });
const count = result[0].count;

주의:

.getMany(), .getOne(), .getScalar() 같은 메서드는 존재하지 않습니다
항상 배열을 반환합니다 (Expand<TResult>[])
단일 객체는 .first() 사용

Puri에서 집계 함수를 사용하려면?

Puri.count(), Puri.sum(), Puri.avg() 등의 static 메서드를 사용합니다.

// COUNT
const result = await UserModel.getPuri("r")
  .table("users")
  .select({ count: Puri.count() })
  .where({ status: "active" });
const count = result[0].count;

// SUM
const result = await OrderModel.getPuri("r")
  .table("orders")
  .select({ total: Puri.sum("amount") })
  .where({ status: "completed" });
const total = result[0].total;

// AVG
const result = await ProductModel.getPuri("r")
  .table("products")
  .select({ avg_price: Puri.avg("price") });
const avgPrice = result[0].avg_price;

// COUNT + GROUP BY
const stats = await OrderModel.getPuri("r")
  .table("orders")
  .select("user_id", { count: Puri.count(), total: Puri.sum("amount") })
  .groupBy("user_id");

Puri에서 JOIN을 사용하려면?

INNER JOIN:

const ordersWithUser = await OrderModel.getPuri("r")
  .table("orders")
  .select("orders.id", "orders.total", "users.name")
  .join("users", "users.id", "orders.user_id");

LEFT JOIN:

const usersWithOrders = await UserModel.getPuri("r")
  .table("users")
  .select("users.id", "users.name", "orders.total")
  .leftJoin("orders", "orders.user_id", "users.id");

복잡한 JOIN 조건 (콜백 방식):

const result = await UserModel.getPuri("r")
  .table("users")
  .select("users.*", "orders.total")
  .leftJoin("orders", (j) => {
    j.on("orders.user_id", "users.id").on("orders.status", "=", "completed");
  });

Puri에서 서브쿼리를 사용하려면?

WHERE IN 서브쿼리:

const activeUserIds = UserModel.getPuri("r").table("users").select("id").where({ status: "active" });

const orders = await OrderModel.getPuri("r").table("orders").select("*").whereIn("user_id", activeUserIds);

FROM 서브쿼리:

const subquery = UserModel.getPuri("r")
  .table("users")
  .select("user_id", { count: Puri.count() })
  .groupBy("user_id");

const result = await new Puri(knex, { sq: subquery })
  .select("sq.user_id", "sq.count")
  .where("sq.count", ">", 10);

마이그레이션

마이그레이션을 생성하고 실행하려면?

1. Entity 수정Sonamu UI에서 Entity 편집2. 마이그레이션 생성

# Sonamu UI의 DB Migration 탭
# → Prepared Migration Codes 확인
# → Generate 클릭

또는 CLI:

pnpm sonamu migrate status
# → 생성 필요한 마이그레이션 확인

3. 마이그레이션 실행

# 개발 환경
pnpm sonamu migrate run

# 프로덕션
NODE_ENV=production pnpm sonamu migrate run

# 롤백
pnpm sonamu migrate rollback

마이그레이션을 안전하게 테스트하려면?

Shadow DB를 사용하여 테스트합니다:

# Shadow DB 테스트
pnpm sonamu migrate shadow-test
# → 임시 Shadow DB 생성
# → Migration 적용
# → 성공 확인
# → Shadow DB 삭제

Shadow DB 설정:

// sonamu.config.ts
export default {
  database: {
    connections: {
      main: {
        // ...
      },
      shadow: {
        host: "localhost",
        port: 5432,
        database: "myapp_shadow",
        user: "postgres",
        password: "password",
      },
    },
  },
} satisfies SonamuConfig;

컬럼 타입을 변경할 때 기존 데이터를 안전하게 마이그레이션하려면?

임시 컬럼을 활용하여 데이터를 변환한 후 원본 컬럼을 교체합니다.예시: string → integer 변환

// migrations/20250115_change_status_type.ts
import type { Knex } from "knex";

export async function up(knex: Knex): Promise<void> {
  await knex.schema.alterTable("products", (table) => {
    // 1. 임시 컬럼 생성 (새 타입)
    table.integer("status_new");
  });

  // 2. 데이터 변환
  await knex.raw(`
    UPDATE products 
    SET status_new = CASE 
      WHEN status = 'active' THEN 1
      WHEN status = 'inactive' THEN 2
      WHEN status = 'pending' THEN 3
      ELSE 0
    END
  `);

  // 3. 기존 컬럼 삭제
  await knex.schema.alterTable("products", (table) => {
    table.dropColumn("status");
  });

  // 4. 새 컬럼 이름 변경
  await knex.schema.alterTable("products", (table) => {
    table.renameColumn("status_new", "status");
  });

  // 5. NOT NULL 제약 추가 (선택사항)
  await knex.schema.alterTable("products", (table) => {
    table.integer("status").notNullable().alter();
  });
}

export async function down(knex: Knex): Promise<void> {
  // 롤백: 역순으로 복원
  await knex.schema.alterTable("products", (table) => {
    table.string("status_old", 20);
  });

  await knex.raw(`
    UPDATE products 
    SET status_old = CASE 
      WHEN status = 1 THEN 'active'
      WHEN status = 2 THEN 'inactive'
      WHEN status = 3 THEN 'pending'
      ELSE 'unknown'
    END
  `);

  await knex.schema.alterTable("products", (table) => {
    table.dropColumn("status");
    table.renameColumn("status_old", "status");
  });
}

컬럼명을 변경할 때 데이터를 보존하려면?

Entity 자동 생성 시 DROP/ADD로 생성되므로 수동으로 RENAME 사용:

// Entity 변경 후 자동 생성된 Migration 파일 수정
export async function up(knex: Knex): Promise<void> {
  await knex.schema.alterTable("users", (table) => {
    // ❌ table.dropColumn("old_name");
    // ❌ table.string("new_name");

    // ✅ RENAME 사용 (데이터 보존)
    table.renameColumn("old_name", "new_name");
  });
}

export async function down(knex: Knex): Promise<void> {
  await knex.schema.alterTable("users", (table) => {
    table.renameColumn("new_name", "old_name");
  });
}

FK 제약조건이 있는 컬럼을 변경하려면?

FK 제약을 삭제한 후 컬럼 변경, 다시 FK 재생성:

export async function up(knex: Knex): Promise<void> {
  await knex.schema.alterTable("orders", (table) => {
    // 1. FK 제약 삭제
    table.dropForeign(["user_id"]);
  });

  // 2. 컬럼 타입 변경
  await knex.raw(`
    ALTER TABLE orders 
    ALTER COLUMN user_id TYPE BIGINT USING user_id::BIGINT
  `);

  await knex.schema.alterTable("orders", (table) => {
    // 3. FK 제약 재생성
    table
      .foreign("user_id")
      .references("id")
      .inTable("users")
      .onDelete("CASCADE")
      .onUpdate("CASCADE");
  });
}

export async function down(knex: Knex): Promise<void> {
  await knex.schema.alterTable("orders", (table) => {
    table.dropForeign(["user_id"]);
  });

  await knex.raw(`
    ALTER TABLE orders 
    ALTER COLUMN user_id TYPE INTEGER USING user_id::INTEGER
  `);

  await knex.schema.alterTable("orders", (table) => {
    table.foreign("user_id").references("id").inTable("users");
  });
}

PostgreSQL 특화

PostgreSQL의 JSONB 연산자를 Puri에서 사용하려면?

JSONB 포함 연산자 @>에는 타입 안전한 .whereJsonSupersetOf()를 사용합니다. 그 외 JSONB 연산자는 Puri.rawString()과 파라미터가 바인딩된 .whereRaw()를 사용합니다.JSONB 속성 조회 (->>, ->):

// metadata->>'brand' = 'Samsung'
const products = await ProductModel.getPuri("r")
  .table("products")
  .select({
    id: "products.id",
    name: "products.name",
    brand: Puri.rawString("products.metadata->>'brand'"),
    tags: Puri.rawStringArray("products.metadata->'tags'"),
  })
  .whereRaw("products.metadata->>'brand' = ?", ["Samsung"]);

JSONB 포함 연산자 (@>):

// metadata @> '{"warranty": 2}'
const productsWithWarranty = await ProductModel.getPuri("r")
  .table("products")
  .select({
    id: "products.id",
    name: "products.name",
  })
  .whereJsonSupersetOf("products.metadata", { warranty: 2 });

값은 내부에서 직렬화되고 바인딩되므로 JSON.stringify()를 직접 호출하지 않습니다. 괄호 안에서 OR 조건이 필요하면 whereGroup()의 orWhereJsonSupersetOf()를 사용합니다.JSONB 키 존재 여부 (?):

// metadata ? 'discount'
const productsWithDiscount = await ProductModel.getPuri("r")
  .table("products")
  .select("*")
  .whereRaw("products.metadata ?? 'discount'"); // ? 대신 ?? 사용

중첩 JSONB 속성:

// metadata->'specs'->>'cpu'
const laptops = await ProductModel.getPuri("r")
  .table("products")
  .select({
    id: "products.id",
    name: "products.name",
    cpu: Puri.rawString("products.metadata->'specs'->>'cpu'"),
    ram: Puri.rawString("products.metadata->'specs'->>'ram'"),
  })
  .whereRaw("products.metadata->'specs'->>'cpu' LIKE ?", ["%Intel%"]);

주의사항:

->> 는 텍스트 반환, -> 는 JSONB 반환
SQL Injection 방지를 위해 파라미터 바인딩 사용
GIN 인덱스 생성 권장: CREATE INDEX ON products USING gin(metadata);

PostgreSQL의 Full-Text Search를 사용하려면?

ts_vector 컬럼 생성:

// Entity 정의
{
  "name": "search_vector",
  "type": "customType",
  "id": "TsVectorType",
  "nullable": true
}

검색 쿼리:

const posts = await PostModel.getPuri("r")
  .table("posts")
  .select("*")
  .whereTsSearch("search_vector", "typescript database", {
    parser: "websearch_to_tsquery",
    config: "simple",
  });

하이라이팅:

const posts = await PostModel.getPuri("r")
  .table("posts")
  .select({
    id: "posts.id",
    title: Puri.tsHighlight("posts.title", "typescript"),
    content: Puri.tsHighlight("posts.content", "typescript", {
      startSel: "<mark>",
      stopSel: "</mark>",
      maxFragments: 3,
    }),
  })
  .whereTsSearch("search_vector", "typescript");

트랜잭션

트랜잭션을 사용하려면?

방법 1: 수동 트랜잭션 (getPuri("w").transaction())

class UserModel extends BaseModelClass {
  async createWithProfile(data: { name: string; bio: string }) {
    const wdb = this.getPuri("w");

    return wdb.transaction(async (trx) => {
      trx.ubRegister("users", { name: data.name });
      const [userId] = await trx.ubUpsert("users");

      trx.ubRegister("profiles", { user_id: userId, bio: data.bio });
      await trx.ubUpsert("profiles");

      return userId;
    });
  }
}

방법 2: @transactional() 데코레이터

import { transactional } from "sonamu";

class UserModel extends BaseModelClass {
  @transactional()
  async createWithProfile(data: { name: string; bio: string }) {
    // 메서드 본문 전체가 자동으로 트랜잭션 안에서 실행됩니다.
    const [userId] = await UserModel.save([{ name: data.name }]);
    await ProfileModel.save([{ user_id: userId, bio: data.bio }]);
    return userId;
  }
}

에러 발생 시 자동 롤백됩니다. 더 자세한 내용은 수동 트랜잭션 및 @transactional 데코레이터 문서를 참고하세요.

시작하기

핵심 개념

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

데이터베이스

Puri 쿼리 빌더

마이그레이션

PostgreSQL 특화

트랜잭션

관련 문서

​Puri 쿼리 빌더

​마이그레이션

​PostgreSQL 특화

​트랜잭션

​관련 문서

Puri 쿼리 빌더

마이그레이션

PostgreSQL 특화

트랜잭션

관련 문서