데이터 관리

이 문서에서는 Sudapapa Diary의 데이터 저장 구조와 백업·복원·이전·초기화 절차를 자세히 다룹니다.

데이터 저장 구조

모든 사용자 데이터는 Windows 사용자 폴더 아래 다음 위치에 저장됩니다.

• Directory%APPDATA%/sudapapadiary

  • DirectoryConfigurations

    • DirectoryDatabase

      • sudapapa.db (메인 SQLite DB)
    • DirectoryBackups

      • Directoryjson-backup-YYYY-MM-DDTHH-MM-SS/

        • …
      • Directorydb-backup-YYYY-MM-DDTHH-MM-SS/

        • …
      • Directorymigration-backup-YYYY-MM-DDTHH-MM-SS/

        • …
    • Connections (구버전 JSON, 호환성 유지용)
    • Calendars (구버전 JSON, 호환성 유지용)
    • Passwords (구버전 JSON, 호환성 유지용)
    • Defaults (기본값 시드)
    • migration-status.json (마이그레이션 상태)
• Directory%APPDATA%/SudapapaDiary

  • license-server.db (라이선스 서버 캐시)
• %APPDATA%/sudapapadiary/Logs (옵션 - 디버그 로그)

%APPDATA%는 일반적으로 C:\Users\<사용자>\AppData\Roaming 입니다.

빠른 접근

다음 방법으로 데이터 폴더를 빠르게 열 수 있습니다.

• 윈도우 탐색기 주소창에 %APPDATA%\sudapapadiary 입력
• 트레이 메뉴 → 앱 정보 → 데이터 폴더 열기 (있는 경우)

DB 스키마 개요

sudapapa.db는 다음 핵심 테이블로 구성됩니다.

테이블	용도
calendars	캘린더 메타(이름·색·소스 등)
events	일정 본문·반복 규칙·알람
connections	OAuth 연결(Google·Microsoft·Kakao·Naver)
passwords	비밀번호 매니저 항목 (암호화)
memos	메모 위젯 본문 (인스턴스별 행)
quick_access_instances	즐겨찾기 위젯 인스턴스·항목
favorites_qa	QuickAccess 즐겨찾기
holidays	국가별 공휴일 캐시
lunar_events	음력 일정·기념일
settings	환경설정 키-값 저장
subscription	구독·라이선스 로컬 캐시
weather_cache	날씨 정보 캐시
naver_* (별도)	네이버 캘린더 데이터

스키마는 apps/desktop/src/main/database/schema/ 아래 001_initial_schema.sql ~ 010_add_naver_provider.sql 마이그레이션 파일로 관리됩니다.

Note

better-sqlite3(WAL 모드, 외래키 ON)로 작동하며 동기 트랜잭션을 사용합니다. 기본 인덱스·트리거·뷰는 별도 SQL로 자동 적용됩니다.

자동 마이그레이션

앱이 시작될 때 다음 절차가 자동으로 실행됩니다.

1. 버전 확인 — 현재 DB 스키마와 코드 기대 버전 비교
2. 체크포인트 로드 — migration-status.json에서 마지막 성공 단계 확인
3. 백업 생성 — migration-backup-* 디렉터리에 마이그레이션 전 상태 저장
4. 마이그레이션 실행 — JSON → SQLite 또는 스키마 업그레이드
5. 검증 — 행 수·필수 컬럼·외래키 무결성 확인
6. 체크포인트 갱신 — 성공 시 다음 단계로, 실패 시 롤백 가능

마이그레이션 실패 시 자동 백업으로 롤백할 수 있도록 Backups/migration-backup-* 폴더가 보존됩니다.

마이그레이션 종류

유형	트리거	백업 폴더
JSON → SQLite	첫 실행 또는 구버전에서 업그레이드	migration-backup-*
스키마 업그레이드	새 SQL 파일 추가 시	db-backup-*
OAuth 토큰 형식 변경	인증 모듈 업데이트	자동 처리
키체인 마이그레이션	파일 키 → Windows 자격 증명 관리자	자동 처리

백업

자동 백업

다음 시점에 백업이 자동 생성됩니다.

• 마이그레이션 직전 — Configurations/Backups/migration-backup-<timestamp>/
• DB 변경 직후 일부 작업 — 필요한 경우 db-backup-<timestamp>/

기본 보관 개수: 최근 5개. 그 이상은 자동 삭제됩니다(BackupManager의 maxBackups).

수동 백업 (전체 설정 내보내기)

가장 안전하고 권장되는 방법입니다.

1. 트레이 → 설정 → 환경설정 → 설정 백업 영역으로 이동합니다.
2. 설정 내보내기 버튼을 클릭합니다.
3. 백업을 보호할 암호를 입력합니다(8자 이상, 특수문자 1개 이상).
4. 저장 위치를 선택합니다(외장 드라이브·OneDrive·Google Drive 권장).
5. 결과 파일은 AES-256-GCM 암호화된 단일 파일이며, 매직 바이트 SDPB로 식별됩니다.

백업 파일에 포함되는 데이터:

• 모든 일정·메모·즐겨찾기
• 비밀번호 매니저 (암호화 상태로)
• OAuth 연결 정보
• 환경설정 전체
• 위젯 위치·크기·테마 설정

데이터 폴더 직접 복사 (고급)

앱을 종료한 상태에서 %APPDATA%\sudapapadiary 폴더 전체를 복사하는 방법입니다. 가장 정확하지만, OS 자격 증명 관리자에 저장된 키는 함께 복사되지 않습니다.

Caution

실행 중에는 SQLite WAL 파일이 잠겨 있어 복사가 일관되지 않을 수 있습니다. 반드시 트레이에서 완전 종료(우클릭 → 종료) 후 복사하세요.

복원

백업 파일에서 복원

1. 트레이 → 설정 → 환경설정 → 설정 백업 영역에서 설정 불러오기 클릭
2. 백업 파일(.sdpb 등)을 선택
3. 백업 시 입력한 암호 입력
4. 복원 후 앱이 자동 재시작

자동 백업 폴더에서 복원

1. 앱을 완전히 종료합니다.
2. Configurations/Backups/의 원하는 시점 백업 폴더(예: db-backup-2026-04-21T10-30-00)를 엽니다.
3. 그 안의 sudapapa.db(또는 JSON 폴더들)을 Configurations/Database/sudapapa.db로 덮어쓰기 복사합니다.
4. 앱을 다시 실행하면 해당 시점 데이터로 복원됩니다.

Caution

복원 직전의 현재 상태가 필요하면 먼저 수동 내보내기로 보존하세요.

다른 PC로 이전

같은 사용자가 새 PC로 옮기는 경우 다음 절차를 권장합니다.

1. 기존 PC: 트레이 → 설정 → 설정 내보내기로 백업 파일 생성
2. 백업 파일을 외장 드라이브 또는 클라우드로 옮기기
3. 새 PC: Sudapapa Diary 설치 후 첫 실행
4. 트레이 → 설정 → 환경설정 → 설정 불러오기로 백업 파일 선택
5. 암호 입력 → 자동 재시작
6. OAuth 재인증: Google·Microsoft·Kakao·Naver 계정은 새 PC에서 다시 로그인 필요
7. 비밀번호 재입력 가능성: Windows 자격 증명 관리자 키는 PC 단위로 보호되므로 비밀번호 매니저의 일부 항목은 다시 입력해야 할 수 있습니다.
8. 라이선스: 구독 팝업에서 라이선스 키와 이메일로 인증, 새 기기로 등록

이전 가능 / 불가 항목

항목	백업 파일로 이전	데이터 폴더 직접 복사
일정·메모·즐겨찾기	O	O
환경설정	O	O
위젯 위치·크기	O	O
비밀번호 (암호화 본체)	O	O
비밀번호 복호화 키	X	X — Windows 자격 증명 관리자 미이전
OAuth 토큰	X	X — 토큰 자체는 PC 키에 의존
라이선스 캐시	O	O — 단, 기기 한도 1슬롯 차지

Tip

안전·간편한 방법은 백업 파일을 사용하는 것입니다. 데이터 폴더를 직접 옮기더라도 OAuth와 비밀번호는 새 PC에서 재인증이 필요합니다.

데이터 초기화

일부 데이터만 초기화

대상	방법
캘린더·일정	캘린더 위젯 → 캘린더 관리에서 개별 캘린더 삭제 또는 동기화 해제
메모 인스턴스	메모 위젯 → ⋯ 메뉴 → 삭제
즐겨찾기 인스턴스	즐겨찾기 위젯 → 설정 → 삭제
비밀번호 항목	비밀번호 페이지에서 개별 삭제
OAuth 연결	계정 페이지 → 연결 해제
환경설정	각 옵션을 기본값으로 되돌리기

전체 데이터 초기화 (Factory Reset)

1. 앱을 완전히 종료합니다(트레이 → 종료).
2. 백업이 필요하면 먼저 백업 파일을 생성합니다.
3. 윈도우 탐색기에서 다음 폴더를 삭제합니다:
   • %APPDATA%\sudapapadiary
   • %APPDATA%\SudapapaDiary
4. Windows 자격 증명 관리자 → 일반 자격 증명에서 SudapapaDiary 항목을 삭제합니다(암호화 키 제거).
5. 앱을 다시 실행하면 첫 실행 상태로 시작됩니다.

복구 불가능

데이터 폴더와 자격 증명 관리자 키를 함께 삭제하면 백업 없이는 복구가 불가능합니다.

캐시 비우기

날씨·홀리데이·이미지 등 캐시 테이블만 비우면 디스크 절약·문제 해결에 도움이 됩니다.

캐시	비우는 효과
날씨 캐시	다음 조회 시 새로 가져옴
공휴일 캐시	새로 동기화
일정 동기화 캐시	외부 캘린더 전체 재동기화 트리거
이미지·preview	미리보기 이미지 재생성

캐시 비우기 옵션이 환경설정 UI에 노출되어 있지 않은 경우, 데이터 폴더의 해당 캐시 디렉터리를 직접 삭제할 수 있습니다.

로그 파일

문제 진단을 위해 로그 파일을 확인할 수 있습니다.

• 위치: %APPDATA%\sudapapadiary\Logs\ (생성된 경우)
• 또는 콘솔에서 npm start로 실행 시 stdout 출력

문의 시 로그를 함께 첨부하면 진단이 빠릅니다.

디스크 공간

항목	일반적인 용량
빈 DB	~200KB
일정 1년치	520MB
메모 100개	~1MB
비밀번호 100개	~50KB
백업 폴더 (5개 보관)	10100MB
캐시 (날씨·홀리데이)	520MB

전체적으로 100~200MB 이내가 일반적입니다.

DB 손상 복구

비정상 종료(전원 강제 차단 등)로 DB가 손상된 경우:

1. 앱이 시작 중 오류로 멈추는지 확인합니다.
2. Configurations/Database/sudapapa.db와 sudapapa.db-wal, sudapapa.db-shm 파일을 다른 폴더로 이동합니다(임시 백업).
3. Configurations/Backups/db-backup-* 중 가장 최근 폴더에서 sudapapa.db를 가져와 원래 위치에 복사합니다.
4. 앱을 다시 실행합니다.
5. 백업 시점부터 손상 시점까지의 데이터는 손실될 수 있습니다.

자동 백업이 없거나 최근 백업이 너무 오래된 경우, 별도로 보관한 백업 파일에서 설정 불러오기로 복원합니다.

자주 묻는 질문

Q. 백업 파일을 분실했고 PC도 초기화했어요. A. 안타깝지만 데이터 복구가 불가능합니다. 정기적인 백업과 클라우드 보관(OneDrive·Google Drive)을 강력히 권장합니다.

Q. 자동 백업 보관 개수를 늘릴 수 있나요? A. 현재 코드는 5개로 고정되어 있습니다. 더 많은 시점을 보존하려면 수동으로 Backups/ 폴더에서 원하는 시점을 안전한 곳으로 복사해 두세요.

Q. SQLite DB를 직접 편집해도 되나요? A. DB Browser for SQLite 등으로 열람 가능하지만, 직접 수정은 권장하지 않습니다. 잘못된 편집은 앱 실행 오류와 마이그레이션 실패를 유발할 수 있습니다. 반드시 백업 후 자기 책임 하에 진행하세요.

Q. 두 PC에서 같은 데이터를 실시간으로 동기화하려면? A. 현재 빌드는 P2P 동기화를 지원하지 않습니다. Google·Microsoft 캘린더에 일정을 저장하면 외부 서비스를 통해 자동 동기화됩니다. 메모·비밀번호의 다중 PC 실시간 동기화는 추후 검토 항목입니다.