> ## 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 데이터베이스를 사용하여 Project Editor에서 바로 Replit App에 영구 데이터 저장소를 추가할 수 있게 해줍니다.

<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="screenshot of the database editor" width="1389" height="871" data-path="images/databases/database-editor.jpg" />
</Frame>

## 기능

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

* **데이터베이스 도구**: 내장 SQL 도구로 쿼리를 실행하고, 데이터베이스 스키마를 관리하고, 데이터를 시각화합니다
* **타임 트래블**: [롤백 기능](/ko/features/version-control/checkpoints-and-rollbacks/)을 사용해 데이터베이스를 어느 **Agent** 체크포인트로든 복원합니다
* **무료 저장 공간**: 모든 Replit App에 20GB의 무료 저장 공간이 포함됩니다.
* **환경 변수**: Replit App에서 환경 변수를 사용해 데이터베이스에 안전하게 접근합니다

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

## 사용법

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

Project Editor에서 바로 Replit 데이터베이스 도구에 접근할 수 있습니다.
다음 섹션에서는 데이터베이스를 설정하고 관리하는 방법을 안내합니다.

<Accordion title="Replit 데이터베이스 도구에 접근하는 방법">
  좌측 \*\*도구 도크(Tool dock)\*\*에서:

  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="All tools icon" width="16" height="16" data-path="images/icons/workspace-all-tools-button.svg" /> **전체 도구**를 선택해 Project Editor 도구 목록을 확인하세요.
  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="PostgresSQL database icon" 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="magnifying glass icon" width="16" height="16" data-path="images/icons/workspace-search-icon.svg" /> 돋보기를 선택해 검색 도구를 여세요
  2. "Replit Database"를 입력해 도구를 찾고 검색 결과에서 선택하세요.
</Accordion>

### 데이터베이스 추가

모든 Replit App에는 기본적으로 데이터베이스가 함께 제공됩니다. Project Editor에서 <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="PostgresSQL database icon" width="24" height="24" data-path="images/icons/postgres.svg" /> **데이터베이스** 도구를 선택하면 접근할 수 있습니다.

**Agent**에게 Replit App에 PostgreSQL 데이터베이스를 추가해 달라고 요청하고 앱이 어떤 데이터를 저장해야 하는지에 대한
세부 정보를 알려주면 데이터베이스를 앱에 통합할 수 있습니다. Agent가 데이터베이스 스키마를 생성하고
앱이 데이터베이스와 통신하도록 업데이트합니다.

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

[롤백 기능](/ko/features/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="Checkpoint rollback interface showing rollback options" width="3154" height="2366" data-path="images/replitai/checkpoint-rollback.png" />
</Frame>

<Info>
  체크포인트 상태로 복원할 때는 "추가 롤백 옵션" 아래에서 "Database"를 선택해야 합니다. 그러면 데이터베이스가 체크포인트 생성 시점의 상태로 복원됩니다.
</Info>

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

SQL 러너는 데이터베이스에서 SQL 명령을 실행하고 결과를 확인할 수 있는 Project Editor 도구입니다.

<Accordion title="SQL 러너에 접근하는 방법">
  **Replit 데이터베이스** 도구에서:

  1. **My Data** 탭을 선택하세요
  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 runner icon" 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 run icon" 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="screenshot of the SQL runner and run button" 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>가 포함되어 있습니다.

이 시각적 도구는 구문 오류를 방지하는 데 도움이 되며 다음과 같은 기능을 제공합니다.

* 데이터를 필터링 및 정렬해 특정 정보에 집중
* 외부에서 사용할 수 있도록 데이터를 파일로 내보내기
* 행 데이터 삽입 또는 수정
* 스키마, 테이블, 뷰, enum 생성 및 관리

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

다음 이미지는 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="image of the table structure editor" width="1389" height="871" data-path="images/databases/database-editor.jpg" />
</Frame>

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

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

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

<Accordion title="데이터베이스 연결 자격 증명에 접근하는 방법">
  1. Project Editor에서 <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="PostgresSQL database icon" 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="gear icon" width="16" height="16" data-path="images/icons/settings-icon.svg" /> **Settings** 탭(톱니바퀴 아이콘)을 선택하세요. 이 탭에서는 데이터베이스의 연결 자격 증명과 저장 공간 사용량을 확인할 수 있습니다.
</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의 보안 모범 사례 구현과 결합되어 다음 기능을 통해 앱을 각종 공격으로부터 보호합니다.

* **스키마 검증**: 데이터가 예상된 형식을 따르는지 확인합니다
* **데이터 정제(Sanitization)**: SQL 인젝션 공격을 방지하기 위해 빌더 입력을 자동으로 정리합니다

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

2025년 12월 4일 이전에는 개발 데이터베이스가 <a href="https://neon.com/" target="_blank">Neon</a>에서 호스팅되었습니다.
이 데이터베이스는 이제 지원 종료(deprecated)되었으며, 모든 새로운 개발 데이터베이스는 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 App에 무료로 포함                                                                                | 사용량 기반 결제. 자세한 내용은 [게시 및 데이터베이스 결제](/ko/billing/about-usage-based-billing#databases)를 참고하세요. |
| **복원 기능**     | [롤백 기능](/ko/features/version-control/checkpoints-and-rollbacks/)을 사용해 데이터베이스를 어느 체크포인트로든 복원          | 특정 시점 복원(PITR)—백업 보존 기간 내 어느 시점으로든 복구.                                                       |
| **연결 보안**     | 앱 내부에서만 접근 가능하며, 외부에 절대 노출되지 않음.                                                                     | 전체 연결 문자열을 사용—노출되면 누구든 데이터베이스에 접근하고 수정할 수 있음.                                                |
| **리믹스 동작**    | [리믹스](/ko/build/remix-an-app)는 격리와 보안을 위해 데이터가 복사된 새 개발 데이터베이스를 생성                                   | 리믹스가 모든 복제본에서 동일한 데이터베이스를 재사용하므로, 리믹스에서의 변경 사항이 원본 앱에 영향을 줄 수 있음.                            |
| **데이터베이스 생성** | 각 Replit App마다 자동으로 생성됨.                                                                             | 명시적인 설정이 필요함.                                                                                |
| **게시 워크플로**   | 배포 또는 게시를 하려면 환경 간 격리를 위해 [프로덕션 데이터베이스](/ko/features/data-and-storage/production-databases)를 생성해야 함. | 개발과 프로덕션이 동일한 데이터베이스를 공유하여, 의도치 않은 개발 변경 사항이 프로덕션 앱에 영향을 줄 수 있었음.                            |

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