> ## 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.

# 데이터베이스 업그레이드

> 개발 데이터베이스의 Neon에서 Helium으로의 자동 업그레이드와 프로세스 중 예상되는 사항에 대해 알아보세요.

Replit은 개발 데이터베이스를 [Neon](https://neon.tech)(타사 서버리스 PostgreSQL 공급자)에서 Replit 자체 관리형 PostgreSQL 인프라인 **Helium**으로 업그레이드하고 있습니다. 이 업그레이드는 자동으로 실행되며, 앱당 한 번 실행되고 모든 데이터를 보존합니다.

<Note>
  이 업그레이드는 **개발 데이터베이스**에만 적용됩니다. 배포된 앱에서 사용하는
  프로덕션 데이터베이스는 대부분의 경우 영향을 받지 않습니다. 단, 배포된 앱이
  다른 앱과 개발 데이터베이스를 공유하는 경우(오래된 포크 또는 리믹스 앱에서
  흔히 발생), 중요한 단계를 위해 [공유 데이터베이스를 사용하는 게시된 앱
  수정](/references/data-and-storage/shared-database-migration)을
  참조하세요.
</Note>

## 변경되는 사항

업그레이드는 개발 데이터베이스를 Neon 인프라에서 Replit 플랫폼에서 직접 실행되는 Helium으로 이전합니다. 이것이 의미하는 바는 다음과 같습니다:

* **낮은 지연 시간**: 데이터베이스가 앱과 함께 Replit 인프라에서 실행되어 연결 시간 단축
* **더 많은 스토리지**: 스토리지 한도가 10 GB에서 20 GB로 증가
* **동일한 데이터베이스 엔진**: Helium은 Neon과 동일한 버전인 PostgreSQL 16을 사용 — 쿼리, 스키마, 데이터가 동일하게 작동
* **원활한 연결**: `DATABASE_URL` 환경 변수가 자동으로 업데이트되어 Helium을 가리킴
* **Neon 연결 저장**: 이전 Neon 연결 문자열이 참조용으로 Secrets의 `NEON_DATABASE_URL`에 저장됩니다. 이전 Neon 데이터베이스는 업그레이드 후 앱에서 더 이상 사용되지 않으며 임시 유예 기간 후 삭제될 예정입니다.

레거시 Neon 데이터베이스와 새 Replit 데이터베이스 간의 전체 비교(청구, 복원 기능, 연결 보안, 리믹싱 동작의 차이 포함)는 [레거시 개발 데이터베이스](/references/data-and-storage/sql-database#legacy-development-database)를 참조하세요.

## 업그레이드 중 예상되는 사항

업그레이드는 프로젝트 편집기에서 Replit 앱을 열면 자동으로 실행됩니다.

1. **"데이터베이스를 업그레이드하는 중"** 메시지와 함께 진행 화면이 나타납니다
2. 데이터가 Neon에서 Helium으로 안전하게 복사됩니다. 전송 중 데이터가 변경되거나 손실되지 않습니다.
3. 소요 시간은 데이터베이스 크기에 따라 다릅니다 — 대용량 데이터베이스의 경우 몇 분에서 몇 시간이 걸릴 수 있습니다
4. 탭을 열어두거나 닫고 나중에 돌아올 수 있습니다
5. 업그레이드가 완료되면 확인 대화 상자가 나타납니다: **"데이터베이스를 업그레이드했습니다!"**

<Info>
  업그레이드 중 문제가 발생하면 자동으로 건너뛰어 계속 작업할 수 있습니다. 앱을
  다시 열 때 업그레이드가 재시도됩니다.
</Info>

## 업그레이드 후 해야 할 일

대부분의 경우 별도의 조치가 필요하지 않습니다. 앱이 이전과 같이 계속 작동합니다.

<Tip>
  코드가 `DATABASE_URL` 환경 변수를 사용하여 데이터베이스에 연결하는 경우,
  변경이 필요하지 않습니다. 변수가 자동으로 업데이트되어 새 Helium 데이터베이스를
  가리킵니다.
</Tip>

다음 사항이 앱에 해당하는지 확인하세요:

* **하드코딩된 Neon 연결 문자열**: 코드에서 `neon.tech` 연결 문자열을 직접 참조하는 경우, JavaScript에서는 `process.env.DATABASE_URL`, Python에서는 `os.environ['DATABASE_URL']`과 같이 `DATABASE_URL` 환경 변수를 사용하도록 업데이트하세요.

* **사용자 정의 PostgreSQL 역할**: Neon에서 사용자 정의 데이터베이스 역할을 생성한 경우, 해당 역할과 권한이 자동으로 마이그레이션됩니다. 단, 역할 비밀번호는 복사할 수 없으므로 새 Helium 데이터베이스에서 사용자 정의 역할의 비밀번호를 재설정해야 합니다.

* **개별 PG 환경 변수**: `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD` 환경 변수는 업그레이드 후 제거됩니다. 연결에 필요한 모든 정보가 포함된 `DATABASE_URL` 연결 문자열을 사용하세요.

## 문제 해결

### 업그레이드 후 SSL 연결 오류

업그레이드 후 `The server does not support SSL connections` 또는 소켓이 예기치 않게 연결 해제되는 오류가 발생할 수 있습니다. 이는 데이터베이스 연결 코드가 SSL 핸드셰이크를 강제하는 경우에 발생합니다. Neon은 모든 연결에 SSL을 요구했지만, Helium은 앱 옆에 로컬에서 실행되므로 SSL을 사용하지 않습니다.

이를 수정하려면 데이터베이스 연결의 SSL 설정을 환경에 따라 조건부로 설정하세요. 이렇게 하면 앱이 개발(Helium)에서는 SSL 없이, 프로덕션(프로덕션 데이터베이스가 여전히 요구할 수 있는 경우)에서는 SSL로 연결됩니다.

<CodeGroup>
  ```js JavaScript theme={null}
  // 이전 (업그레이드 후 작동 안 함)
  const pool = new Pool({
    connectionString: process.env.DATABASE_URL,
    ssl: { rejectUnauthorized: false },
  });

  // 이후 (개발 및 프로덕션 모두에서 작동)
  const pool = new Pool({
    connectionString: process.env.DATABASE_URL,
    ssl:
      process.env.NODE_ENV === "production"
        ? { rejectUnauthorized: false }
        : false,
  });
  ```
</CodeGroup>

<Tip>
  Drizzle, Prisma, Sequelize 같은 ORM을 사용하는 경우, 조건부로 SSL 설정을
  구성하는 방법에 대한 해당 문서를 확인하세요. 동일한 원칙이 적용됩니다 —
  개발 데이터베이스에는 SSL을 비활성화하고 프로덕션에는 활성화하세요.
</Tip>

## 공유 데이터베이스를 사용하는 배포된 앱

Replit에서 포크 또는 리믹스된 오래된 앱은 원본 앱과 개발 데이터베이스를 공유할 수 있습니다. 레거시 Neon 시스템에서는 앱을 포크하면 원본 앱의 `DATABASE_URL`이 복사되어 두 앱과 게시된 버전이 동일한 데이터베이스에 연결되었습니다.

데이터베이스 업그레이드 후 원본 앱의 Neon 데이터베이스가 비활성화됩니다. 게시된 앱이 여전히 공유 데이터베이스 URL을 사용하는 경우, 게시된 앱이 작동을 멈추거나 데이터에 접근할 수 없게 될 수 있습니다.

<Warning>
  공유 데이터베이스는 **2026년 6월 8일**에 종료됩니다. 영구적인 데이터 손실을 방지하려면
  그 전에 게시된 앱을 업데이트하세요.
</Warning>

### 다음 단계

게시된 앱이 영향을 받는 경우, 전용 단계별 가이드를 따르세요:

* [공유 데이터베이스를 사용하는 게시된 앱 수정](/references/data-and-storage/shared-database-migration)

해당 가이드에서 다루는 내용:

* 게시된 앱이 여전히 이전 Neon 연결을 사용하는지 확인하는 방법
* **프로덕션 데이터베이스 생성**과 함께 **게시** 또는 **재게시**를 사용하는 경우
* 게시된 앱이 이전 공유 데이터베이스에 의존하는 경우 데이터를 수동으로 내보내고 가져오는 방법
* 다운타임, 활성 쓰기, 사용자 정의 PostgreSQL 역할에 대한 중요 주의 사항

## 자주 묻는 질문

<Accordion title="업그레이드 중 데이터가 안전한가요?">
  예. 데이터는 Neon에서 Helium으로 복사됩니다 — 전송 중에 이동되거나 삭제되지
  않습니다. 원본 Neon 데이터베이스는 업그레이드가 성공적으로 완료될 때까지
  보존됩니다. 데이터가 변경되거나 손실되지 않습니다.
</Accordion>

<Accordion title="업그레이드를 건너뛰거나 연기할 수 있나요?">
  업그레이드는 Replit 앱을 열면 자동으로 실행됩니다. 문제가 발생하면
  자동으로 건너뛰어 계속 정상적으로 작업할 수 있습니다. 업그레이드는 다음에 앱을
  열 때 재시도됩니다.
</Accordion>

<Accordion title="업그레이드에 실패했습니다. 어떻게 해야 하나요?">
  업그레이드에 실패하면 자동으로 건너뛰어 기존 Neon 데이터베이스로 앱을 계속
  사용할 수 있습니다. 시스템은 다음에 앱을 열 때 업그레이드를 재시도합니다.
  여러 번 시도해도 문제가 지속되면 지원을 위해 [고객 지원](https://replit.com/support)에
  문의하세요.
</Accordion>

<Accordion title="환경 변수가 변경된 이유는 무엇인가요?">
  업그레이드 후 `DATABASE_URL`은 Neon 대신 새 Helium 데이터베이스를 가리킵니다.
  이전 Neon 연결 문자열은 앱의 Secrets에 `NEON_DATABASE_URL`로 저장됩니다.
  코드가 `DATABASE_URL`을 사용하여 연결하는 경우, 변경이 필요하지 않습니다 —
  변수가 자동으로 업데이트됩니다.
</Accordion>

<Accordion title="PGHOST, PGPORT, PGUSER, PGPASSWORD는 어떻게 되었나요?">
  이 개별 환경 변수는 업그레이드 후 제거됩니다. Helium은 앱이 연결하는 데
  필요한 모든 정보를 포함하는 `DATABASE_URL` 환경 변수를 통해 연결 세부 정보를
  제공합니다. 이 개별 변수를 참조하는 코드를 `DATABASE_URL`을 사용하도록 업데이트하세요.
</Accordion>

<Accordion title="이전 Neon 데이터베이스에 여전히 접근할 수 있나요?">
  이전 Neon 연결 문자열이 참조용으로 앱의 Secrets에 `NEON_DATABASE_URL`로
  저장됩니다. 대부분의 경우, 이전 Neon 데이터베이스는 업그레이드 후 더 이상
  사용되지 않으며 **2026년 6월 8일**에 삭제될 예정입니다.

  배포된 앱이 포크 또는 리믹스된 앱의 이전 공유 Neon 데이터베이스를 사용하고 있는 경우, 데이터를 내보내고 자체 프로덕션 데이터베이스로 이동할 수 있도록 해당 Neon 데이터베이스에 임시로 접근할 수 있습니다. 이 접근은 임시적이며, 공유 데이터베이스는 **2026년 6월 8일**에 여전히 삭제될 예정이므로 가능한 빨리 게시된 앱을 업데이트하세요.

  Secrets에 `NEON_DATABASE_URL`이 없고 이전 연결 문자열 검색에 도움이 필요하면 [고객 지원](https://replit.com/support)에 문의하세요.
</Accordion>

<Accordion title="배포된 앱이나 프로덕션 앱에 영향이 있나요?">
  대부분의 경우 영향이 없습니다 — 프로덕션 데이터베이스는 별도로 관리되며 이
  업그레이드에 포함되지 않습니다. 단, 게시된 앱이 별도의 프로덕션 데이터베이스
  대신 개발 데이터베이스 URL을 직접 사용하는 경우 업그레이드가 게시된 앱에
  영향을 미칠 수 있습니다. 이는 포크 또는 리믹스된 이전 앱에서 가장 흔하며,
  포크가 원본 앱의 데이터베이스를 공유했습니다. 수정 방법은 [공유 데이터베이스를
  사용하는 게시된 앱 수정](/references/data-and-storage/shared-database-migration)을
  참조하세요.
</Accordion>

## 다음 단계

* [데이터베이스](/references/data-and-storage/sql-database): Replit 데이터베이스 도구와 데이터베이스 관리 방법 알아보기
* [프로덕션 데이터베이스](/references/data-and-storage/production-databases): 프로덕션 데이터베이스가 개발 데이터베이스와 어떻게 다른지 이해하기