Prisma Postgres & Astro
Prisma Postgres는 최신 웹 앱을 위해 구축된 완전 관리형 서버리스 Postgres 데이터베이스입니다.
Prisma ORM에 연결하기 (권장)
섹션 제목: “Prisma ORM에 연결하기 (권장)”Prisma ORM은 Prisma Postgres 데이터베이스에 연결하는 데 권장되는 방법입니다. 타입 안전 쿼리, 마이그레이션 및 글로벌 성능을 제공합니다.
이 가이드는 Prisma ORM 8을 사용합니다. Prisma ORM 7을 사용 중이라면 대신 Prisma 문서의 Astro용 Prisma ORM 7 가이드를 따르세요.
전제 조건
섹션 제목: “전제 조건”- 요청 시 렌더링 (SSR)을 활성화하기 위해 어댑터가 설치된 Astro 프로젝트가 필요합니다.
- Astro의 최소 요구 사항을 충족하는 Node.js 버전이 필요합니다. Node.js v24를 사용 중이라면 Prisma ORM 8의 요구 사항에 맞게
v24.11.0이상을 사용해야 합니다.
의존성 설치 및 Prisma 초기화
섹션 제목: “의존성 설치 및 Prisma 초기화”프로젝트에서 다음 명령을 실행하여 Prisma ORM을 설치하고 시작 파일을 생성합니다.
npx prisma@latest orm init --target postgres --authoring psl이 명령은 prisma CLI, @prisma/orm-postgres, dotenv를 설치하고 다음 파일을 생성합니다.
.env에서DATABASE_URL을 불러오는prisma.config.ts파일- 시작 데이터 모델이 포함된
src/prisma/contract.prisma파일 - Prisma ORM 클라이언트를 내보내는
src/prisma/db.ts파일 .env.example파일
이미 Prisma Postgres 데이터베이스가 있다면 연결 문자열을 .env에 DATABASE_URL로 추가하세요. 그렇지 않다면 다음 명령을 실행하여 데이터베이스를 생성하고 연결 문자열을 자동으로 기록하세요.
npx create-db@latest --env .env이 명령은 클레임 URL을 출력합니다. 데이터베이스를 계속 사용하려면 해당 URL을 열고 로그인하세요. Prisma는 클레임되지 않은 데이터베이스를 24시간 후에 삭제합니다.
모델 정의하기
섹션 제목: “모델 정의하기”Prisma는 데이터베이스 테이블을 생성하기 위해 컨트랙트에 최소 하나의 모델이 필요합니다. 다음 예시에서는 Post 모델을 임시로 정의합니다. 시작하려면 src/prisma/contract.prisma의 내용을 이 예시로 바꾸세요. 나중에 안전하게 삭제하거나 실제 데이터를 반영하는 모델로 대체할 수 있습니다.
// use prisma-8
model Post { id Int @id @default(autoincrement()) title String content String? published Boolean @default(false)}// use prisma-8 줄은 파일 맨 위에 유지하세요. 이 줄은 파일이 어떤 컨트랙트 구문을 사용하는지 Prisma에 알려줍니다. Prisma ORM 설정 구성에 대한 자세한 내용은 Prisma 컨트랙트 참조에서 알아보세요.
컨트랙트 출력하기
섹션 제목: “컨트랙트 출력하기”다음 명령을 실행하여 src/prisma/db.ts가 가져오는 타입이 지정된 파일을 생성합니다. 컨트랙트를 변경할 때마다 이 명령을 다시 실행하세요.
npx prisma contract emit데이터베이스 테이블 생성하기
섹션 제목: “데이터베이스 테이블 생성하기”다음 명령을 실행하여 컨트랙트로부터 테이블을 생성합니다. 그러면 데이터베이스의 상태를 기록하는 migrations/ 디렉터리도 함께 생성됩니다.
npx prisma db initConnection terminated unexpectedly 메시지와 함께 명령이 중단되면, 방금 생성한 데이터베이스가 아직 시작 중인 것입니다. 몇 초 기다린 후 다시 실행하세요.
컨트랙트를 변경한 후에는 npx prisma db update를 다시 실행하여 변경 사항을 데이터베이스에 적용하세요.
데이터 쿼리 및 표시하기
섹션 제목: “데이터 쿼리 및 표시하기”src/prisma/db.ts에서 내보낸 db 클라이언트는 한 번 생성되어 프로젝트 전체에서 재사용됩니다. 모델은 PostgreSQL 스키마별로 그룹화되므로 Post 모델은 db.orm.public.Post로 사용할 수 있습니다.
다음 예시는 공개된 게시물만 id별로 정렬하여 가져온 다음, Astro 템플릿에서 제목과 게시물 내용을 표시하는 방법을 보여줍니다.
---import { db } from '../prisma/db';
const posts = await db.orm.public.Post .where({ published: true }) .orderBy((post) => post.id.desc()) .all();---
<html> <head> <title>공개된 게시물 목록</title> </head> <body> <h1>공개된 게시물 목록</h1> <ul> {posts.map((post) => ( <li> <h2>{post.title}</h2> {post.content && <p>{post.content}</p>} </li> ))} </ul> </body></html>API 라우트에서 쿼리를 처리하는 것이 가장 좋습니다. Astro 프로젝트에서 Prisma ORM을 사용하는 방법에 대한 자세한 내용은 Astro + Prisma ORM 가이드와 Prisma의 데이터 읽기 가이드를 참조하세요.
다른 ORM 및 라이브러리와 연결하기
섹션 제목: “다른 ORM 및 라이브러리와 연결하기”다른 ORM, 데이터베이스 라이브러리 또는 원하는 도구를 사용하여 직접 TCP를 통해 Prisma Postgres에 연결할 수 있습니다. 시작하려면 Prisma Console에서 직접 연결 문자열을 만드세요.
전제 조건
섹션 제목: “전제 조건”- 요청 시 렌더링 (SSR)을 활성화하기 위해 어댑터가 설치된 Astro 프로젝트가 필요합니다.
- TCP가 활성화된 연결 문자열이 있는 Prisma Postgres 데이터베이스가 필요합니다.
의존성 설치하기
섹션 제목: “의존성 설치하기”다음은 직접 TCP 연결을 하기 위해 pg(Node.js용 PostgreSQL 클라이언트)를 사용하는 예시입니다.
다음 명령을 실행하여 pg 패키지를 설치합니다.
npm install pg데이터베이스 클라이언트 쿼리
섹션 제목: “데이터베이스 클라이언트 쿼리”SQL 서버와 통신하고 데이터베이스에서 데이터를 가져올 수 있도록 pg 클라이언트에 연결 문자열을 제공합니다.
테이블을 만들고 데이터를 삽입하는 다음 예시는 쿼리 URL과 TCP 연결의 유효성을 검사하는 데 사용할 수 있습니다:
---import { Client } from 'pg';const client = new Client({ connectionString: import.meta.env.DATABASE_URL, ssl: { rejectUnauthorized: false }});await client.connect();
await client.query(` CREATE TABLE IF NOT EXISTS posts ( id SERIAL PRIMARY KEY, title TEXT UNIQUE, content TEXT );
INSERT INTO posts (title, content) VALUES ('Hello', 'World') ON CONFLICT (title) DO NOTHING;`);
const { rows } = await client.query('SELECT * FROM posts');await client.end();---
<h1>게시물 목록</h1><p>{rows[0].title}: {rows[0].content}</p>