> ## 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 제공업체)에서 **Helium**(Replit 자체의 관리형 PostgreSQL 인프라)으로 업그레이드하고 있습니다. 이 업그레이드는 자동으로 진행되며, 앱마다 한 번 실행되고, 모든 데이터를 보존합니다.
이 업그레이드는 **개발 데이터베이스**에만 적용됩니다. 게시된 앱이 사용하는
프로덕션 데이터베이스는 대부분의 경우 영향을 받지 않습니다. 하지만 게시된
앱이 다른 앱과 개발 데이터베이스를 공유하고 있다면(오래된 포크 또는 리믹스
앱에서 흔함), 중요한 조치가 필요하니 [공유 데이터베이스를 사용하는 게시된 앱
수정하기](/ko/features/data-and-storage/shared-database-migration)를
참고하세요.
## 무엇이 바뀌나요
이 업그레이드는 개발 데이터베이스를 Neon의 인프라에서 Replit 플랫폼 위에서 직접 실행되는 Helium으로 이전합니다. 이것이 여러분에게 의미하는 바는 다음과 같습니다.
* **더 낮은 지연 시간**: 데이터베이스가 앱과 함께 Replit 인프라에서 실행되어 연결 시간이 줄어듭니다
* **더 많은 저장 공간**: 저장 용량 한도가 10GB에서 20GB로 늘어납니다
* **동일한 데이터베이스 엔진**: Helium은 Neon과 동일한 버전인 PostgreSQL 16을 사용합니다 — 쿼리, 스키마, 데이터가 동일하게 작동합니다
* **원활한 연결**: `DATABASE_URL` 환경 변수가 Helium을 가리키도록 자동으로 업데이트됩니다
* **Neon 연결 정보 저장**: 이전 Neon 연결 문자열은 참고용으로 Secrets에 `NEON_DATABASE_URL`로 저장됩니다. 업그레이드 후 앱은 더 이상 이전 Neon 데이터베이스를 사용하지 않으며, 일정 유예 기간이 지나면 제거될 예정입니다.
레거시 Neon 데이터베이스와 새로운 Replit 데이터베이스 간의 전체 비교 — 청구, 복원 기능, 연결 보안, 리믹스 동작의 차이 포함 — 는 [레거시 개발 데이터베이스](/ko/features/data-and-storage/sql-database#legacy-development-database)를 참고하세요.
## 업그레이드 중 예상할 수 있는 사항
업그레이드는 Project Editor에서 Replit 앱을 열 때 자동으로 실행됩니다.
1. \*\*"Upgrading your database"\*\*라는 메시지와 함께 진행 화면이 표시됩니다
2. 데이터가 Neon에서 Helium으로 안전하게 복사됩니다. 전송 중에 데이터가 변경되거나 손실되지 않습니다.
3. 소요 시간은 데이터베이스 크기에 따라 다릅니다 — 대규모 데이터베이스의 경우 몇 분에서 몇 시간까지 걸릴 수 있습니다
4. 탭을 열어둘 수도 있고, 닫고 나중에 다시 돌아올 수도 있습니다
5. 업그레이드가 완료되면 \*\*"We've upgraded your database!"\*\*라는 확인 대화상자가 표시됩니다
업그레이드 중 문제가 발생하면 자동으로 건너뛰어 계속 작업할 수 있도록 합니다.
업그레이드는 다음에 앱을 열 때 다시 시도됩니다.
## 업그레이드 후 해야 할 일
대부분의 빌더에게는 별도의 조치가 필요하지 않습니다. 앱은 이전과 동일하게 계속 작동합니다.
코드가 `DATABASE_URL` 환경 변수를 사용하여 데이터베이스에 연결한다면, 변경할
필요가 없습니다. 이 변수는 새로운 Helium 데이터베이스를 가리키도록 자동으로
업데이트됩니다.
앱에 다음 중 해당하는 사항이 있다면 검토하세요.
* **하드코딩된 Neon 연결 문자열**: 코드가 `neon.tech` 연결 문자열을 직접 참조한다면, 대신 `DATABASE_URL` 환경 변수를 사용하도록 업데이트하세요 — JavaScript에서는 `process.env.DATABASE_URL`, Python에서는 `os.environ['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을 요구할 수 있음)에서는 SSL로 연결됩니다.
```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,
});
```
Drizzle, Prisma, Sequelize 같은 ORM을 사용한다면, SSL 설정을 조건부로 구성하는
방법을 해당 문서에서 확인하세요. 같은 원칙이 적용됩니다 — 개발 데이터베이스에서는
SSL을 비활성화하고 프로덕션에서는 활성화하세요.
## 공유 데이터베이스를 사용하는 게시된 앱
Replit에서 포크되거나 리믹스된 오래된 앱은 원본 앱과 개발 데이터베이스를 공유할 수 있습니다. 레거시 Neon 시스템에서는 앱을 포크하면 원본 앱의 `DATABASE_URL`이 복사되어, 두 앱과 그 게시된 버전이 동일한 데이터베이스에 연결되었습니다.
데이터베이스 업그레이드 후, 원본 앱의 Neon 데이터베이스는 비활성화됩니다. 게시된 앱이 여전히 그 공유 데이터베이스 URL을 사용하고 있다면, 게시된 앱이 작동을 멈추거나 데이터 접근 권한을 잃을 수 있습니다.
공유 데이터베이스는 **2026년 6월 8일**에 종료될 예정입니다. 영구적인 데이터 손실을
피하려면 그 전에 게시된 앱을 업데이트하세요.
### 다음 조치
게시된 앱이 영향을 받는다면, 전용 단계별 가이드를 따르세요.
* [공유 데이터베이스를 사용하는 게시된 앱 수정하기](/ko/features/data-and-storage/shared-database-migration)
이 가이드는 다음을 다룹니다.
* 게시된 앱이 여전히 이전 Neon 연결을 사용하고 있는지 확인하는 방법
* **Create production database**와 함께 **Publish** 또는 **Republish**를 언제 사용할지
* 게시된 앱이 여전히 이전 공유 데이터베이스에 의존하는 경우 데이터를 수동으로 내보내고 가져오는 방법
* 다운타임, 활성 쓰기 작업, 커스텀 PostgreSQL 역할에 대한 중요한 주의 사항
## 자주 묻는 질문
네. 데이터는 Neon에서 Helium으로 복사됩니다 — 전송 중에 이동되거나 삭제되지
않습니다. 원본 Neon 데이터베이스는 업그레이드가 성공적으로 완료될 때까지 보존됩니다.
데이터는 변경되거나 손실되지 않습니다.
업그레이드는 Replit 앱을 열 때 자동으로 실행됩니다. 문제가 발생하면 자동으로
건너뛰게 되며 평소처럼 계속 작업할 수 있습니다. 업그레이드는 다음에 앱을 열 때
다시 시도됩니다.
업그레이드가 실패하면 자동으로 건너뛰어져서 기존 Neon 데이터베이스로 앱을 계속
사용할 수 있습니다. 시스템은 다음에 앱을 열 때 업그레이드를 다시 시도합니다.
여러 번 시도해도 문제가 지속된다면 [지원팀에 문의](https://replit.com/support)하세요.
업그레이드 후 `DATABASE_URL`은 Neon 대신 새로운 Helium 데이터베이스를
가리킵니다. 이전 Neon 연결 문자열은 앱의 Secrets에 `NEON_DATABASE_URL`로
저장됩니다. 코드가 `DATABASE_URL`을 사용하여 연결한다면 변경할 필요가 없습니다
— 이 변수는 자동으로 업데이트됩니다.
이 개별 환경 변수들은 업그레이드 후 제거됩니다. Helium은 앱이 연결하는 데
필요한 모든 정보를 담은 `DATABASE_URL` 환경 변수를 통해 연결 세부 정보를
제공합니다. 이 개별 변수를 참조하는 코드는 `DATABASE_URL`을 사용하도록
업데이트하세요.
이전 Neon 연결 문자열은 참고용으로 앱의 Secrets에 `NEON_DATABASE_URL`로
저장됩니다. 대부분의 경우, 업그레이드 후 이전 Neon 데이터베이스는 더 이상
사용되지 않으며 **2026년 6월 8일**에 제거될 예정입니다.
게시된 앱이 포크되거나 리믹스된 앱의 오래된 공유 Neon 데이터베이스를 사용하고
있었다면, 데이터를 내보내고 자체 프로덕션 데이터베이스로 이전할 수 있도록 해당
Neon 데이터베이스가 일시적으로 계속 사용 가능할 수 있습니다. 이 접근은 임시적이며,
공유 데이터베이스는 여전히 **2026년 6월 8일**에 제거될 예정이므로 가능한 한 빨리
게시된 앱을 업데이트하세요.
Secrets에 `NEON_DATABASE_URL`이 없고 이전 연결 문자열을 복구하는 데 도움이
필요하다면, [지원팀에 문의](https://replit.com/support)하세요.
대부분의 경우 그렇지 않습니다 — 프로덕션 데이터베이스는 별도로 관리되며 이
업그레이드의 대상이 아닙니다. 하지만 게시된 앱이 (별도의 프로덕션 데이터베이스
대신) 개발 데이터베이스 URL을 직접 사용한다면, 업그레이드가 게시된 앱에 영향을
줄 수 있습니다. 이는 포크되거나 리믹스된 오래된 앱에서 가장 흔하며, 이런
경우 포크가 원본 앱의 데이터베이스를 공유했습니다. 해결 방법은 [공유
데이터베이스를 사용하는 게시된 앱
수정하기](/ko/features/data-and-storage/shared-database-migration)를
참고하세요.
## 다음 단계
* [Database](/ko/features/data-and-storage/sql-database): Replit Database 도구와 데이터베이스 관리 방법을 알아보세요
* [프로덕션 데이터베이스](/ko/features/data-and-storage/production-databases): 프로덕션 데이터베이스가 개발 데이터베이스와 어떻게 다른지 알아보세요