리전 마이그레이션

프로젝트를 다른 리전으로 이동 — 무엇이 마이그레이션되는지, 관리형 흐름, 그리고 오늘 작동하는 수동 pg_dump 런북.

리전 마이그레이션 은 기존 프로젝트를 생성된 리전 에서 다른 리전으로 이동합니다. 트래픽이 다른 리전에 더 가까워졌을 때(왕복 지연 시간 감소), 또는 컴플라이언스나 데이터 레지던시 요구사항이 데이터가 특정 관할권에 있어야 한다고 규정할 때 사용합니다.

마이그레이션은 데이터가 어디에 있는지를 바꾸지, 데이터가 무엇인지 를 바꾸지 않습니다. 브랜치, 롤, 데이터베이스, 그리고 그 안의 행이 모두 함께 옮겨집니다. 클라이언트 측에서 바뀌는 유일한 것은 연결 문자열의 호스트 입니다 — 프로젝트가 대상 리전의 새 엔드포인트 호스트에 안착하므로, 전환이 완료되면 DATABASE_URL 을 한 번 다시 가리켜야 합니다.

How it works

관리형 마이그레이션은 사용자가 명시적으로 승인하는 전환을 동반한, 제어되고 검증된 복사로 실행됩니다. 단계는 다음과 같습니다.

동결 — 복사가 일관되고 움직이지 않는 대상을 갖도록, 원본 프로젝트를 잠시 읽기 전용 / 일시 중단 상태로 둡니다.
덤프 — 원본 리전에서 모든 브랜치의 논리 덤프를 취합니다.
전송 — 덤프를 TLS를 통해 대상 리전으로 이동합니다.
복원 — 덤프를 대상 리전에 새로 프로비저닝된 프로젝트로 복원합니다.
검증 — 대상이 원본과 바이트 단위로 동등한지 확인합니다. 스키마 핑거프린트, 테이블별 행 수, 콘텐츠 체크섬이 모두 일치해야 마이그레이션이 전환용으로 제시됩니다.
확인 — 자동으로 전환되는 것은 없습니다. 검증 결과를 검토하고 전환을 명시적으로 확인합니다.
전환 — 프로젝트의 활성 엔드포인트가 대상 리전으로 다시 가리켜집니다. 연결 문자열 호스트가 바뀝니다.

전환 전에 취소하거나 어느 단계에서든 검증이 실패하면 마이그레이션은 롤백 됩니다. 대상 골격은 폐기되고 원본 프로젝트는 읽기 전용 상태에서 빠져나와 변경되지 않은 채로 남습니다.

Size guidance

읽기 전용 윈도우는 데이터 크기에 따라 확장됩니다.

10 GB 미만 — 일반적으로 15분 이내에 완료됩니다.
10–100 GB — 확장된 윈도우. 더 긴 읽기 전용 기간을 계획하고 피크 시간 외에 일정을 잡으세요.
100 GB 초과 — 지원이 따르는 마이그레이션은 지원에 문의 하세요. 대규모 프로젝트는 셀프서비스 흐름이 아니라 직접 수행하는 런북으로 마이그레이션됩니다.

Managed migration (console)

관리형 리전 마이그레이션은 점진적으로 출시 중 입니다. 여기서 설명하는 마법사는 순차적으로 활성화되고 있습니다. 프로젝트 설정에 아직 Migrate region 이 보이지 않으면 아래의 수동 런북 을 사용하세요. 이는 오늘 모든 프로젝트에서 작동합니다.

콘솔 마법사는 위 흐름을 안내합니다.

프로젝트를 열고 Settings → Migrate region 으로 이동합니다.
대상 선택 — 드롭다운에서 대상 리전을 선택합니다. 현재 리전이 참고용으로 표시됩니다.
영향 검토 — 마법사가 곧 일어날 일을 요약합니다. 프로젝트가 겪을 읽기 전용 윈도우, 그리고 전환 시 연결 문자열 호스트가 바뀐다는 사실입니다.
진행 상황 모니터링 — 각 브랜치가 덤프 → 전송 → 복원의 진행 상황을 개별로 표시합니다. 마이그레이션이 실행되는 동안 마법사가 상태를 스트리밍합니다.
검증 검토 — 복사가 완료되면 검증 결과가 브랜치별로 표시됩니다. 스키마 핑거프린트 일치, 행 수 일치, 체크섬 일치입니다.
전환 확인 — 검증이 녹색이 되면 전환을 확인합니다. 이것이 자동으로 되돌릴 수 없는 지점입니다.
DATABASE_URL 업데이트 — 전환 후, 엔드포인트 카드에서 새 연결 문자열을 복사하여 애플리케이션의 DATABASE_URL 을 업데이트합니다. 호스트가 바뀌었습니다. 나머지는 모두 동일합니다.

Manual migration runbook

이 런북은 오늘, 어떤 플랜에서든 작동합니다. 표준 Postgres 도구와 공개 연결 문자열을 사용하므로 관리형 흐름에 의존하지 않습니다. 형태는 다음과 같습니다. 대상 리전에 새 프로젝트를 세우고, pg_dump / pg_restore 로 데이터를 복사하고, 검증한 다음, 다시 가리키고 이전 프로젝트를 삭제합니다.

1. Create the destination project

대상 리전 에 새 프로젝트를 생성합니다(콘솔 New project, 또는 API). 원본 프로젝트의 Postgres 메이저 버전을 맞춥니다. 엔드포인트 카드에서 새 프로젝트의 연결 문자열을 기록해 둡니다.

2. Dump the source

원본 프로젝트의 연결 문자열에서 custom 형식으로 덤프합니다. --no-owner 와 --no-privileges 는 대상에서 새로 생성된 롤 전반에 걸쳐 덤프를 이식 가능하게 유지합니다.

pg_dump \
  --format=custom \
  --no-owner \
  --no-privileges \
  "postgresql://app:SOURCE_PWD@ep_SOURCE.kisenon.com:5432/main?sslmode=require" \
  --file=migration.dump

3. Restore into the destination

대상 프로젝트의 연결 문자열로 복원합니다. --single-transaction 에 --exit-on-error 를 더하면 복원이 전부-아니면-전무가 됩니다. 무언가 실패하면 대상은 절반만 로드되는 대신 깨끗한 상태로 남습니다.

pg_restore \
  --no-owner \
  --no-privileges \
  --single-transaction \
  --exit-on-error \
  --dbname "postgresql://app:DEST_PWD@ep_DEST.kisenon.com:5432/main?sslmode=require" \
  migration.dump

4. Verify

전환하기 전에 대상이 원본과 일치하는지 확인합니다. 두 연결 문자열에 대해 테이블별 행 수를 비교합니다.

SELECT relname, n_live_tup
FROM pg_stat_user_tables
ORDER BY relname;

더 강력한 점검을 위해, 가장 중요한 테이블에서 콘텐츠 체크섬을 표본 점검합니다. 이를 원본과 대상 양쪽에 대해 실행하고 결과를 비교합니다.

SELECT md5(string_agg(t::text, '' ORDER BY t)) AS checksum
FROM my_table AS t;

행 수와 체크섬이 일치하면 데이터가 온전히 옮겨진 것입니다.

5. Cut over and clean up

애플리케이션의 DATABASE_URL 을 대상 연결 문자열로 다시 가리킵니다. 새 프로젝트에 대해 애플리케이션이 정상임을 확인했으면, 과금을 멈추기 위해 이전 프로젝트를 삭제합니다.

keon projects delete <old-project-id>

프로젝트 삭제는 되돌릴 수 없습니다 — 대상을 검증하고 모든 트래픽을 그쪽으로 전환한 후에만 수행하세요.

FAQ

How much downtime should I expect?

관리형 마이그레이션의 경우, 유일한 중단은 복사 중의 읽기 전용 윈도우입니다. 쓰기는 일시 중지되고 읽기는 계속됩니다. 윈도우는 데이터 크기에 따라 확장됩니다(크기 가이드 참조). 10 GB 미만 프로젝트는 15분 미만, 더 큰 것은 더 깁니다. 수동 런북의 경우, 다운타임은 덤프, 복원, 검증을 하는 동안 쓰기를 멈추기 위해 선택한 윈도우입니다.

Can I cancel a migration?

예 — 최종 전환 전 이라면 언제든지. 취소하면 대상 골격이 폐기되고 원본 프로젝트가 정상으로 돌아갑니다. 전환을 확인하기 전까지 원본은 결코 변경되지 않으므로, 취소하면 시작한 그 지점에 정확히 그대로 남습니다.

What happens to my branches?

모든 브랜치가 마이그레이션됩니다. 논리 덤프 앤 복원이 카피 온 라이트 이력을 평탄화 한다는 점에 유의하세요. 각 브랜치는 현재 데이터와 함께 옮겨지지만, 자식 브랜치와 그 부모 사이의 fork-at-LSN 관계는 보존되지 않습니다 — 대상 브랜치는 페이지를 공유하는 대신 마이그레이션된 데이터에서 새로 시작합니다. 데이터는 온전하지만, 공유 스토리지 계보는 그렇지 않습니다.

Do my passwords and roles survive?

롤은 대상 프로젝트를 세우는 과정의 일부로 다시 생성되고, 그들이 소유한 데이터는 옮겨집니다. 수동 런북은 --no-owner --no-privileges 로 덤프하므로, 롤 소유권과 그랜트는 덤프로 이전되지 않습니다 — 대상에서 다시 적용합니다. 롤/비밀번호 동일성은 자동적인 것으로 여기지 말고, 마이그레이션 후 검증하고 다시 확립할 대상으로 다루세요. 관리형 흐름은 프로젝트의 롤을 대신 다시 생성하지만, 동일한 주의가 적용됩니다. 전환 전에 애플리케이션의 로그인 롤과 비밀번호가 대상에서 작동하는지 확인하세요.

Do my connection strings change?

예 — 호스트 가 바뀝니다. 프로젝트가 대상 리전의 새 엔드포인트 호스트로 이동하기 때문입니다. 전환 시 한 번 DATABASE_URL(및 호스트가 하드코딩된 다른 모든 곳)을 업데이트합니다. API 키(nsk_…)는 계정 범위이며 리전 마이그레이션의 영향을 받지 않습니다.

Is my data encrypted in transit?

예. 리전 간 전송은 TLS를 통해 실행되며, 원본에서의 덤프와 대상으로의 복원 모두 연결 문자열 에 설명된 표준 sslmode=require Postgres 연결을 사용합니다.

리전 — 마이그레이션의 출발지와 도착지 카탈로그.
프로젝트 — 전체로서 마이그레이션되는 단위.
연결 문자열 — 전환 시 호스트가 바뀌는 와이어 형식.
브랜치 — 카피 온 라이트 자식, 그리고 덤프/복원이 그 계보에 미치는 영향.

리전 마이그레이션

On this page