getPuri

getPuri는 Puri 쿼리 빌더를 가져오는 메서드입니다. 직접 SQL 쿼리를 작성하거나 UpsertBuilder를 사용할 때 필요합니다.

타입 시그니처

getPuri(which: DBPreset): PuriWrapper

매개변수

which

데이터베이스 프리셋을 지정합니다. 타입: DBPreset ("r" | "w")

"r": Read 전용 (복제 DB, 조회용)
"w": Write 가능 (Primary DB, 쓰기용)

// 읽기 전용
const rdb = this.getPuri("r");

// 쓰기 가능
const wdb = this.getPuri("w");

"r"과 "w"는 동일한 DB를 가리킬 수 있습니다. 설정에 따라 다릅니다.

반환값

타입: PuriWrapper Puri 쿼리 빌더 래퍼 객체를 반환합니다.

const wdb = this.getPuri("w");

// Puri 쿼리 빌더 메서드 사용
const users = await wdb.table("users").where("status", "active").select();

PuriWrapper 메서드

table / from

테이블을 지정하여 Puri 쿼리 빌더를 시작합니다.

const wdb = this.getPuri("w");

// table() 사용
const users = await wdb.table("users").where("status", "active").select();

// from() 사용 (동일)
const posts = await wdb.from("posts").where("published", true).select();

transaction

트랜잭션을 시작합니다.

const wdb = this.getPuri("w");

await wdb.transaction(async (trx) => {
  // 트랜잭션 내에서 쿼리 실행
  await trx.table("users").insert({ ... });
  await trx.table("posts").insert({ ... });

  // 모두 성공하거나 모두 실패
});

UpsertBuilder 메서드

ubRegister

UpsertBuilder에 레코드를 등록합니다.

const wdb = this.getPuri("w");

wdb.ubRegister("users", {
  email: "john@example.com",
  name: "John",
});

ubUpsert

등록된 레코드를 Upsert합니다.

await wdb.transaction(async (trx) => {
  const ids = await trx.ubUpsert("users");
  return ids;
});

ubInsertOnly

등록된 레코드를 Insert만 합니다 (UPDATE 없음).

await wdb.transaction(async (trx) => {
  const ids = await trx.ubInsertOnly("users");
  return ids;
});

ubUpdateBatch

등록된 레코드를 배치 업데이트합니다.

wdb.ubRegister("users", { id: 1, name: "Updated" });
wdb.ubRegister("users", { id: 2, name: "Updated 2" });

await wdb.ubUpdateBatch("users", {
  chunkSize: 500,
  where: "id",
});

raw

Raw SQL을 실행합니다.

const wdb = this.getPuri("w");

const result = await wdb.raw(
  `
  SELECT * FROM users WHERE status = ?
`,
  ["active"],
);

기본 사용법

직접 쿼리 작성

import { BaseModelClass } from "sonamu";

class UserModelClass extends BaseModelClass {
  async getActiveUsers() {
    const rdb = this.getPuri("r");

    const users = await rdb
      .table("users")
      .where("status", "active")
      .orderBy("created_at", "desc")
      .limit(10)
      .select();

    return users;
  }
}

복잡한 쿼리

async getUserStats() {
  const rdb = this.getPuri("r");

  const stats = await rdb.table("users")
    .leftJoin("posts", "users.id", "posts.user_id")
    .groupBy("users.id")
    .select({
      user_id: "users.id",
      user_name: "users.name",
      post_count: rdb.raw("COUNT(posts.id)")
    });

  return stats;
}

트랜잭션 사용

async transferPoints(fromUserId: number, toUserId: number, points: number) {
  const wdb = this.getPuri("w");

  await wdb.transaction(async (trx) => {
    // 포인트 차감
    await trx.table("users")
      .where("id", fromUserId)
      .decrement("points", points);

    // 포인트 증가
    await trx.table("users")
      .where("id", toUserId)
      .increment("points", points);

    // 히스토리 기록
    await trx.table("point_history").insert({
      from_user_id: fromUserId,
      to_user_id: toUserId,
      points,
      created_at: new Date()
    });
  });
}

트랜잭션 컨텍스트 자동 감지

getPuri는 트랜잭션 컨텍스트를 자동으로 감지하고 재사용합니다. 이는 @transactional 데코레이터와 함께 사용할 때 중요한 기능입니다.

동작 원리

getPuri 메서드는 내부적으로 다음과 같이 동작합니다:

DB.getTransactionContext()를 통해 현재 실행 중인 트랜잭션 확인
트랜잭션이 있으면 해당 트랜잭션을 재사용
트랜잭션이 없으면 새로운 PuriWrapper 생성

// getPuri 내부 로직 (참고용)
getPuri(which: DBPreset): PuriWrapper {
  // 1. 트랜잭션 컨텍스트에서 트랜잭션 획득 시도
  const trx = DB.getTransactionContext().getTransaction(which);

  if (trx) {
    // 2. 트랜잭션이 있으면 재사용
    return trx;
  }

  // 3. 트랜잭션이 없으면 새로운 PuriWrapper 반환
  const db = this.getDB(which);
  return new PuriWrapper(db, new UpsertBuilder());
}

@transactional 내에서 사용

import { BaseModelClass, transactional, api } from "sonamu";

class UserModelClass extends BaseModelClass {
  @api({ httpMethod: "POST" })
  @transactional()
  async createUserWithProfile(params: { email: string; name: string; bio: string }) {
    // @transactional 내에서 getPuri 호출
    const wdb = this.getPuri("w");

    // wdb는 @transactional이 생성한 트랜잭션을 자동으로 사용
    // 별도의 트랜잭션 관리 코드 불필요
    const [user] = await wdb
      .table("users")
      .insert({
        email: params.email,
        name: params.name,
      })
      .returning("*");

    await wdb.table("profiles").insert({
      user_id: user.id,
      bio: params.bio,
    });

    return user;
  }
}

중첩 메서드 호출 안전성

이 기능 덕분에 트랜잭션 내에서 다른 메서드를 호출해도 안전합니다. 모든 getPuri 호출이 동일한 트랜잭션을 사용합니다.

class UserModelClass extends BaseModelClass {
  @transactional()
  async createUser(email: string, name: string) {
    const wdb = this.getPuri("w");

    const [user] = await wdb.table("users").insert({ email, name }).returning("*");

    // 다른 메서드 호출 - 동일한 트랜잭션 사용
    await this.createDefaultProfile(user.id);

    return user;
  }

  // @transactional 없지만, 위에서 호출되면 동일한 트랜잭션 사용
  async createDefaultProfile(userId: number) {
    const wdb = this.getPuri("w");

    // createUser의 트랜잭션을 자동으로 재사용
    await wdb.table("profiles").insert({
      user_id: userId,
      bio: "Welcome!",
    });
  }
}

@transactional 데코레이터가 설정한 트랜잭션 컨텍스트는 모든 하위 메서드 호출에서 자동으로 공유됩니다. 이는 AsyncLocalStorage를 통해 구현됩니다.

트랜잭션 내에서 getPuri로 얻은 PuriWrapper와 wdb.transaction()으로 시작한 새로운 트랜잭션은 서로 다른 트랜잭션입니다. 중첩 트랜잭션이 필요한 경우 명시적으로 관리해야 합니다.

실전 예시

집계 쿼리
Raw SQL
배치 작업
복잡한 트랜잭션

import { BaseModelClass } from "sonamu";

class AnalyticsModelClass extends BaseModelClass {
  async getDailySales(startDate: Date, endDate: Date) {
    const rdb = this.getPuri("r");

    const sales = await rdb.table("orders")
      .whereBetween("created_at", [startDate, endDate])
      .groupBy(rdb.raw("DATE(created_at)"))
      .select({
        date: rdb.raw("DATE(created_at)"),
        total_orders: rdb.raw("COUNT(*)"),
        total_amount: rdb.raw("SUM(total_amount)"),
        avg_amount: rdb.raw("AVG(total_amount)")
      })
      .orderBy("date", "asc");

    return sales;
  }

  async getTopUsers(limit: number = 10) {
    const rdb = this.getPuri("r");

    const users = await rdb.table("users")
      .leftJoin("orders", "users.id", "orders.user_id")
      .groupBy("users.id")
      .select({
        user_id: "users.id",
        user_name: "users.name",
        order_count: rdb.raw("COUNT(orders.id)"),
        total_spent: rdb.raw("COALESCE(SUM(orders.total_amount), 0)")
      })
      .orderBy("total_spent", "desc")
      .limit(limit);

    return users;
  }
}

import { BaseModelClass } from "sonamu";

class ReportModelClass extends BaseModelClass {
  async getComplexReport() {
    const rdb = this.getPuri("r");

    // Raw SQL로 복잡한 쿼리
    const [result] = await rdb.raw(`
      WITH monthly_sales AS (
        SELECT
          to_char(created_at, 'YYYY-MM') as month,
          COUNT(*) as order_count,
          SUM(total_amount) as total
        FROM orders
        WHERE status = 'completed'
        GROUP BY month
      )
      SELECT
        month,
        order_count,
        total,
        LAG(total) OVER (ORDER BY month) as prev_month_total,
        (total - LAG(total) OVER (ORDER BY month)) / LAG(total) OVER (ORDER BY month) * 100 as growth_rate
      FROM monthly_sales
      ORDER BY month DESC
      LIMIT 12
    `);

    return result;
  }

  async searchFullText(keyword: string) {
    const rdb = this.getPuri("r");

    // Full-text search
    const posts = await rdb.raw(`
      SELECT
        id,
        title,
        content,
        MATCH(title, content) AGAINST(? IN BOOLEAN MODE) as relevance
      FROM posts
      WHERE MATCH(title, content) AGAINST(? IN BOOLEAN MODE)
      ORDER BY relevance DESC
      LIMIT 20
    `, [keyword, keyword]);

    return posts[0];
  }
}

import { BaseModelClass } from "sonamu";

class BatchModelClass extends BaseModelClass {
  async batchUpdateStatus(
    userIds: number[],
    status: string
  ) {
    const wdb = this.getPuri("w");

    // 500개씩 배치 처리
    const chunkSize = 500;
    let updated = 0;

    for (let i = 0; i < userIds.length; i += chunkSize) {
      const chunk = userIds.slice(i, i + chunkSize);

      const count = await wdb.table("users")
        .whereIn("id", chunk)
        .update({
          status,
          updated_at: new Date()
        });

      updated += count;
    }

    return { updated };
  }

  async batchInsert(users: Array<{ email: string; name: string }>) {
    const wdb = this.getPuri("w");

    return wdb.transaction(async (trx) => {
      // UpsertBuilder로 배치 등록
      users.forEach(user => {
        trx.ubRegister("users", {
          email: user.email,
          name: user.name,
          status: "active",
          created_at: new Date()
        });
      });

      // 한 번에 upsert
      const ids = await trx.ubUpsert("users", {
        chunkSize: 500
      });

      return { count: ids.length, ids };
    });
  }
}

import { BaseModelClass } from "sonamu";

class OrderModelClass extends BaseModelClass {
  async processOrder(orderId: number) {
    const wdb = this.getPuri("w");

    return wdb.transaction(async (trx) => {
      // 1. 주문 조회
      const [order] = await trx.table("orders")
        .where("id", orderId)
        .forUpdate()  // 락 걸기
        .select();

      if (!order) {
        throw new Error("Order not found");
      }

      // 2. 주문 항목 조회
      const items = await trx.table("order_items")
        .where("order_id", orderId)
        .select();

      // 3. 재고 확인 및 차감
      for (const item of items) {
        const [product] = await trx.table("products")
          .where("id", item.product_id)
          .forUpdate()
          .select();

        if (product.stock < item.quantity) {
          throw new Error(`Insufficient stock for ${product.name}`);
        }

        await trx.table("products")
          .where("id", item.product_id)
          .decrement("stock", item.quantity);
      }

      // 4. 주문 상태 업데이트
      await trx.table("orders")
        .where("id", orderId)
        .update({
          status: "processing",
          processed_at: new Date()
        });

      // 5. 히스토리 기록
      await trx.table("order_history").insert({
        order_id: orderId,
        status: "processing",
        created_at: new Date()
      });

      return { success: true };
    });
  }
}

getPuri vs getDB

Puri 쿼리 빌더 + UpsertBuilder를 제공합니다.

const wdb = this.getPuri("w");

// Puri 쿼리 빌더
await wdb.table("users").where("id", 1).select();

// UpsertBuilder
wdb.ubRegister("users", { ... });
await wdb.ubUpsert("users");

getDB

순수 Knex 인스턴스를 제공합니다.

const wdb = this.getDB("w");

// Knex 직접 사용
await wdb("users").where("id", 1).select();

대부분의 경우 getPuri를 사용하는 것을 권장합니다. 타입 안정성과 UpsertBuilder 기능을 제공합니다.

트랜잭션 격리 수준

const wdb = this.getPuri("w");

await wdb.transaction(
  async (trx) => {
    // 트랜잭션 작업
  },
  {
    isolation: "serializable", // 격리 수준
    readOnly: false, // 읽기 전용 여부
  },
);

격리 수준:

"read uncommitted"
"read committed" (PostgreSQL 기본)
"repeatable read"
"serializable"

타입 안정성

Puri는 완전한 타입 안정성을 제공합니다.

const wdb = this.getPuri("w");

// ✅ 타입 안전
const users = await wdb
  .table("users")
  .where("status", "active") // status 필드 자동 완성
  .select();

users[0].email; // ✅ 타입 추론됨

// ❌ 타입 에러
await wdb.table("users").where("unknown_field", "value"); // 존재하지 않는 필드

주의사항

1. 읽기/쓰기 구분

읽기 작업은 "r", 쓰기 작업은 "w"를 사용하세요.

// ✅ 올바름: 읽기는 "r"
const rdb = this.getPuri("r");
const users = await rdb.table("users").select();

// ✅ 올바름: 쓰기는 "w"
const wdb = this.getPuri("w");
await wdb.table("users").insert({ ... });

2. 트랜잭션 컨텍스트

@transactional 내에서는 트랜잭션이 자동으로 관리됩니다.

@transactional()
async method() {
  const wdb = this.getPuri("w");
  // wdb는 자동으로 트랜잭션 사용
}

3. UpsertBuilder는 트랜잭션 필수

// ❌ 에러: 트랜잭션 없음
const wdb = this.getPuri("w");
wdb.ubRegister("users", { ... });
await wdb.ubUpsert("users");  // 에러!

// ✅ 올바름: 트랜잭션 내에서
await wdb.transaction(async (trx) => {
  trx.ubRegister("users", { ... });
  await trx.ubUpsert("users");
});

성능 최적화

1. 인덱스 활용

// WHERE 조건에 인덱스 사용
const users = await rdb
  .table("users")
  .where("status", "active") // status에 인덱스 필요
  .where("created_at", ">", startDate) // created_at에 인덱스 필요
  .select();

2. SELECT 필드 제한

// ❌ 모든 필드 조회
const users = await rdb.table("users").select();

// ✅ 필요한 필드만
const users = await rdb.table("users").select("id", "email", "name");

3. 배치 처리

// 대량 데이터는 배치로 처리
for (let i = 0; i < ids.length; i += 500) {
  const chunk = ids.slice(i, i + 500);
  await wdb.table("users").whereIn("id", chunk).update({ ... });
}

다음 단계

Puri 쿼리 빌더

Puri 쿼리 작성 방법

UpsertBuilder

UpsertBuilder 사용 가이드

@transactional

트랜잭션 데코레이터

트랜잭션

수동 트랜잭션 관리

​타입 시그니처

​매개변수

​which

​반환값

​PuriWrapper 메서드

​table / from

​transaction

​UpsertBuilder 메서드

​ubRegister

​ubUpsert

​ubInsertOnly

​ubUpdateBatch

​raw

​기본 사용법

​직접 쿼리 작성

​복잡한 쿼리

​트랜잭션 사용

​트랜잭션 컨텍스트 자동 감지

​동작 원리

​@transactional 내에서 사용

​중첩 메서드 호출 안전성

​실전 예시

​getPuri vs getDB

​getPuri

​getDB

​트랜잭션 격리 수준

​타입 안정성

​주의사항

​1. 읽기/쓰기 구분

​2. 트랜잭션 컨텍스트

​3. UpsertBuilder는 트랜잭션 필수

​성능 최적화

​1. 인덱스 활용

​2. SELECT 필드 제한

​3. 배치 처리

​다음 단계

Puri 쿼리 빌더

UpsertBuilder

@transactional

트랜잭션

타입 시그니처

매개변수

which

반환값

PuriWrapper 메서드

table / from

transaction

UpsertBuilder 메서드

ubRegister

ubUpsert

ubInsertOnly

ubUpdateBatch

raw

기본 사용법

직접 쿼리 작성

복잡한 쿼리

트랜잭션 사용

트랜잭션 컨텍스트 자동 감지

동작 원리

@transactional 내에서 사용

중첩 메서드 호출 안전성

실전 예시

getPuri vs getDB

getPuri

getDB

트랜잭션 격리 수준

타입 안정성

주의사항

1. 읽기/쓰기 구분

2. 트랜잭션 컨텍스트

3. UpsertBuilder는 트랜잭션 필수

성능 최적화

1. 인덱스 활용

2. SELECT 필드 제한

3. 배치 처리

다음 단계