Skip to main content
Kysely는 TypeScript용 타입 안전(type-safe) SQL 쿼리 빌더입니다. 이 가이드에서는 pg 드라이버를 통해 TLS 검증을 적용하여 Kysely를 ClickHouse Managed Postgres에 연결하고, Kysely 마이그레이션(migrations)으로 테이블을 생성한 다음, Node.js로 간단한 할 일(to-do) API를 구동합니다.

사전 요구 사항

  • Node.js 22.18 이상. 이 버전부터는 빌드 단계 없이 TypeScript 파일을 바로 실행할 수 있습니다. 이 가이드의 파일은 .mts 확장자를 사용하므로, CommonJS 프로젝트와 ES 모듈 프로젝트 모두에서 Node.js가 해당 파일을 ES 모듈로 처리합니다.
  • ClickHouse Cloud 계정.
  • 데이터베이스 생성에 사용할 psql. SQL 콘솔에서 CREATE DATABASE SQL 문을 실행해도 됩니다.
  • API 호출에 사용할 curl.
이 가이드는 Node.js 24.21, Kysely 0.29.6, pg 8.23.1, TypeScript 7.0.2, PostgreSQL 18 환경에서 테스트되었습니다.

ClickHouse Managed Postgres 서비스 생성

ClickHouse Cloud 콘솔에서 New service를 클릭한 후 Postgres를 선택하십시오. 몇 분 내로 인스턴스가 준비됩니다. 자세한 단계별 안내는 빠른 시작 가이드를 참조하십시오.

연결 정보 확인하기

서비스의 왼쪽 사이드바에서 Connect를 클릭합니다. Directly를 선택한 상태로 두고 Use SSL을 켜면 url 연결 문자열이 sslmode=verify-full&sslrootcert=...로 끝납니다. Download CA certificate를 클릭하여 <service-name>-ca-certificate.pem이라는 이름의 서비스 CA 인증서를 다운로드한 다음, 연결 문자열을 복사합니다. 이 가이드에서는 다음 두 가지 이유로 포트 5432를 통해 Postgres에 직접 연결합니다.
  • Node.js 서버는 장시간 실행되는 프로세스입니다. pg Pool이 이미 소수의 연결을 열어 두고 재사용하므로, 서버 측 풀러(pooler)를 추가해도 얻는 이점이 거의 없습니다.
  • Kysely의 Migrator는 마이그레이션을 실행하는 동안 세션 수준의 권고 잠금(advisory lock, pg_advisory_lock)을 유지합니다. PgBouncer는 트랜잭션 풀링 모드로 동작하므로 잠금 획득, 마이그레이션 실행, 잠금 해제가 각각 서로 다른 백엔드 연결에서 처리될 수 있습니다. 따라서 PgBouncer를 거치면 풀링된 연결에 잠금이 해제되지 않은 채 남을 수 있으며, 이후 실행되는 마이그레이션은 이 잠금을 기다리며 차단됩니다.
나중에 앱 인스턴스나 서버리스 함수를 여러 개 실행하게 되면 앱의 연결 문자열이 PgBouncer(동일한 호스트, 포트 6432)를 가리키도록 변경할 수 있습니다. pg는 기본적으로 이름 없는 prepared statement를 사용하므로, pg를 사용하는 Kysely는 트랜잭션 풀링 모드에서도 정상적으로 동작합니다. 단, 마이그레이션은 계속 포트 5432로 실행하십시오. 자세한 내용은 PgBouncer 연결 풀링을 참조하십시오.

프로젝트 설정

프로젝트를 생성한 후 Kysely, pg 드라이버, TypeScript를 설치하세요.
기존 앱에 추가하시나요?mkdir kysely-todo && cd kysely-todo와 npm init -y는 건너뛰십시오. 대신 프로젝트에서 다음 명령어를 실행하세요. 이 명령어는 migrate 및 typecheck 스크립트를 추가하며, 기존 start 스크립트는 변경하지 않습니다. 그런 다음 연결 구성 단계로 넘어가세요.

연결 구성

다운로드한 CA 인증서를 프로젝트 디렉터리로 옮긴 후 파일 이름을 ca-certificate.pem으로 변경하십시오. 그런 다음 애플리케이션용 데이터베이스를 생성하십시오.
복사한 연결 문자열을 새 .env 파일이나 기존 .env 파일에 추가하십시오. <PASSWORD>는 실제 비밀번호로, 데이터베이스 이름은 guide_kysely로 바꾸고, sslrootcert는 ca-certificate.pem으로 설정하십시오:
.env
pg는 연결 문자열에서 sslmode와 sslrootcert를 읽습니다. verify-full로 설정하면 서버 인증서가 서비스의 CA로 서명되었는지, 그리고 호스트명과 일치하는지 검사합니다. sslrootcert는 작업 디렉터리를 기준으로 해석되며, npm run을 사용하면 작업 디렉터리는 프로젝트 루트가 됩니다.
URL에서 sslmode=verify-full을 제거하지 마십시오. sslmode가 없으면 pg는 TLS를 사용하지 않으며 서버도 검증하지 않습니다. 또한 Pool에 ssl 객체를 함께 전달하지 마십시오. URL에 sslmode가 포함되어 있으면 URL의 설정이 ssl 객체를 대체합니다. 파일이 아닌 다른 곳에서 CA를 불러와야 한다면 URL에서 sslmode와 sslrootcert를 제거하고, 대신 Pool에 ssl: { ca }를 전달하십시오.
tsc가 Node.js가 실행하는 파일과 동일한 파일을 타입 검사하도록 tsconfig.json을 추가하십시오. 앱에 이미 tsconfig.json이 있다면 다음 compilerOptions와 migrations 폴더를 기존 파일에 머지하십시오.
tsconfig.json

데이터베이스 인터페이스 정의

Kysely는 테이블 구조를 기술한 인터페이스를 바탕으로 모든 쿼리에 타입을 부여합니다. src/db.mts 파일을 생성하고, 이 인터페이스와 함께 pg Pool을 사용하는 PostgresDialect 기반의 Kysely 인스턴스를 정의하세요:
src/db.mts
Generated는 데이터베이스가 값을 자동으로 채우는 컬럼을 나타내므로, 이러한 컬럼은 삽입 시 생략할 수 있습니다.

마이그레이션 생성 및 실행

이 가이드에서는 핵심 kysely 패키지에 포함된 Kysely의 내장 Migrator와 FileMigrationProvider를 사용합니다. 별도의 kysely-ctl CLI는 선택 사항이며, 동일한 Migrator를 래핑한 도구입니다. 마이그레이션 파일을 생성하십시오. Kysely는 파일 이름의 영숫자 순으로 마이그레이션을 실행하므로, 파일 이름 앞에 날짜를 접두사로 붙이십시오.
migrations/2026-09-30_create_todo.mts
대기 중인 모든 마이그레이션을 적용하려면 src/migrate.mts 파일을 생성하십시오. Kysely 0.29에서는 kysely/migration에서 Migrator와 FileMigrationProvider를 가져옵니다:
src/migrate.mts
마이그레이션을 실행하세요:
Kysely는 적용된 마이그레이션을 kysely_migration 테이블에 기록하므로, 명령을 다시 실행해도 아무 변화가 없습니다.
pg가 실제로 인증서를 검증하는지 확인하려면 sslrootcert 없이 마이그레이션을 실행해 보십시오. Node.js는 기본적으로 서비스의 CA를 신뢰하지 않으므로 연결에 실패합니다.

데이터베이스 쿼리하기

Kysely를 사용해 할 일(to-do)을 생성, 조회, 수정, 삭제하는 간단한 HTTP 서버인 src/server.mts를 작성하십시오. 기존 앱에서는 자체 라우트 핸들러(route handler)에서도 동일한 쿼리를 사용할 수 있습니다:
src/server.mts
모든 쿼리는 Database 인터페이스를 기준으로 검사되므로, 테이블명이나 컬럼명의 철자가 틀리거나 필수 항목인 title을 빠뜨린 채 삽입을 수행하면 타입 검사에 실패합니다. 다음과 같이 프로젝트를 검사하세요:

확인

서버를 시작하십시오.
npm start로 자체 앱이 실행되는 기존 앱에서는 대신 node --env-file=.env src/server.mts 명령으로 예시 서버를 시작하십시오. 다른 터미널에서 할 일 항목을 몇 개 생성, 수정, 삭제해 보십시오:
브라우저에서 http://localhost:3000/todos를 열면 남은 할 일 목록을 확인할 수 있습니다. 응답은 다음과 같습니다.
콘솔에서 동일한 데이터를 확인하려면 서비스의 왼쪽 사이드바에서 SQL 콘솔을 열고 guide_kysely와 public 스키마를 펼친 다음 todo 테이블을 클릭하십시오. Kysely가 생성한 kysely_migration 및 kysely_migration_lock 테이블도 함께 표시됩니다.

다음 단계

  • 연결: 연결 문자열, PgBouncer, TLS를 다룹니다.
  • 설정: max_connections 등 PostgreSQL 및 PgBouncer 매개변수를 조정합니다.
  • 읽기 레플리카: 읽기 작업이 많은 워크로드를 확장합니다.
  • Kysely 문서: 조인, 트랜잭션, 타입 생성을 다룹니다.
마지막 수정일 2026년 10월 14일