[Fix] 필요한 WAL의 보관·외부 복사 완료 경계 검증

[Gimini-3]

목적

Refs #563

앞선 #562는 업로드 성공 응답 65건 중 33건만 복원했습니다. 외부에 동결된 WAL 끝까지만 재생됐으므로, 외부 복사의 완료 시각과 업무 데이터의 보존 범위가 다른 이유를 먼저 조사했습니다.

기존 격리 시험은 pg_switch_wal() 뒤 2초 대기와 archive-wal 한 번의 종료 코드 0으로 충분한 보관을 추정했습니다. 이번 변경은 필요한 WAL 파일이 실제로 보관되고 외부에서도 일치하는지 확인하는 선택적 완료 계약을 추가합니다. 공개 설정·개인 환경 파일은 변경하지 않습니다.

테스트 환경

• 실제 재현: OpenSQL 17.8의 소유 마커가 있는 전용 논리 DB, 실제 Barman 3.19.1 Docker 수집기와 새 카탈로그·터널입니다. 모델 서버·OpenProxy는 사용하지 않았습니다.
• 단위 시험: 로컬 Python에서 파일·시계·명령을 제어합니다. 실제 클라우드 결과와 구분합니다.
• LIVE2 재현은 Barman 로컬 보관 완료까지입니다. 실제 GCS의 generation 고정·재읽기 및 전체 복구는 이어지는 별도 결과에 기록합니다.
• 기존 Primary·Patroni·HBA·공개 Barman 설정, .env와 프런트엔드 개인 설정은 유지했습니다.

테스트 방법

1. 설치 이미지의 StreamingWalArchiver.get_next_batch()를 네트워크 없이 읽고 공식 동일 버전 소스와 대조했습니다.
2. marker 커밋 → WAL 전환 → 2초·archive 1회 후 정확한 대상 파일의 위치와 종료 코드를 함께 기록했습니다.
3. 첫 사례는 명시적 추가 쓰기 없이 최대 20초 대기했습니다. 이후 각 사례에서 다음 구간의 합성 restore point와 이름 기반 대기를 결합했습니다.
4. 새 sync --required-wal <24자리 WAL> --wait-timeout 120은 정확한 완성 파일만 기다리고, 기존 복사 뒤 원격 크기·CRC32C를 대조합니다. 실패 시 이전 성공 시각을 유지합니다.
5. 소유 DB·역할·수집기·터널·키를 정리하고 공개 설정 보존·원래 클러스터 상태를 확인했습니다.

변경 파일	역할
scripts/opensql/barman_offsite_sync.py	고정 대기 대신 필요한 완성 WAL을 제한 시간 내 확인. 명시적 옵션 사용 시 원격 무결성까지 완료 조건에 포함
scripts/opensql/test_barman_offsite_sync.py	지연 도착·partial 제외·시간 초과·잘못된 이름/시간·archive 오류·원격 누락·이전 성공 유지
.github/workflows/ci.yml	기존 복구 계약 CI에 WAL 외부 보존 계약 테스트 연결
docs/design/issue-563-wal-offsite-freshness.md	기존 복사 최근성과 특정 구간 최신성의 구분, 같은 복구 재시험의 사전 합격 기준
docs/test-results/wal-offsite-boundary-20261018/	개별 run 로그·준비 중단·실제 3사례·정리·비식별 파생물 해시

관측 결과

Run ID	결과	의미
WAL-ARCHIVE-BOUNDARY-20261018-LIVE1	INCOMPLETE, 수신기 준비 미완료	비교 미실행. 재현 횟수에서 제외. 정리 확인
WAL-ARCHIVE-BOUNDARY-20261018-LIVE2	기존 종료 코드 0은 3/3, 필요 파일 미보관 2/3	명령 성공이 필요한 WAL 보관 완료를 뜻하지 않았음
같은 LIVE2의 최종 이름 확인	3/3, 각각 16,777,216바이트	필요한 파일의 보관 상태 직접 확인
WAL-FRESHNESS-UNIT-20261018-R1	WAL 15/15, 실패 0	기존 8개·추가 7개 계약
WAL-RECOVERY-CONTRACT-20261018-R2	WAL 15/15·복구 40/40, 실패 0	최초 감사·Worker 활성화 순서 회귀 없음

상세 결과와 개별 증거

검증 과정에서 확인된 사항

• Barman은 수신기 재시작 위치를 위해 .partial이 없을 때 마지막 완성 파일을 streaming에 보류할 수 있습니다. 이 보호 동작은 제거하지 않았습니다. 수정 대상은 시험·호출자의 완료 판정입니다.
• 첫 사례는 20초 시간 초과가 아니라 6.966초 뒤 추가 쓰기 없이 도착했습니다. 고정 2초는 부족할 수 있으나 단순 대기가 항상 실패하거나 restore point가 항상 필수라고 결론 내리지 않습니다.
• LIVE1의 새 역할 수신 준비 문제는 정확한 인증 원인까지 확정하지 않았습니다. 공개 HBA를 바꾸지 않고 기존 검증된 인증 경로로 별도 LIVE2를 실행했습니다. 인증정보는 게시하지 않았습니다.
• 실제 재현에서는 공개 대기 함수를 실제 Docker Barman 명령에 연결했습니다. 전체 gsutil sync CLI를 클라우드에서 실행한 증거는 아닙니다. 원격 메타데이터 계약은 단위 시험이며, 전체 복구 재시험에서는 실제 GCS REST의 고정 generation 바이트를 읽어 대조합니다.
• 기존 인자 없는 타이머·health는 그대로 복사 최근성 검사입니다. 이번 변경만으로 운영 RPO 0이나 전체 65건 무손실을 주장하지 않습니다. 앞선 32건 전체의 원인을 동일 경합 하나로 소급 확정하지도 않습니다.
• 다음 복구 회차는 마지막 보존 완료 구간의 ACK 누락 0을 Worker 활성화 전에 검사하고, 그 뒤 요청은 별도 손실로 보고합니다. 마지막에 추가 복사를 해서 결과를 보충하지 않습니다.
• 공개 증거는 사전 비식별 검사를 통과한 20개 파생물만 포함합니다. 원본 설정·자격증명·인프라 식별정보는 포함하지 않습니다.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Repository: DocGrid/docgrid/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 8b43baf9-82e2-4b89-9bc1-c26ccf94806f

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Gimini-3]

변경 검토 기록

검토 대상 head: 44de876fb55a1c02cf9653ef863ccc21c4b40ba5

작성자가 전체 diff를 다시 검토했습니다. 별도 사람의 승인이나 자동 리뷰 완료로 표현하지 않습니다. CodeRabbit은 저장소 조건으로 자동 리뷰를 건너뛰었다고 응답했습니다.

• 기본 호출의 외부 복사·health 동작은 유지됩니다. 선택적 required-WAL 모드에서만 정확한 완성 파일 대기와 원격 무결성 조건이 추가됩니다.
• 잘못된 이름·무한/비정상 대기 값·partial·다른 파일은 완료로 처리하지 않습니다. 명령 오류·기한 초과·원격 누락은 이전 성공 시각을 유지하며 실패합니다.
• 실제 재현은 3사례 중 조기 판정 2사례, 이름 기반 최종 확인 3사례입니다. 첫 사례의 추가 대기는 6.966초의 도착이며 20초 시간 초과로 적지 않았습니다.
• 실제 로컬 보관 재현과 단위 원격 메타데이터 검증, 앞으로 수행할 전체 클라우드 복구를 구분했습니다. 기존 32건의 모든 원인을 하나로 소급 확정하지 않습니다.
• 공개 설정·개인 env 변경이 diff에 없습니다. 공개 파생물 20개는 인프라 식별값·인증정보·개인정보를 사전 제거하고 SHA-256 목록으로 대조했습니다.
• 로컬 WAL 15개·복구 계약 40개 테스트 통과, git diff --check 통과입니다. 병합은 필수 CI 완료와 현재 head 재확인 후 진행합니다.

현재 검토에서 병합을 막을 코드 문제는 발견하지 못했습니다.