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()
    });
  });
}

트랜잭션 연동

요청한 preset에 이미 활성 트랜잭션이 있으면 getPuri는 해당 DB 트랜잭션에 참여합니다. 활성 트랜잭션이 없으면 preset에 설정된 DB에 접근합니다.

@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;
  }
}

중첩 메서드 호출 안전성

트랜잭션 안에서 호출한 메서드가 같은 preset을 요청하면 동일한 DB 트랜잭션에 참여합니다.

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 안에서 같은 dbPreset으로 호출한 getPuri는 동일한 DB 트랜잭션에 참여합니다. 가장 바깥 데코레이터 호출이 커밋과 롤백을 담당합니다.

같은 dbPreset의 트랜잭션이 이미 활성 상태라면 중첩 .transaction()은 Savepoint를 생성합니다. 중첩 호출은 하나씩 순차적으로 await하고 sibling Savepoint를 Promise.all로 병렬 실행하지 마세요. 설정된 DB마다 고유한 dbPreset을 일관되게 사용하고, 서로 다른 DB 연결에 같은 preset 이름을 재사용하지 마세요. 이 부분 롤백 안내는 직접 DB 쿼리에 적용됩니다. 하나의 UpsertBuilder batch나 graph를 공유한다면 실패를 잡고 계속하지 말고 가장 바깥 트랜잭션까지 전파해 전체 작업을 롤백하세요.

실전 예시

집계 쿼리
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 내에서는 트랜잭션이 자동으로 관리됩니다.

@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. @transactional 내에서 사용

​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. @transactional 내에서 사용

3. UpsertBuilder는 트랜잭션 필수

성능 최적화

1. 인덱스 활용

2. SELECT 필드 제한

3. 배치 처리

다음 단계