05. 데이터베이스 (SQLite)
파일: backend/data/alice.db (git 제외). 저널 모드 WAL(초기화 시 1회 설정, 파일에 영구 저장), 커넥션당 busy_timeout 30초.
테이블
transfers — ACN Transfer 이벤트
| 컬럼 | 타입 | 설명 |
|---|---|---|
tx_hash | TEXT | 트랜잭션 해시(소문자 0x) |
log_index | INTEGER | 영수증 내 로그 인덱스. 한 tx에 Transfer가 여러 개일 수 있어 PK에 포함 |
block_number | INTEGER | 블록 번호 |
from_address | TEXT | 보낸 주소(소문자) |
to_address | TEXT | 받은 주소(소문자) |
amount_wei | TEXT | 수량(wei). uint256은 SQLite INTEGER(64bit)를 넘을 수 있어 TEXT |
block_time | INTEGER | 블록 타임스탬프(unix). 없으면 NULL |
source | TEXT | indexer 또는 client(POST /api/transfers로 기록) |
created_at | INTEGER | 저장 시각(unix) |
- PK:
(tx_hash, log_index) - 인덱스:
from_address,to_address,block_number DESC - upsert 규칙: 충돌 시
block_number갱신,block_time은 NULL이 아닌 값 우선 유지.
indexer_state — 인덱서 체크포인트
| 컬럼 | 타입 | 설명 |
|---|---|---|
key | TEXT PK | last_indexed_block |
value | TEXT | 마지막 처리 블록 번호 |
설계 메모
- 주소는 전부 소문자로 정규화해 저장·비교한다(EIP-55 체크섬은 표시용).
- 금액 계산은 DB가 아니라 애플리케이션(파이썬
int, 프론트bigint)에서 한다. - 스키마는
db.py의SCHEMA에CREATE TABLE IF NOT EXISTS로 정의되며 앱 시작 시 적용된다. 마이그레이션 도구 없이 시작하고, 변경이 잦아지면 Alembic 도입을 검토한다. - 백업은
sqlite3 alice.db ".backup alice-YYYYMMDD.db"로 온라인 백업 가능.