> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 데이터베이스

> Replit의 내장 SQL 데이터베이스를 사용하여 앱의 데이터를 저장하고 조회하는 방법을 알아보세요.

export const YouTubeEmbed = ({videoId, title = "YouTube video", startAt}) => {
  if (!videoId) {
    return null;
  }
  let url = "https://www.youtube.com/embed/" + videoId;
  if (startAt) {
    url = url + "?start=" + startAt;
  }
  return <Frame>
      <iframe src={url} title={title} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen></iframe>
    </Frame>;
};

Replit 데이터베이스는 완전 관리형 SQL 데이터베이스를 사용하여 프로젝트 편집기에서 Replit 앱에 영구 데이터 스토리지를 추가할 수 있습니다.

<Note>
  가장 빠른 시작 방법은 **Agent**에게 앱에 데이터베이스를 추가해 달라고 요청하는 것입니다. Agent가 연동을 설정하고, 데이터베이스 스키마를 만들고, 데이터를 저장하고 조회하도록 앱을 업데이트합니다.
</Note>

<Frame>
  <img src="https://mintcdn.com/replit/tlGd6oyGOaUUeRxr/images/databases/database-editor.jpg?fit=max&auto=format&n=tlGd6oyGOaUUeRxr&q=85&s=18a9293165cc5d42db6c61ea572780d1" alt="데이터베이스 편집기 스크린샷" width="1389" height="871" data-path="images/databases/database-editor.jpg" />
</Frame>

## 기능

Replit 데이터베이스 도구는 다음 기능을 제공합니다:

* **데이터베이스 도구**: 내장 SQL 도구로 쿼리를 실행하고, 데이터베이스 스키마를 관리하고, 데이터를 시각화합니다
* **시간 여행**: [롤백 기능](/references/version-control/checkpoints-and-rollbacks/)을 사용하여 데이터베이스를 **Agent** 체크포인트 상태로 복원합니다
* **무료 스토리지**: 모든 Replit 앱에 20GB의 무료 스토리지가 포함됩니다
* **환경 변수**: Replit 앱의 환경 변수를 사용하여 데이터베이스에 안전하게 접근합니다

<Info>
  2025년 12월 4일 이전에는 개발 데이터베이스가 Neon에 호스팅되었으며 몇 가지 중요한 차이점이 있습니다.
  자세한 내용은 [레거시 Neon 개발 데이터베이스](#legacy-development-database) 섹션을 참조하세요.
</Info>

## 사용법

<YouTubeEmbed videoId="zbyRuoPNIc8" title="Replit에서 데이터베이스 사용하는 방법" />

프로젝트 편집기에서 직접 Replit 데이터베이스 도구에 접근할 수 있습니다.
다음 섹션에서 데이터베이스 설정 및 관리 방법을 안내합니다.

<Accordion title="Replit 데이터베이스 도구 접근 방법">
  왼쪽 **도구 독**에서:

  1. <img class="icon-svg" src="https://mintcdn.com/replit/X_IP1EeHGm0cA2VA/images/icons/workspace-all-tools-button.svg?fit=max&auto=format&n=X_IP1EeHGm0cA2VA&q=85&s=579643854fb13c402de516695e52c554" alt="모든 도구 아이콘" width="16" height="16" data-path="images/icons/workspace-all-tools-button.svg" /> **모든 도구**를 선택하여 프로젝트 편집기 도구 목록을 확인합니다.
  2. <img class="icon-svg" src="https://mintcdn.com/replit/rJldsgYVucXB_6kW/images/icons/postgres.svg?fit=max&auto=format&n=rJldsgYVucXB_6kW&q=85&s=68fc78519888560040eb7096f68e76df" alt="PostgreSQL 데이터베이스 아이콘" width="24" height="24" data-path="images/icons/postgres.svg" /> **데이터베이스**를 선택합니다.

  **검색창**에서:

  1. 상단의 <img class="icon-svg" src="https://mintcdn.com/replit/X_IP1EeHGm0cA2VA/images/icons/workspace-search-icon.svg?fit=max&auto=format&n=X_IP1EeHGm0cA2VA&q=85&s=d3feed840da2d19e1ee4873d137114dc" alt="돋보기 아이콘" width="16" height="16" data-path="images/icons/workspace-search-icon.svg" /> 돋보기를 선택하여 검색 도구를 엽니다
  2. "Replit Database"를 입력하여 도구를 찾고 결과에서 선택합니다.
</Accordion>

### 데이터베이스 추가

모든 Replit 앱에는 기본적으로 데이터베이스가 포함되어 있습니다. 프로젝트 편집기에서 <img class="icon-svg" src="https://mintcdn.com/replit/rJldsgYVucXB_6kW/images/icons/postgres.svg?fit=max&auto=format&n=rJldsgYVucXB_6kW&q=85&s=68fc78519888560040eb7096f68e76df" alt="PostgreSQL 데이터베이스 아이콘" width="24" height="24" data-path="images/icons/postgres.svg" /> **데이터베이스** 도구를 선택하여 접근할 수 있습니다.

**Agent**에게 Replit 앱에 PostgreSQL 데이터베이스를 추가해 달라고 요청하여 앱과 데이터베이스를 연동할 수 있습니다. Replit 앱이 저장해야 할 데이터에 대한 세부 사항을 포함하세요. Agent가 데이터베이스 스키마를 만들고 데이터베이스와 통신하도록 앱을 업데이트합니다.

### 데이터베이스를 이전 상태로 복원

[롤백 기능](/references/version-control/checkpoints-and-rollbacks/)을 사용하여 앱과 데이터베이스를 이전 상태로 되돌릴 수 있습니다.
이 기능을 사용하면 **Agent**가 만든 체크포인트 상태로 데이터베이스를 복원할 수 있습니다.

<Frame>
  <img src="https://mintcdn.com/replit/0UCOQvZyQpUEM03B/images/replitai/checkpoint-rollback.png?fit=max&auto=format&n=0UCOQvZyQpUEM03B&q=85&s=f9594eb28458309b2759e8698b8535ce" alt="롤백 옵션을 보여주는 체크포인트 롤백 인터페이스" width="3154" height="2366" data-path="images/replitai/checkpoint-rollback.png" />
</Frame>

<Info>
  체크포인트 상태로 복원할 때 "추가 롤백 옵션"에서 "데이터베이스"를 선택하세요. 이렇게 하면 체크포인트 시점의 데이터베이스 상태로 복원됩니다.
</Info>

### 데이터베이스 명령 실행

SQL 실행기는 데이터베이스에서 SQL 명령을 실행하고 결과를 확인할 수 있는 프로젝트 편집기 도구입니다.

<Accordion title="SQL 실행기 접근 방법">
  **Replit 데이터베이스** 도구에서:

  1. **내 데이터** 탭을 선택합니다
  2. <img class="icon-svg" src="https://mintcdn.com/replit/X_IP1EeHGm0cA2VA/images/icons/sql-runner-icon.svg?fit=max&auto=format&n=X_IP1EeHGm0cA2VA&q=85&s=fd73c517972d1a4004105e6ab49d130b" alt="SQL 실행기 아이콘" width="16" height="16" data-path="images/icons/sql-runner-icon.svg" /> **SQL 실행기**를 선택합니다
</Accordion>

쿼리를 실행하려면 텍스트 영역에 SQL 문을 입력하고
아래와 같이 인접한 <img class="icon-svg" src="https://mintcdn.com/replit/X_IP1EeHGm0cA2VA/images/icons/sql-play.svg?fit=max&auto=format&n=X_IP1EeHGm0cA2VA&q=85&s=eb0c68e0ab494444f0cbc60325bd1150" alt="sql 실행 아이콘" width="18" height="18" data-path="images/icons/sql-play.svg" /> 실행 버튼을 선택합니다:

<Frame>
  <img src="https://mintcdn.com/replit/tlGd6oyGOaUUeRxr/images/databases/sql-runner-run.jpg?fit=max&auto=format&n=tlGd6oyGOaUUeRxr&q=85&s=258c6ac51524a21e6a6e2070c7cefd3c" alt="SQL 실행기와 실행 버튼 스크린샷" width="1390" height="608" data-path="images/databases/sql-runner-run.jpg" />
</Frame>

### 데이터 시각적으로 탐색 및 수정

Replit 데이터베이스 도구에는 데이터를 시각적으로 탐색하고 수정할 수 있는 <a href="https://orm.drizzle.team/drizzle-studio/overview" target="_blank">Drizzle Studio</a>가 포함되어 있습니다.

이 시각화 도구는 구문 오류를 방지하고 다음 기능을 제공합니다:

* 특정 정보에 집중하기 위한 데이터 필터링 및 정렬
* 외부 사용을 위한 파일로 데이터 내보내기
* 행 데이터 삽입 또는 수정
* 스키마, 테이블, 뷰, 열거형 생성 및 관리

이 도구들은 **Replit 데이터베이스** 도구의 **내 데이터** 탭에서 접근할 수 있습니다.

다음 이미지는 Drizzle Studio 빌더 인터페이스의 뷰입니다:

<Frame>
  <img src="https://mintcdn.com/replit/tlGd6oyGOaUUeRxr/images/databases/database-editor.jpg?fit=max&auto=format&n=tlGd6oyGOaUUeRxr&q=85&s=18a9293165cc5d42db6c61ea572780d1" alt="테이블 구조 편집기 이미지" width="1389" height="871" data-path="images/databases/database-editor.jpg" />
</Frame>

<Tip>
  [환경 변수](#environment-variables)에서 찾을 수 있는 연결 문자열을 사용하여
  PostgreSQL 호환 SQL 클라이언트로 데이터베이스에 연결할 수 있습니다.
</Tip>

### 연결 자격 증명 및 사용량 확인

데이터베이스 연결 자격 증명은 Replit 앱의 환경 변수로 저장됩니다.
이 자격 증명은 앱이 데이터베이스에 안전하게 연결하고 명령을 실행하는 데 사용됩니다.

<Accordion title="데이터베이스 연결 자격 증명 접근 방법">
  1. 프로젝트 편집기에서 <img class="icon-svg" src="https://mintcdn.com/replit/rJldsgYVucXB_6kW/images/icons/postgres.svg?fit=max&auto=format&n=rJldsgYVucXB_6kW&q=85&s=68fc78519888560040eb7096f68e76df" alt="PostgreSQL 데이터베이스 아이콘" width="24" height="24" data-path="images/icons/postgres.svg" /> **Replit 데이터베이스** 도구로 이동합니다
  2. 개발 또는 프로덕션 데이터베이스를 선택합니다
  3. <img class="icon-svg" src="https://mintcdn.com/replit/rJldsgYVucXB_6kW/images/icons/settings-icon.svg?fit=max&auto=format&n=rJldsgYVucXB_6kW&q=85&s=27601119959a9349e102c44c2adbd398" alt="기어 아이콘" width="16" height="16" data-path="images/icons/settings-icon.svg" /> **설정** 탭(기어 아이콘)을 선택합니다. 이 탭에서 데이터베이스의 연결 자격 증명과 스토리지 사용량을 확인할 수 있습니다.
</Accordion>

#### 환경 변수

개발 데이터베이스 연결을 위해 다음 환경 변수를 사용할 수 있습니다:

* `DATABASE_URL`: 데이터베이스에 연결하고 인증하는 방법

이 `DATABASE_URL`은 앱에서만 사용할 수 있으며, 유출되더라도 다른 사람이 데이터베이스에 접근하거나 수정하는 데 사용할 수 없습니다.

<Info>
  개발 데이터베이스가 여전히 [레거시 Neon 인프라](#legacy-development-database)에 있다면 다음 추가 환경 변수도 사용할 수 있습니다: `PGHOST`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`, `PGPORT`. 이러한 개별 연결 변수는 Replit의 현재 인프라에서 호스팅되는 데이터베이스에는 제공되지 않습니다 — 대신 `DATABASE_URL`을 사용하세요.
</Info>

<Info>
  이 `DATABASE_URL`은 앱 범위로 제한되어 있으므로, 개발 데이터베이스는 본인 소유의 앱이나 외부 데이터베이스 뷰어를 포함하여 다른 앱에서 접근할 수 없습니다.
  이 분리는 보안 모범 사례를 따르며 데이터베이스에 대한 무단 접근을 방지합니다.
</Info>

<Warning>
  [레거시 Neon 개발 데이터베이스](#legacy-development-database)를 사용 중인 경우, `DATABASE_URL`을 공유하지 마세요.
  누구나 데이터베이스에 접근하고 수정하는 데 사용할 수 있는 데이터베이스 자격 증명이 포함되어 있습니다.
  공개 장소나 지원 티켓에 절대 붙여넣지 마세요.
</Warning>

### 보안 기능

**Agent**를 사용하여 데이터베이스 연동을 추가하면 내장 보안 기능이 있는
ORM(Object-Relational Mapper)이 추가되어 모든 데이터베이스 통신을 처리합니다.

이 ORM 계층은 Agent의 보안 모범 사례 구현과 결합하여 다음 기능으로 앱을 보호합니다:

* **스키마 검증**: 데이터가 예상 형식을 준수하는지 확인
* **데이터 살균**: 빌더 입력을 자동으로 정리하여 SQL 인젝션 공격 방지

## 레거시 개발 데이터베이스

2025년 12월 4일 이전에는 개발 데이터베이스가 <a href="https://neon.com/" target="_blank">Neon</a>에 호스팅되었습니다.
이 데이터베이스는 이제 더 이상 사용되지 않으며 모든 새 개발 데이터베이스는 Replit 자체 데이터베이스 인프라에 호스팅됩니다.

`DATABASE_URL` [환경 변수](#view-connection-credentials-and-usage)를 확인하여 개발 데이터베이스가 Neon에 호스팅되어 있는지 확인할 수 있습니다.

<Info>
  `DATABASE_URL`에 `neon.tech/neondb`가 포함되어 있으면 개발 데이터베이스가 아직 Neon에 호스팅되어 있는 것입니다.
  `helium/heliumdb`가 포함되어 있으면 개발 데이터베이스가 Replit에 호스팅되어 있는 것입니다.
</Info>

다음은 레거시 Neon 개발 데이터베이스와 새로운 Replit 개발 데이터베이스의 주요 차이점입니다:

| **기능**        | **Replit (현재)**                                                                                | **Neon (레거시)**                                                                            |
| ------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **호스팅**       | Replit 자체 인프라에 호스팅                                                                             | Neon(서드파티 제공업체)에 호스팅                                                                      |
| **결제**        | 모든 Replit 앱에 무료로 포함                                                                            | 사용량 기반 청구. 자세한 내용은 [게시 및 데이터베이스 청구](/billing/about-usage-based-billing#databases)를 참조하세요. |
| **복원 기능**     | [롤백 기능](/references/version-control/checkpoints-and-rollbacks/)을 사용하여 데이터베이스를 모든 체크포인트로 복원     | PITR(포인트인타임 복구) — 백업 보존 기간 내의 임의 시점으로 복구.                                                 |
| **연결 보안**     | 앱 내에서만 접근 가능, 공개적으로 노출되지 않음.                                                                   | 전체 연결 문자열 사용 — 유출되면 누구나 데이터베이스에 접근하고 수정할 수 있음.                                            |
| **리믹스 동작**    | [리믹스](/build/remix-an-app) 시 격리 및 보안을 위해 복사된 데이터가 있는 새 개발 데이터베이스 생성.                           | 리믹스 시 모든 복사본이 동일한 데이터베이스를 재사용하므로 리믹스의 변경 사항이 원본 앱에 영향을 줄 수 있음.                            |
| **데이터베이스 생성** | 각 Replit 앱마다 자동으로 생성.                                                                          | 명시적 설정 필요.                                                                                |
| **게시 워크플로**   | 배포 또는 게시 시 환경 간 격리를 위해 [프로덕션 데이터베이스](/references/data-and-storage/production-databases) 생성 필요. | 개발과 프로덕션이 동일한 데이터베이스를 공유하여 의도치 않은 개발 변경이 프로덕션 앱에 영향을 줄 수 있음.                              |

<Warning>
  앱이 레거시 Neon 데이터베이스를 사용하는 동안 포크되거나 리믹스된 경우, 게시된 앱이 여전히 원본 앱의 데이터베이스 URL을 참조하고 있을 수 있습니다. [데이터베이스 업그레이드](/references/data-and-storage/database-upgrade) 이후 이 공유 연결은 작동을 멈춥니다. 게시된 앱 업데이트 방법은 [공유 데이터베이스를 사용하는 게시된 앱 수정](/references/data-and-storage/shared-database-migration)을 참조하세요.
</Warning>