Skip to main content
Prisma ORM은 선언적 스키마, 마이그레이션 도구(Prisma Migrate), 자동 생성되는 타입 안전(type-safe) 클라이언트를 제공하는 TypeScript ORM입니다. 이 가이드에서는 Prisma를 ClickHouse Managed Postgres에 연결하고, 마이그레이션으로 테이블을 생성한 뒤, 스크립트와 간단한 HTTP 엔드포인트에서 해당 테이블을 쿼리합니다. 이 가이드에서는 현재 안정 릴리스인 Prisma ORM 7(7.10.0에서 테스트됨)을 사용합니다.

사전 요구 사항

  • Node.js 20.19, 22.12 또는 24 이상
  • ClickHouse Managed Postgres 서비스
  • 데이터베이스 생성에 사용할 psql. SQL 콘솔에서 CREATE DATABASE SQL 문을 실행해도 됩니다.
  • macOS 사용 시: Prisma Migrate 실행에 필요한 Docker (마이그레이션 실행 참조)

ClickHouse Managed Postgres 서비스 생성

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

연결 정보 확인

서비스의 왼쪽 사이드바에서 Connect를 클릭합니다. 모달에 사용자 이름, 비밀번호, 서버, 포트와 함께 바로 사용할 수 있는 연결 문자열(connection string)이 표시됩니다. Prisma에는 데이터베이스와 통신하는 구성 요소가 두 가지 있으므로, 이 가이드에서는 연결을 두 개 사용합니다.
  • 애플리케이션(Prisma Client) 은 포트 6432에서 PgBouncer를 통해 연결합니다. PgBouncer가 연결을 풀링하므로 여러 앱 프로세스나 서버리스 인스턴스가 소수의 Postgres 백엔드를 공유할 수 있습니다.
  • Prisma CLI(Prisma Migrate) 는 포트 5432에서 직접 연결합니다. Prisma Migrate는 실행되는 동안 세션 수준의 권고 잠금(advisory lock)을 획득합니다. PgBouncer의 트랜잭션 풀링 모드에서는 이 잠금이 풀링된 백엔드에 그대로 남은 채 해당 백엔드가 다른 클라이언트의 요청을 처리할 수 있으며, 그 결과 이후의 마이그레이션이 이 잠금에 막혀 진행되지 않습니다.
모달 상단에서 Directly와 via PgBouncer를 전환하면 각 포트를 확인할 수 있습니다. 서버와 자격 증명은 두 연결 모두 동일하며, 포트만 다릅니다. via PgBouncer를 선택한 상태에서 Download CA certificate를 클릭합니다. Directly를 선택한 경우에는 먼저 Use SSL을 켜야 버튼이 표시됩니다. 파일 이름은 <service-name>-ca-certificate.pem이며, Settings → CA Certificate에서도 찾을 수 있습니다. 이 인증서는 인스턴스마다 고유하며, sslmode=verify-full로 연결할 때 사용합니다. 이 모드에서는 통신 중인 서버가 실제로 자신의 서버인지 검증합니다.

프로젝트 설정

TypeScript 프로젝트를 생성하고 Prisma CLI, Prisma Client, node-postgres 드라이버 어댑터 및 dotenv를 설치하십시오.
prisma@7과 @prisma/client@7을 명시적으로 설치하십시오. 이 문서의 작성 시점 기준으로 prisma의 npm latest 태그는 Prisma 8 릴리스 후보(release candidate)를 가리키며, 이 버전은 본 가이드와 설정 방식이 다릅니다.
tsconfig.json 파일을 생성하세요:
기존 앱에 추가하는 경우mkdir, npm init, tsconfig.json 단계는 건너뛰세요. 프로젝트에서 npm install tsx @types/pg prisma@7 --save-dev와 npm install @prisma/client@7 @prisma/adapter-pg pg dotenv를 실행한 다음 Prisma 초기화 단계부터 진행하세요.

Prisma 초기화

1

prisma init 실행

이 명령어는 prisma/schema.prisma와 Prisma 구성 파일인 prisma7.config.ts를 생성합니다. 또한 .env에는 플레이스홀더 DATABASE_URL을, .gitignore에는 생성된 클라이언트를 추가하고(해당 파일이 없으면 새로 생성합니다), AI 코딩 에이전트용 Prisma 스킬도 추가합니다. Prisma 7.10 이상에서는 Prisma 8 포맷과 충돌하지 않도록 구성 파일 이름을 prisma7.config.ts로 지정합니다.
2

CA 인증서 추가

다운로드한 CA 인증서를 프로젝트 루트로 옮긴 후 이름을 ca-certificate.pem으로 변경하세요.
인증서의 상대 경로는 명령어를 실행하는 디렉터리를 기준으로 해석됩니다. 따라서 이 가이드의 모든 명령어는 프로젝트 루트에서 실행하세요.

연결 구성

1

데이터베이스 생성

앱에서 사용할 데이터베이스를 생성합니다. <PASSWORD>와 호스트를 Connect 모달에 표시된 값으로 바꾸세요:
2

연결 URL 설정

.env에서 prisma init이 추가한 플레이스홀더 DATABASE_URL을 아래의 연결 URL 2개로 바꾸세요. 두 URL 모두 guide_prisma 데이터베이스를 가리킵니다. 비밀번호는 Connect 모달에 표시된 값을 사용하세요:
두 URL을 읽는 드라이버가 서로 다르기 때문에 TLS 매개변수도 서로 다릅니다:
  • **DATABASE_URL**은 @prisma/adapter-pg를 통해 node-postgres가 읽습니다. Connect 모달에 표시된 것과 동일한 표준 매개변수인 sslmode=verify-full&sslrootcert=...를 지원합니다.
  • **DIRECT_URL**은 Prisma CLI의 스키마 엔진이 읽으며, 이 엔진은 자체 매개변수를 사용합니다. sslcert는 CA 인증서의 경로를 지정하고, sslaccept=strict는 인증서 및 호스트명 검증을 활성화합니다.
Prisma CLI용 URL에는 sslmode=verify-full&sslrootcert=...를 사용하지 마십시오. 스키마 엔진은 sslrootcert를 무시하며, sslaccept=strict가 없으면 서버 인증서를 전혀 검증하지 않습니다. 따라서 연결은 암호화되지만 인증은 이루어지지 않습니다.
3

Prisma CLI가 직접 연결을 사용하도록 설정

prisma7.config.ts의 내용을 다음과 같이 바꾸세요:
Prisma 7에서 구성 파일의 URL은 CLI에서만 사용됩니다. Prisma Client는 드라이버 어댑터를 통해 연결하며, 드라이버 어댑터는 데이터베이스 쿼리에서 구성합니다.

스키마 정의 및 마이그레이션 실행

1

모델 추가

prisma/schema.prisma 파일 끝에 Todo 모델을 추가합니다.
2

마이그레이션 실행

Linux에서는 Prisma Migrate를 직접 실행합니다.
macOS에서는 동일한 명령어를 Linux 컨테이너에서 실행합니다.
ClickHouse Managed Postgres는 TLS 1.3만 허용합니다. macOS에서는 Prisma CLI의 스키마 엔진이 시스템 TLS 라이브러리를 사용하는데, 이 라이브러리로는 해당 설정에서 연결할 수 없습니다. 이 경우 P1011: Error opening a TLS connection: One or more parameters passed to a function were not valid 오류가 발생하고, sslcert를 제거하면 bad protocol version 오류가 발생합니다(prisma/orm#29600). 이 문제는 prisma migrate, prisma db pull처럼 데이터베이스에 연결하는 CLI 명령어에만 해당합니다. Prisma Client는 node-postgres를 통해 연결하므로 영향을 받지 않습니다. CLI를 Linux 컨테이너나 Linux 기반 CI 파이프라인에서 실행하면 이 문제를 우회할 수 있습니다.
Prisma는 prisma/migrations/에 SQL 마이그레이션을 생성한 뒤 적용합니다.
3

Prisma Client 생성

클라이언트는 generated/prisma에 생성됩니다. 이 명령어는 데이터베이스에 연결하지 않으므로 어떤 플랫폼에서든 실행할 수 있습니다.

데이터베이스 쿼리

1

Prisma Client 생성

lib/prisma.ts를 생성하십시오. PrismaPg 어댑터는 PgBouncer를 통해 DATABASE_URL로 연결합니다:
PgBouncer 설정 불필요@prisma/adapter-pg는 각 쿼리를 이름 없는 prepared statement로 전송하고 DEALLOCATE를 실행하지 않으므로 PgBouncer의 트랜잭션 풀링 모드에서도 정상적으로 동작합니다. 풀링된 여러 백엔드에서 서로 다른 쿼리 수백 개가 동시에 실행되더라도 오류 없이 처리합니다. 이전 Prisma 버전에서 사용하던 pgbouncer=true URL 매개변수는 필요하지 않으며, 드라이버 어댑터를 사용할 때는 아무런 효과가 없습니다.
2

CRUD 쿼리 실행

script.ts를 생성하십시오:
스크립트를 실행하십시오:
3

HTTP로 데이터 제공

server.ts를 생성하십시오. 이 파일은 POST /todos 요청으로 할 일을 생성하고, 모든 GET 요청에 대해 할 일 목록을 반환하는 최소한의 HTTP 서버입니다:
서버를 시작하십시오:
다른 터미널을 열고 할 일 2개를 추가하십시오:
브라우저에서 http://localhost:3000/todos를 열어 추가된 항목을 확인하십시오. 응답은 다음과 같습니다:

SQL 콘솔에서 확인하기

ClickHouse Cloud 콘솔에서 해당 서비스의 SQL 콘솔을 열고, 데이터베이스와 public 스키마를 펼친 다음 Todo 테이블을 선택하십시오. Prisma Migrate가 적용된 마이그레이션을 기록하는 _prisma_migrations 테이블도 함께 표시됩니다. Todo 테이블에는 HTTP 엔드포인트를 통해 추가한 2개의 행이 저장되어 있습니다.

문제 해결

다음 단계