[PostgreSQL/TimescaleDB] TimescaleDB 사용 중 hypertable 및 chunk 포함 전체 백업과 복원하기

TimescaleDB 사용 중 hypertable 및 chunk 포함 전체 백업과 복원하기

PostgreSQL에서 TimescaleDB 확장을 사용할 때, 일반적인 pg_dump 명령어를 사용해서 전체 데이터를 백업할 수 있습니다. 하지만 hypertable과 chunk가 일반 테이블과는 다르게 동작하기 때문에, 복원 시 문제가 생길 수 있습니다. 특히 restore 시에 chunk를 찾지 못한다는 오류가 발생하면 당황스럽죠. 이 글에서는 hypertable과 chunk를 포함한 전체 백업 및 복원 방법과 그 과정에서 자주 발생하는 문제점 및 해결법을 정리해봤습니다.

pg_dump를 이용한 전체 백업

TimescaleDB는 PostgreSQL의 확장이므로 pg_dump 명령만으로 hypertable, chunk, 메타데이터, constraint 등 모든 정보를 포함한 백업을 만들 수 있습니다. 추천하는 커맨드는 다음과 같습니다:

pg_dump -U <username> -h <host> -p <port> -d <dbname> -Fc -f backup.dump

• -Fc: 커스텀 포맷 (복원 시 유연하게 사용 가능)
• -f: 백업 파일 이름 지정
• <username>, <host>, <port>, <dbname>은 자신의 환경에 맞게 수정

이 명령은 hypertable, chunk, 인덱스, 제약조건 등 전체를 포함합니다.

복원 시 pg_restore 사용법

복원 전에 주의할 점은 복원 대상 데이터베이스에 TimescaleDB 확장이 먼저 설치되어 있어야 한다는 것입니다. 복원 전에 아래 명령을 실행해야 합니다:

CREATE EXTENSION IF NOT EXISTS timescaledb;

그 이후 다음과 같이 복원하면 됩니다:

pg_restore -U <username> -h <host> -p <port> -d <new_dbname> -Fc backup.dump

만약 chunk를 찾지 못한다는 오류가 발생하면 아래 원인들을 확인해보세요.

복원 시 chunk 오류 발생 시 확인할 사항

1. TimescaleDB 확장 설치 순서 문제

복원 전에 확장이 설치되지 않으면 chunk를 인식하지 못합니다. 반드시 pg_restore 전에 CREATE EXTENSION을 실행해야 합니다.

2. 복원 순서 문제

pg_restore가 schema보다 chunk를 먼저 복원하려고 하면 오류가 납니다. 이 경우 섹션을 지정해서 복원 순서를 명확히 할 수 있습니다:

pg_restore -U <username> -d <dbname> --section=pre-data --section=data --section=post-data -Fc backup.dump

하지만 보통은 기본 커맨드로도 dependency 순서를 자동 처리하므로 아래처럼 사용하는 걸 추천합니다:

pg_restore -U <username> -d <dbname> -Fc backup.dump

3. 백업 시 schema-only 또는 data-only 옵션 사용

백업할 때 --schema-only 또는 --data-only 옵션을 사용했다면 hypertable 메타데이터가 포함되지 않을 수 있습니다. 전체 백업을 사용해야 복원 시 문제가 생기지 않습니다.

4. TimescaleDB 버전 불일치

백업한 DB와 복원할 DB의 TimescaleDB 버전이 다르면 내부 구조가 달라져서 오류가 발생할 수 있습니다. 다음 쿼리로 버전을 확인하고 동일한 버전인지 점검하세요:

SELECT default_version, installed_version FROM pg_available_extensions WHERE name = 'timescaledb';

5. Docker나 RDS 환경에서의 문제

Docker에서는 컨테이너 내부에서 미리 확장을 설치해야 하고, AWS RDS 같은 매니지드 서비스에서는 shared_preload_libraries 설정이 필요할 수도 있습니다. 환경에 따라 TimescaleDB 사용 가능 여부와 확장 설치 방법을 사전에 확인하세요.

복원 후 hypertable과 chunk 확인

복원 후에는 아래 쿼리로 hypertable과 chunk가 잘 복원되었는지 확인할 수 있습니다:

-- hypertables
SELECT * FROM timescaledb_information.hypertables;

-- chunks
SELECT * FROM timescaledb_information.chunks;

dump 파일 직접 열어보기 (선택 사항)

만약 어떤 순서로 덤프가 되었는지 확인하고 싶다면 텍스트 포맷으로 덤프해보는 것도 좋은 방법입니다:

pg_dump -U <username> -d <dbname> -f dump.sql

dump.sql 파일을 열어보면 테이블, chunk, constraint 등이 어떤 순서로 정의되는지 확인할 수 있어 문제 해결에 도움이 됩니다.