7.10.0에서 테스트됨)을 사용합니다.
사전 요구 사항
- Node.js 20.19, 22.12 또는 24 이상
- ClickHouse Managed Postgres 서비스
- 데이터베이스 생성에 사용할
psql. SQL 콘솔에서CREATE DATABASESQL 문을 실행해도 됩니다. - 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의 트랜잭션 풀링 모드에서는 이 잠금이 풀링된 백엔드에 그대로 남은 채 해당 백엔드가 다른 클라이언트의 요청을 처리할 수 있으며, 그 결과 이후의 마이그레이션이 이 잠금에 막혀 진행되지 않습니다.
<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 파일을 생성하세요:
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 모달에 표시된 값을 사용하세요:- **
DATABASE_URL**은@prisma/adapter-pg를 통해 node-postgres가 읽습니다. Connect 모달에 표시된 것과 동일한 표준 매개변수인sslmode=verify-full&sslrootcert=...를 지원합니다. - **
DIRECT_URL**은 Prisma CLI의 스키마 엔진이 읽으며, 이 엔진은 자체 매개변수를 사용합니다.sslcert는 CA 인증서의 경로를 지정하고,sslaccept=strict는 인증서 및 호스트명 검증을 활성화합니다.
3
Prisma CLI가 직접 연결을 사용하도록 설정
prisma7.config.ts의 내용을 다음과 같이 바꾸세요:스키마 정의 및 마이그레이션 실행
1
모델 추가
prisma/schema.prisma 파일 끝에 Todo 모델을 추가합니다.2
마이그레이션 실행
Linux에서는 Prisma Migrate를 직접 실행합니다.macOS에서는 동일한 명령어를 Linux 컨테이너에서 실행합니다.Prisma는
prisma/migrations/에 SQL 마이그레이션을 생성한 뒤 적용합니다.3
Prisma Client 생성
generated/prisma에 생성됩니다. 이 명령어는 데이터베이스에 연결하지 않으므로 어떤 플랫폼에서든 실행할 수 있습니다.데이터베이스 쿼리
1
Prisma Client 생성
lib/prisma.ts를 생성하십시오. PrismaPg 어댑터는 PgBouncer를 통해 DATABASE_URL로 연결합니다:2
CRUD 쿼리 실행
script.ts를 생성하십시오:3
HTTP로 데이터 제공
server.ts를 생성하십시오. 이 파일은 POST /todos 요청으로 할 일을 생성하고, 모든 GET 요청에 대해 할 일 목록을 반환하는 최소한의 HTTP 서버입니다:SQL 콘솔에서 확인하기
ClickHouse Cloud 콘솔에서 해당 서비스의 SQL 콘솔을 열고, 데이터베이스와public 스키마를 펼친 다음 Todo 테이블을 선택하십시오. Prisma Migrate가 적용된 마이그레이션을 기록하는 _prisma_migrations 테이블도 함께 표시됩니다.
Todo 테이블에는 HTTP 엔드포인트를 통해 추가한 2개의 행이 저장되어 있습니다.
문제 해결
다음 단계
- 연결: 연결 문자열(connection string), PgBouncer 및 TLS
- 설정: Postgres 및 PgBouncer 매개변수 조정
- 읽기 레플리카(Read replica): 읽기 작업이 많은 워크로드 확장
- 로컬 개발: Docker에서 실행되는 로컬 Postgres로 개발
- 프로덕션 환경의 Prisma Migrate: CI 파이프라인에서
prisma migrate deploy사용