기본 쿼리 - 🌲 Sonamu

Puri는 TypeScript로 안전하게 SQL 쿼리를 작성할 수 있는 타입 안전한 쿼리 빌더입니다. 이 문서는 SELECT, INSERT, UPDATE, DELETE의 기본 사용법을 설명합니다.

쿼리 시작하기

SELECT

데이터 조회하기 select, selectAll, first

INSERT

데이터 추가하기 insert, upsert, returning

UPDATE

데이터 수정하기 update, increment, decrement

DELETE

데이터 삭제하기 delete

SELECT - 데이터 조회

기본 SELECT

const users = await db.table("users").select({
  id: "id",
  name: "username",
  email: "email",
});
// 결과: { id: number; name: string; email: string; }[]

const users = await db.table("users").selectAll();
// 결과: User[]

const user = await db.table("users").select({ id: "id", name: "username" }).where("id", 1).first();
// 결과: { id: number; name: string; } | undefined

select 메서드는 객체 형태로 컬럼을 선택합니다. 키는 결과 필드명, 값은 실제 테이블 컬럼명입니다.

컬럼 별칭(Alias)

const posts = await db.table("posts").select({
  postId: "id", // 별칭 사용
  postTitle: "title",
  authorName: "author_name", // snake_case → camelCase
  createdDate: "created_at",
});

// 결과 타입이 자동으로 추론됨
const firstPost = posts[0];
console.log(firstPost.postId); // number
console.log(firstPost.postTitle); // string

appendSelect - 컬럼 추가

이미 선택한 컬럼에 추가로 컬럼을 선택할 수 있습니다.

const query = db.table("users").select({
  id: "id",
  name: "username",
});

const users = await query.appendSelect({
  email: "email",
  role: "role",
});

// 결과: { id, name, email, role }

WHERE - 조건 필터링

기본 WHERE

const users = await db
  .table("users")
  .select({ id: "id", name: "username" })
  .where("role", "admin");

const users = await db.table("users").select({ id: "id", age: "age" }).where("age", ">=", 18);
// 지원: =, !=, <, <=, >, >=

const users = await db.table("users").select({ id: "id" }).where("deleted_at", "!=", null);

복수 조건 (AND)

const users = await db
  .table("users")
  .select({ id: "id", name: "username" })
  .where("role", "admin")
  .where("is_active", true)
  .where("age", ">=", 18);

// SQL: WHERE role = 'admin' AND is_active = true AND age >= 18

OR 조건

const users = await db
  .table("users")
  .select({ id: "id", name: "username" })
  .where("role", "admin")
  .orWhere("role", "moderator");

// SQL: WHERE role = 'admin' OR role = 'moderator'

orWhere는 단순 OR 조건입니다. 복잡한 조건 그룹은 whereGroup을 사용하세요. 자세한 내용은 Advanced Patterns 참고

IN / NOT IN

const users = await db
  .table("users")
  .select({ id: "id" })
  .whereIn("role", ["admin", "moderator"]);

const users = await db
  .table("users")
  .select({ id: "id" })
  .whereNotIn("status", ["deleted", "banned"]);

LIKE 검색

const users = await db
  .table("users")
  .select({ id: "id", name: "username" })
  .where("username", "like", "%john%");

// SQL: WHERE username LIKE '%john%'

INSERT - 데이터 추가

단일 레코드 추가

const result = await db.table("users").insert({
  username: "john",
  email: "john@example.com",
  password: "hashed_password",
  role: "normal",
});

// result: number (삽입된 레코드 수)

RETURNING으로 삽입된 데이터 받기

const inserted = await db
  .table("users")
  .insert({
    username: "john",
    email: "john@example.com",
    password: "hashed_password",
    role: "normal",
  })
  .returning(["id", "username"]);

console.log(inserted);
// [{ id: 1, username: "john" }]

여러 레코드 추가

const result = await db.table("users").insert([
  {
    username: "john",
    email: "john@example.com",
    password: "hash1",
    role: "normal",
  },
  {
    username: "jane",
    email: "jane@example.com",
    password: "hash2",
    role: "normal",
  },
]);

UPDATE - 데이터 수정

기본 UPDATE

const count = await db.table("users").where("id", 1).update({
  username: "updated_name",
  updated_at: new Date(),
});

console.log(`${count} rows updated`);

WHERE 절 필수: UPDATE는 반드시 WHERE 조건과 함께 사용해야 합니다. 조건 없이 전체 데이터를 수정하면 에러가 발생할 수 있습니다.

increment / decrement

숫자 컬럼을 증가/감소시킬 수 있습니다.

await db
  .table("posts")
  .where("id", 1)
  .increment("view_count", 1);

// SQL: UPDATE posts SET view_count = view_count + 1 WHERE id = 1

await db
  .table("users")
  .where("id", 1)
  .decrement("credit", 100);

// SQL: UPDATE users SET credit = credit - 100 WHERE id = 1

여러 컬럼 동시 수정

await db.table("users").where("id", 1).update({
  username: "new_name",
  email: "new@example.com",
  updated_at: new Date(),
});

DELETE - 데이터 삭제

기본 DELETE

const count = await db.table("users").where("id", 1).delete();

console.log(`${count} rows deleted`);

WHERE 절 필수: DELETE도 반드시 WHERE 조건과 함께 사용해야 합니다.

여러 레코드 삭제

const count = await db.table("users").whereIn("status", ["deleted", "banned"]).delete();

LIMIT & OFFSET - 페이지네이션

LIMIT - 결과 개수 제한

const users = await db.table("users").select({ id: "id", name: "username" }).limit(10);

// 최대 10개만 조회

OFFSET - 건너뛰기

const users = await db.table("users").select({ id: "id", name: "username" }).limit(10).offset(20);

// 20개를 건너뛰고 다음 10개 조회 (21~30번째)

페이지네이션 예제

function getUsers(page: number, pageSize: number) {
  return db
    .table("users")
    .select({ id: "id", name: "username" })
    .limit(pageSize)
    .offset((page - 1) * pageSize);
}

// 1페이지 (1~10)
await getUsers(1, 10);

// 2페이지 (11~20)
await getUsers(2, 10);

ORDER BY - 정렬

기본 정렬

const users = await db
  .table("users")
  .select({ id: "id", name: "username" })
  .orderBy("created_at", "asc");

const users = await db
  .table("users")
  .select({ id: "id", name: "username" })
  .orderBy("created_at", "desc");

여러 컬럼 정렬

const users = await db
  .table("users")
  .select({ id: "id", name: "username", age: "age" })
  .orderBy("age", "desc") // 1순위: 나이 내림차순
  .orderBy("created_at", "asc"); // 2순위: 생성일 오름차순

first() - 단일 결과 조회

first()는 첫 번째 결과만 반환합니다.

const user = await db
  .table("users")
  .select({ id: "id", name: "username" })
  .where("email", "john@example.com")
  .first();

if (user) {
  console.log(user.name); // string
} else {
  console.log("User not found");
}

// 타입: { id: number; name: string; } | undefined

first()는 결과가 없으면 undefined를 반환합니다. 반드시 존재 여부를 체크하세요.

pluck() - 단일 컬럼 추출

특정 컬럼의 값들만 배열로 가져옵니다.

const userIds = await db
  .table("users")
  .where("role", "admin")
  .pluck("id");

// [1, 2, 3, 4, 5]
// 타입: number[]

const emails = await db
  .table("users")
  .select({ userId: "id", userEmail: "email" })
  .where("role", "admin")
  .pluck("email");

// ["admin1@test.com", "admin2@test.com"]
// 타입: string[]

count - 개수 세기

레코드 개수를 조회하려면 Puri.count() 정적 메서드를 select 안에서 사용합니다.

const result = await db
  .table("users")
  .where("role", "admin")
  .select({ total: Puri.count() })
  .first();

console.log(`Total admins: ${result.total}`);
// 타입: number

Puri.count()는 SELECT 절 안에서 사용하는 정적 메서드입니다. 더 복잡한 집계는 Aggregations 참고

실전 예제

사용자 목록 조회 API

async findUsers(params: {
  role?: string;
  search?: string;
  page: number;
  pageSize: number;
}) {
  const { role, search, page, pageSize } = params;

  let query = this.getPuri("r")
    .table("users")
    .select({
      id: "id",
      username: "username",
      email: "email",
      role: "role",
      createdAt: "created_at",
    });

  // 조건 추가
  if (role) {
    query = query.where("role", role);
  }

  if (search) {
    query = query.where("username", "like", `%${search}%`);
  }

  // 페이지네이션
  const users = await query
    .orderBy("created_at", "desc")
    .limit(pageSize)
    .offset((page - 1) * pageSize);

  // 전체 개수
  const { total } = await this.getPuri("r")
    .table("users")
    .where("role", role)
    .select({ total: Puri.count() })
    .first();

  return { users, total };
}

게시글 작성 API

async createPost(data: {
  title: string;
  content: string;
  userId: number;
}) {
  const inserted = await this.getPuri("w")
    .table("posts")
    .insert({
      title: data.title,
      content: data.content,
      user_id: data.userId,
      status: "draft",
      created_at: new Date(),
    })
    .returning(["id", "title", "created_at"]);

  return inserted[0];
}

조회수 증가

async incrementViewCount(postId: number) {
  await this.getPuri("w")
    .table("posts")
    .where("id", postId)
    .increment("view_count", 1);
}

쿼리 디버깅

debug() - SQL 출력

const users = await db.table("users").select({ id: "id" }).where("role", "admin").debug(); // 콘솔에 SQL 출력

// 출력:
// SELECT "users"."id" AS `id` FROM "users" WHERE "role" = 'admin'

rawQuery() - Knex QueryBuilder 얻기

내부 Knex 쿼리 빌더에 접근할 수 있습니다.

const knexQuery = db.table("users").select({ id: "id" }).rawQuery();

console.log(knexQuery.toQuery());

다음 단계

Joins

테이블 조인하기

Aggregations

집계 함수 사용하기

Type Safety

타입 안전성 이해하기

Advanced Patterns

고급 패턴 배우기

​쿼리 시작하기

SELECT

INSERT

UPDATE

DELETE

​SELECT - 데이터 조회

​기본 SELECT

​컬럼 별칭(Alias)

​appendSelect - 컬럼 추가

​WHERE - 조건 필터링

​기본 WHERE

​복수 조건 (AND)

​OR 조건

​IN / NOT IN

​LIKE 검색

​INSERT - 데이터 추가

​단일 레코드 추가

​RETURNING으로 삽입된 데이터 받기

​여러 레코드 추가

​UPDATE - 데이터 수정

​기본 UPDATE

​increment / decrement

​여러 컬럼 동시 수정

​DELETE - 데이터 삭제

​기본 DELETE

​여러 레코드 삭제

​LIMIT & OFFSET - 페이지네이션

​LIMIT - 결과 개수 제한

​OFFSET - 건너뛰기

​페이지네이션 예제

​ORDER BY - 정렬

​기본 정렬

​여러 컬럼 정렬

​first() - 단일 결과 조회

​pluck() - 단일 컬럼 추출

​count - 개수 세기

​실전 예제

​사용자 목록 조회 API

​게시글 작성 API

​조회수 증가

​쿼리 디버깅

​debug() - SQL 출력

​rawQuery() - Knex QueryBuilder 얻기

​다음 단계

Joins

Aggregations

Type Safety

Advanced Patterns

쿼리 시작하기

SELECT - 데이터 조회

기본 SELECT

컬럼 별칭(Alias)

appendSelect - 컬럼 추가

WHERE - 조건 필터링

기본 WHERE

복수 조건 (AND)

OR 조건

IN / NOT IN

LIKE 검색

INSERT - 데이터 추가

단일 레코드 추가

RETURNING으로 삽입된 데이터 받기

여러 레코드 추가

UPDATE - 데이터 수정

기본 UPDATE

increment / decrement

여러 컬럼 동시 수정

DELETE - 데이터 삭제

기본 DELETE

여러 레코드 삭제

LIMIT & OFFSET - 페이지네이션

LIMIT - 결과 개수 제한

OFFSET - 건너뛰기

페이지네이션 예제

ORDER BY - 정렬

기본 정렬

여러 컬럼 정렬

first() - 단일 결과 조회

pluck() - 단일 컬럼 추출

count - 개수 세기

실전 예제

사용자 목록 조회 API

게시글 작성 API

조회수 증가

쿼리 디버깅

debug() - SQL 출력

rawQuery() - Knex QueryBuilder 얻기

다음 단계