Cloudflare D1 마이그레이션 실전 팁¶

한 줄 요약: 원격 D1에 컬럼 추가는 --file보다 --command 인라인이 안정적. OAuth 토큰 권한 차이 때문.

배경¶

D1 = Cloudflare가 무료로 주는 클라우드 SQLite. 강의 사이트(ai-prompt-lecture)의 게시판 데이터가 여기 저장됨.

게시판 카드에 카테고리 분류를 추가하려면 cards 테이블에 새 컬럼이 필요. 이걸 "마이그레이션"이라고 함 - 기존 데이터는 보존하면서 구조만 바꾸기.

npx wrangler d1 execute lecture-board --remote --file=migrations/0001.sql

SQL 파일을 업로드해서 실행. 직관적이지만 OAuth 토큰의 import 권한이 추가로 필요해서 인증 에러 자주 남.

npx wrangler d1 execute lecture-board --remote --command "ALTER TABLE cards ADD COLUMN category TEXT;"

SQL을 명령줄에 직접 써서 보냄. 평소 사용하는 d1:write 권한만 있으면 됨.

짧은 한 줄짜리 ALTER/CREATE INDEX는 인라인이 빠르고 안정적. 큰 스키마 한 번에 만들 때만 파일.

마이그레이션 후 PRAGMA table_info(cards);로 컬럼이 들어갔는지 확인:

npx wrangler d1 execute lecture-board --remote --command "PRAGMA table_info(cards);"

결과 JSON에 새 컬럼이 cid(컬럼 인덱스) 끝에 추가돼 있으면 성공.

ALTER TABLE cards ADD COLUMN category TEXT;
CREATE INDEX IF NOT EXISTS idx_cards_category ON cards(category);