8.4 KiB
구글 시트 설정을 PostgreSQL로 이전
이전 범위와 저장 구조
- 대상:
CS 통합 프로그램 설정스프레드시트의 설정 탭 전체. - 상품 그룹·상품 코드/이름/가격·정렬·구분선·소그룹 이름·사은품 규칙·문자 문구·배송비·폰트·송장 접두어를 보존한다.
- 같은 PostgreSQL 서버의 별도 DB
corm_db안에corm_settings테이블로 저장한다. DB 이름은SETTINGS_DB로 지정하며 기본값은corm_db이다. 기존ITEMCODE_DB와 코드표/CS 기록 테이블은 수정하지 않는다. - 설정 전체를 JSONB 배열로 저장하므로 행과 셀 순서를 보존한다. DB 버전을 함께 비교해 동시 저장의 조용한 덮어쓰기를 차단한다.
- DB 모드는 요청마다 작은 설정 문서 1건을 읽는다. 프로세스별 캐시 차이 없이 최신 커밋 값을 사용하며, 구글 요청/구글 작업 풀/구글 설정 캐시는 사용하지 않는다.
- DB 장애 시에는 503을 반환한다. 구글의 오래된 설정으로 자동 전환하지 않는다.
- DB 접속 정보와 API 비밀키는 계속
.env/환경변수에 둔다..env를 DB로 복사하는 처리는 없다. - 이 도구는
설정탭을 이전한다.문자내역,수동발주내역은 내역 DB 이전 절차에 따라 같은corm_db로 별도 이전한다.아이템코드탭은 사용하지 않는다. - 실제 수동발주 시트와 밀크런 등 다른 구글 연동에는 계속 구글 인증이 필요하다.
구글 시트의 탭과 DB 테이블을 반드시 1:1로 맞출 필요는 없다. 현재 업무 설정은 설정 탭 안에서
APP_SETTINGS, GROUP_NAMES, ORDER_*, SMS_GIFT_RULES 등의 분류로 구분되어 있다.
이 분류와 상품 순서를 그대로 저장하므로 하나의 corm_settings 테이블을 사용해도 설정이 서로 섞이지 않는다.
문자내역과 수동발주내역은 설정이 아닌 이력 데이터이므로 같은 DB 안의 corm_sms_history, corm_manual_history 테이블로 구분한다.
운영 서버 전환 순서
아래 명령은 Linux 운영 서버의 프로젝트 폴더(/opt/dbx-corm)에서 실행한다.
이 문서의 명령을 실행하기 전까지 현재 동작은 바뀌지 않는다. 기본값은 SETTINGS_BACKEND=google이다.
기존 .env를 예제 파일로 덮어쓰지 말고 필요한 항목만 추가한다.
먼저 PostgreSQL 관리 계정으로 같은 서버에 corm_db를 생성한다. 기존 DB는 이동하거나 변경하지 않는다.
아래는 앱 DB 계정이 king일 때의 SQL 예시다. 실제 POSTGRES_USER가 다르면 소유자를 맞춘다.
이미 DB가 있다면 생성 명령을 다시 실행하지 말고 소유자와 접근 권한을 확인한다.
CREATE DATABASE corm_db OWNER king;
앱 계정에 DB 생성 권한을 추가할 필요는 없다. 관리자가 DB를 생성하고 앱 계정에는 해당 DB 접근 및 테이블 생성/읽기/쓰기 권한을 부여한다.
앱과 이전 도구는 DB를 자동 생성하지 않는다.
이전 명령을 실행하기 전에 서버 .env에 아래 값을 추가한다. 이 단계에서는 저장소 모드는 google로 유지한다.
ITEMCODE_DB=itemcode_db
SETTINGS_DB=corm_db
SETTINGS_BACKEND=google
-
코드를 서버에 반영하고 새 이미지를 빌드한다. 기존 앱은 아직 구글 모드로 실행된다.
docker compose build corm-app -
원본 읽기 및 형식 점검을 실행한다. 이 명령은 DB에 접속하거나 데이터를 쓰지 않는다.
docker compose run --rm --no-deps corm-app python settings_migrate.py import -
직원에게 설정 편집을 잠시 멈추도록 알리고, 직접 시트 편집과 다른 구버전 앱의 설정 저장도 중단한다. 이전 완료 후 DB 모드로 기동할 때까지 이 상태를 유지한다. 현재 앱을 정지하고 원본 JSON을 서버 호스트에 백업한 뒤 DB에 저장한다.
mkdir -p .settings-backups docker compose stop corm-app docker compose run --rm --no-deps -v "$PWD/.settings-backups:/backups" corm-app python settings_migrate.py import --apply --backup /backups/before-postgres.json docker compose run --rm --no-deps corm-app python settings_migrate.py verifyverify가 원본과 DB 전체 행·셀·순서 일치를 출력해야 한다.--apply는 백업을 먼저 생성하고, 테이블 생성·최초 저장·전체 데이터 검증을 하나의 DB 트랜잭션으로 처리한다. 이미 DB 설정이 있거나 백업 경로가 존재하면 덮어쓰지 않고 중단한다. 실패하면 원인을 확인한다. DB가 비어 있는 경우에는 새 백업 경로로 다시 실행할 수 있다. -
이전·검증 완료 후 운영 서버
.env의 저장소 모드를 변경한다. DB 계정은corm_db에 테이블을 생성하고 읽고 쓸 수 있어야 한다.SETTINGS_DB=corm_db SETTINGS_BACKEND=postgres기존
POSTGRES_HOST,POSTGRES_PORT,POSTGRES_USER,POSTGRES_PASSWORD,ITEMCODE_DB와NAVER_*,CAFE24_*, 구글 인증 설정은 그대로 유지한다. -
앱을 기동하고 상태 및 실제 사용자 화면을 확인한다.
docker compose up -d --no-deps corm-app docker compose ps docker compose logs --tail=100 corm-app초기화되지 않은 DB에서는 시작이 실패한다. 먼저 이전이 완료되었는지 확인한다. 권한이 있는 직원으로 로그인해 상품 순서·가격·배송비·문자 문구를 확인하고, 설정 저장 후 새로고침으로 반영 여부를 확인한다. 저장 충돌이나 DB 장애 안내가 보이면 저장을 재시도하기 전에 새로고침한다. 브라우저 개발자 도구의
/api/config응답 헤더X-Settings-Backend: postgres로 저장소를 확인할 수 있다./health/db확인만으로 사용자 설정 조회·저장 검증을 대신하지 않는다.
이후 설정은 프로그램 화면에서 수정한다. 구글 시트 설정 탭의 변경은 DB에 자동 반영되지 않는다.
백업과 복구
정기 PostgreSQL 백업에 **corm_db**와 그 안의 corm_settings 테이블을 포함한다.
기존 itemcode_db만 백업하면 CORM 설정은 보관되지 않는다. 최신 설정을 JSON으로 내보낼 수도 있다.
docker compose run --rm --no-deps -v "$PWD/.settings-backups:/backups" corm-app python settings_migrate.py export --output /backups/current-settings.json
이 명령도 기존 파일은 덮어쓰지 않는다. 매번 새 파일명을 사용한다.
백업에는 업무 설정과 문자 문구가 있으므로 접근을 제한한다. .settings-backups/는 Git과 Docker 빌드에서 제외되어 있다.
파일을 호스트에 보관하려면 위와 같이 반드시 백업 디렉터리를 마운트한다.
빈 DB에 JSON 백업을 복구할 때는 다음 명령을 사용한다. 기존 DB 설정은 덮어쓰지 않는다.
docker compose run --rm --no-deps -v "$PWD/.settings-backups:/backups" corm-app python settings_migrate.py import --input-file /backups/current-settings.json --apply --backup /backups/before-restore.json
docker compose run --rm --no-deps -v "$PWD/.settings-backups:/backups" corm-app python settings_migrate.py verify --input-file /backups/current-settings.json
전환 직후 문제가 생기면 .env를 SETTINGS_BACKEND=google로 되돌리고 컨테이너를 재생성할 수 있다.
구글 시트 원본은 그대로 남아 있다. DB 전환 후 새로 저장한 내용은 구글에 복제되지 않으므로,
변경이 있었다면 우선 위 export로 최신 DB 설정을 보관한다. 단순 모드 복귀 시에는 구글에 남은 이전 값이 표시된다.
구글 모드에서 다시 수정한 내용을 기존 DB로 재이전하려면 별도로 차이를 검토해야 한다. 자동 덮어쓰기는 지원하지 않는다.
로컬 검증
python -m unittest discover -s tests -v
외부 연결 없이 설정 API·순서 보존·구글 작업 풀 분리·오류·충돌·백업/이전 절차를 검증한다.
실제 PostgreSQL 검증은 운영 DB가 아닌 폐기 가능한 테스트 DB의 DSN을 SETTINGS_TEST_DSN에 지정한 뒤 같은 명령을 실행한다.
통합 테스트는 매번 별도의 임시 스키마를 만들고 그 스키마만 제거한다. 테스트 계정에는 스키마 생성 권한이 필요하다.