ClickPipes의 데이터 소스를 사용한 PostgreSQL 데이터 마이그레이션

ClickPipes를 사용하여 PostgreSQL 데이터베이스를 ClickHouse Managed Postgres로 마이그레이션하는 방법을 알아봅니다.

이제 ClickHouse Cloud는 외부 PostgreSQL 데이터베이스를 Managed Postgres 서비스로 마이그레이션할 수 있도록 ClickPipes를 제공합니다. 이 기본 제공 통합을 사용하면 원본 데이터베이스에 연결하고, 스키마를 내보내고, 이를 Managed Postgres로 가져오고, 지속적 복제를 설정하는 작업을 간편하게 수행할 수 있습니다.

​

사전 준비 사항

• 복제 권한이 있는 사용자로 원본 PostgreSQL 데이터베이스에 접근할 수 있어야 합니다. 원본에 해당하는 설정 가이드를 따르십시오.
  • Amazon RDS Postgres
  • Amazon Aurora Postgres
  • Supabase Postgres
  • Google Cloud SQL Postgres
  • Azure Flexible Server for Postgres
  • Neon Postgres
  • Crunchy Bridge Postgres
  • TimescaleDB
  • 기타 provider 또는 자체 호스팅 instance의 경우 Generic Postgres Source
• 마이그레이션 대상으로 사용할 ClickHouse Managed Postgres 서비스가 필요합니다. 아직 없다면 quickstart를 참조하십시오.
• 로컬 머신에 pg_dump와 psql이 설치되어 있어야 합니다. 둘 다 기본 PostgreSQL 클라이언트 도구에 포함되어 있습니다.

​

마이그레이션 전에 고려할 사항

• DDL 전파: 지속적 복제(CDC)에서는 DML 작업과 ADD COLUMN을 포착합니다. DROP COLUMN 및 ALTER COLUMN 같은 다른 DDL 변경 사항은 전파되지 않으므로 대상에 수동으로 적용해야 합니다.

마이그레이션 중 문제가 발생하면 일반적인 오류와 해결 방법은 Managed Postgres Migrations FAQ에서 확인하십시오.

​

1단계: 원본 데이터베이스에 연결

ClickHouse Cloud 콘솔을 열고 Managed Postgres 서비스를 선택합니다.

왼쪽 사이드바에서 데이터 소스를 클릭합니다.

Start import를 클릭합니다.

원본 PostgreSQL 데이터베이스의 연결 정보를 입력합니다: 호스트, 포트, 사용자 이름, 비밀번호, 데이터베이스 이름. 원본 데이터베이스에서 필요하면 TLS를 활성화합니다.

원본 데이터베이스에 대한 비공개 연결이 필요하면 SSH tunneling을 선택하고 필요한 SSH 정보를 입력할 수 있습니다. 이렇게 하면 공개적으로 접근할 수 없는 데이터베이스에도 마이그레이션이 안전하게 연결할 수 있습니다.

수집 메서드를 선택합니다:

• Initial load + CDC — 기존 데이터를 복사한 다음, 이후 변경 사항도 계속 반영하여 대상을 동기화 상태로 유지합니다.
• Initial load only — 한 번만 복사하고, 이후 복제는 수행하지 않습니다.
• CDC only — 초기 복사를 건너뛰고 이 시점 이후의 새 변경 사항만 복제합니다.

다음을 클릭합니다.

​

자동 스키마 마이그레이션

이 옵션을 선택하면 ClickPipe가 생성된 후 Setup 단계에서 원본 데이터베이스의 스키마를 자동으로 가져와 Managed Postgres 서비스에 적용합니다.

이 기능은 이후 마법사에서 선택하는 테이블과 관계없이 원본 데이터베이스의 모든 데이터베이스 객체를 가져오므로 비어 있는 대상 데이터베이스가 필요합니다. 대상 데이터베이스에 기존 데이터가 있거나 더 세부적인 구성이 필요하다면 수동 모드를 선택해야 합니다.

드롭다운에서 대상 데이터베이스를 선택하거나 새 데이터베이스 만들기를 클릭하여 새 데이터베이스를 프로비저닝합니다.

​

모니터링

ClickPipes 세부 정보 보기에서 스키마 마이그레이션 진행 상황을 확인할 수 있습니다. 로그에는 스키마 마이그레이션 상태와 발생한 오류가 표시됩니다.

이 모드에는 다음과 같은 제한 사항이 있습니다.

• SSH tunneling을 사용하는 파이프에는 자동 스키마 마이그레이션을 사용할 수 없습니다. 스키마는 수동으로 내보내고 가져와야 합니다.

​

수동 스키마 마이그레이션

대상 데이터베이스에 이미 데이터가 있거나 자동화 모드에서 전제하는 초기 상태 대신 더 맞춤화된 설정이 필요한 경우, 여기에서 수동 모드를 선택할 수 있습니다.

​

데이터베이스 스키마 내보내기

마법사에 원본 연결 정보가 미리 입력된 pg_dump 명령이 표시됩니다. 터미널에서 실행합니다:

pg_dump \
  -h <source_host> \
  -U <source_user> \
  -d <source_database> \
  --schema-only \
  -f pg.sql

이 명령을 실행하면 현재 디렉터리에 pg.sql이 생성됩니다.

다음을 클릭합니다.

​

Managed Postgres 서비스로 스키마 가져오기

드롭다운에서 대상 데이터베이스를 선택하거나 새 데이터베이스 만들기를 클릭해 새 데이터베이스를 프로비저닝합니다.

마법사에 스키마 덤프를 Managed Postgres 서비스에 적용하는 psql 명령이 표시됩니다. 터미널에서 실행합니다:

psql \
  -h <target_host> \
  -p 5432 \
  -U <target_user> \
  -d <target_database> \
  -f pg.sql

다음을 클릭합니다.

​

Step 4: 수집 설정 구성

논리적 복제에 사용할 publication을 지정합니다. 비워 두면 publication이 자동으로 생성됩니다.

처리량을 조정하려면 고급 복제 설정을 펼치십시오.

설정	기본값	설명
동기화 인터벌(초)	10	replication slot을 폴링하는 주기
초기 적재용 병렬 스레드 수	4	대량 복사 단계에 사용하는 스레드 수
Pull 배치 크기	100,000	복제 배치마다 가져오는 행 수
스냅샷 파티션당 행 수	100000	대형 테이블 스냅샷의 파티션 크기
병렬 스냅샷 테이블 수	1	동시에 스냅샷하는 테이블 수

다음을 클릭하십시오.

​

5단계: 테이블 선택

복제할 테이블을 선택하세요. 테이블은 스키마별로 그룹화되어 있습니다. 개별 테이블을 선택하거나 스키마를 펼쳐 전체를 선택하세요.

Create migration을 클릭하세요.

​

마이그레이션 모니터링

마이그레이션을 생성하면 데이터 소스에 Running 상태로 표시됩니다.

마이그레이션을 클릭하면 상세 보기가 열립니다. Tables 탭에는 처리된 행 수, 파티션, 파티션당 평균 시간 등 각 테이블의 초기 적재 진행 상황이 표시됩니다. Metrics 탭에는 CDC가 시작되면 복제 지연과 처리량이 표시됩니다.

​

트래픽 전환

초기 적재가 완료되고, CDC를 사용하는 경우 복제 지연(replication lag)이 거의 0에 가까워지면 소스 Postgres 데이터베이스에서 Managed Postgres 서비스로 트래픽을 전환할 수 있습니다. 마이그레이션 상세 보기를 열고 마이그레이션 후 steps 탭을 선택하십시오. 이 가이드형 마법사는 마이그레이션을 안전하게 마무리하는 데 필요한 여섯 단계를 안내합니다. 각 단계는 순서대로 완료해야 다음 단계로 진행할 수 있습니다.

​

1단계: 소스 Postgres 데이터베이스를 읽기 전용 모드로 설정

cutover 도중 데이터가 어긋나지 않도록 소스에서 애플리케이션의 쓰기 작업을 중단하십시오. 마법사에는 원본 데이터베이스 이름이 미리 채워진 ALTER DATABASE 명령이 표시되며, 이를 원본 데이터베이스에서 실행하십시오:

ALTER DATABASE "<source_db>" SET default_transaction_read_only = on;

그런 다음 기존 연결을 모두 종료하여 읽기 전용 설정이 적용되도록 하고, 진행 중인 쓰기 작업이 남아 있지 않게 합니다:

SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE datname = '<source_db>'
  AND pid <> pg_backend_pid();

사용 중인 Postgres 공급자에 따라 이 단계는 다르게 보일 수 있습니다. 관리형 서비스에서는 ALTER DATABASE나 백엔드 종료를 제한하는 대신, 자체 콘솔이나 파라미터 그룹, 또는 쓰기 권한 회수를 통해 읽기 전용 모드를 제공하기도 합니다. 원본을 읽기 전용으로 설정하는 동등한 방법은 해당 공급자의 문서를 참조하십시오.

계속하려면 Mark as completed를 클릭하십시오.

​

2단계: 행 수 검사

검사할 복제된 테이블을 선택합니다. ClickPipes는 선택한 모든 테이블의 행 수를 소스와 타깃 양쪽에서 집계하여 비교합니다. 대용량 테이블은 근사치가 반환될 수 있습니다. 모든 테이블을 검사하려면 Select all tables를 사용하고, 특정 테이블만 검사하려면 해당 테이블을 검색해 선택한 후 Count rows를 클릭하십시오.

​

3단계: 파이프 일시 중지

시퀀스를 재설정하고 트래픽을 전환하기 전에 복제가 중지되도록 ClickPipe를 일시 중지합니다. Pause ClickPipe를 클릭한 후 파이프가 일시 중지될 때까지 기다린 다음 진행하십시오.

​

4단계: 시퀀스 재설정

이후의 삽입 작업이 올바른 값에서 이어지도록 대상에서 시퀀스를 재설정합니다. Reset sequences를 클릭하면 각 시퀀스가 해당 테이블의 현재 최대값에 맞춰집니다.

​

5단계: 트래픽 전환

애플리케이션의 데이터베이스 URL을 Managed Postgres 연결 문자열(connection string)로 변경하여 읽기와 쓰기를 Managed Postgres 서비스로 전환하십시오. 마법사는 url, psql, env, yaml, jdbc 등 여러 포맷으로 연결 정보(connection details)를 제공하므로, 사용 중인 스택에 맞는 항목을 복사해 사용하면 됩니다. 애플리케이션을 업데이트한 후 Mark as completed를 클릭하십시오.

​

6단계: 정리

전환을 완료하고 새 서비스가 정상 상태임을 확인했다면, migration을 삭제하고 소스 리소스를 해제하십시오. 마법사에는 슬롯 이름이 미리 채워진 pg_drop_replication_slot 명령이 표시됩니다. 소스에서 이 명령을 실행하여 replication slot을 삭제하십시오:

SELECT pg_drop_replication_slot('<slot_name>');

그런 다음 Delete ClickPipe migration을 클릭하여 데이터 소스에서 해당 마이그레이션을 제거합니다.

​

다음 단계

• Managed Postgres 빠른 시작
• Managed Postgres 연결 정보
• ClickPipes Postgres FAQ