콘텐츠로 이동

Prisma Postgres & Astro

Prisma Postgres는 최신 웹 앱을 위해 구축된 완전 관리형 서버리스 Postgres 데이터베이스입니다.

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 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의 내용을 이 예시로 바꾸세요. 나중에 안전하게 삭제하거나 실제 데이터를 반영하는 모델로 대체할 수 있습니다.

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 init

Connection terminated unexpectedly 메시지와 함께 명령이 중단되면, 방금 생성한 데이터베이스가 아직 시작 중인 것입니다. 몇 초 기다린 후 다시 실행하세요.

컨트랙트를 변경한 후에는 npx prisma db update를 다시 실행하여 변경 사항을 데이터베이스에 적용하세요.

src/prisma/db.ts에서 내보낸 db 클라이언트는 한 번 생성되어 프로젝트 전체에서 재사용됩니다. 모델은 PostgreSQL 스키마별로 그룹화되므로 Post 모델은 db.orm.public.Post로 사용할 수 있습니다.

다음 예시는 공개된 게시물만 id별로 정렬하여 가져온 다음, Astro 템플릿에서 제목과 게시물 내용을 표시하는 방법을 보여줍니다.

src/pages/posts.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 연결의 유효성을 검사하는 데 사용할 수 있습니다:

src/pages/index.astro
---
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>

더 많은 백엔드 서비스 가이드

기여하기 커뮤니티 후원하기