Builderlog ·빌더로그 편집팀 ·플레이북 ·빌더로그 필드 매뉴얼 196 ·2026.09.09 ·7 분 읽기

Cloudflare D1 마이그레이션 대상 확인: 적용 전에 데이터베이스 점검하기

#Cloudflare#D1#마이그레이션#데이터베이스#배포

Cloudflare D1 마이그레이션 대상 확인은 데이터베이스 이름, 바인딩, 실행 위치, 대기 SQL을 구분하고 변경할 대상에 목록을 조회하는 일부터 시작해요. --local은 로컬 SQLite 상태를, --remote는 실제 원격 D1 데이터베이스를 선택해요.

터미널 옆에 둘 판단 기준이에요.

식별: 프로젝트 설정에서 데이터베이스 이름을 확인하고 바인딩은 따로 기록해요.
선택: --local 또는 --remote를 명시하고 해당 대상의 마이그레이션을 조회해요.
판단: 대기 SQL을 검토하고 데이터베이스·위치·변경 의도가 일치할 때만 적용해요.

잘못된 데이터베이스에 작업하지 않도록 돕는 문서 기반 운영 체계예요. 전체 설치 과정은 다루지 않아요.

근거는 운영 실행이 아니라 문서예요

문서 확인일: 2026-09-09.

조건: 문서만 검토했어요. 마이그레이션 실행, 고객 데이터베이스 접근, 운영 환경 설치의 증거는 없어요. 명령은 템플릿이며 예제 데이터베이스 이름은 가상이에요.

D1 마이그레이션 참조는 버전이 지정된 SQL 파일과 생성·조회·적용 작업을 설명해요. 바인딩은 바뀔 수 있어 명령에 바인딩 대신 데이터베이스 이름을 쓰도록 권장해요.

로컬·원격 구분은 공식 D1 통합 가이드를 따랐어요.

이 근거는 대상 확인 방법을 뒷받침하지만, 사용자 설정의 정확성이나 SQL의 운영 적합성을 증명하지 않아요.

유효한 마이그레이션 명령에도 검증된 목적지가 필요해요.

각 이름의 역할을 구분해요

체크리스트에서 데이터베이스 이름과 앱 바인딩은 별도 항목이에요.

명령에는 설정된 데이터베이스 이름을 쓰고, 바인딩은 앱 설정과 대조하도록 따로 기록해요.

실행 플래그는 로컬 SQLite와 실제 원격 데이터베이스 중 어디에 작업할지 정해요.

원격이라고 운영 환경인 것은 아니에요. 실제 설정에서 역할을 확인하고 플래그나 익숙한 이름으로 추정하지 마세요.

대상을 알아도 변경이 적합한지는 알 수 없으므로 대기 SQL도 검토해요.

확인 항목	기록할 내용	작업을 보류할 때
데이터베이스 이름	의도한 데이터베이스의 설정상 이름	활성 프로젝트 확인 없이 이름을 복사했을 때
바인딩	해당 데이터베이스의 앱 바인딩	데이터베이스 설정과 대조할 수 없을 때
실행 위치	명시적인 `--local` 또는 `--remote`	명령의 실행 위치가 불분명할 때
원격 역할	선택한 원격 DB가 운영 환경인지 다른 환경인지	모든 원격 DB가 운영 환경이라고 가정할 때
대기 SQL	선택한 대상의 마이그레이션 목록과 파일 내용	적용될 내용을 검토하지 않았을 때

자료 설명: 데이터베이스 대상 판단표예요. 적용 명령을 고르기 전에 실제 프로젝트 설정으로 채우세요.

대상 식별을 반복하는 이유가 있어요. 익숙한 이름만으로는 근거가 부족해요.

설정부터 확인하고 명령을 구성해요

설치하거나 유지보수할 프로젝트의 설정을 열어 대상 데이터베이스 이름과 바인딩을 기록해요.

배포 환경이 나뉜다면 명령이 사용하는 설정 맥락을 확인해 체크리스트에 남겨요. 필요한 옵션은 최신 공식 문서를 참고하세요.

가상 프로젝트의 메모 예시예요.

데이터베이스 이름: example-journal-db
앱 바인딩: APP_DATABASE
작업 의도: 로컬 마이그레이션 상태 확인
실행 위치: --local

구분을 설명하는 가상 값이므로 기존 설치에 붙여 넣지 마세요.

확인한 메모로 조회 명령을 구성해요. 과거 적용 명령의 일부만 수정하면 판단 근거가 터미널 기록에 숨을 수 있어요.

실제로 의도한 목적지의 목록을 조회해요

적용 판단 전에 목록을 조회해요.

npx wrangler d1 migrations list example-journal-db --local

원격 조회용 템플릿은 다음과 같아요.

npx wrangler d1 migrations list example-journal-db --remote

가상 이름을 확인한 이름으로 바꾸세요. 대상별 대안 예시이며 모두 실행하는 순서가 아니에요.

결과에 정확한 조회 명령, 데이터베이스 이름, 위치 플래그, 설정 맥락을 함께 기록해요.

나열된 SQL 파일을 열어 의도한 변경과 대조해요. 파일명은 찾는 데 도움이 되지만 검토 대상은 SQL이에요.

로컬 목록은 로컬 대상의 근거예요. 원격의 대기 상태나 다른 원격 데이터베이스까지 검증하지 않아요.

목록 결과는 그 결과를 만든 대상에 속해요.

예상 밖의 결과라면 멈추고 설정과 파일을 재확인해요. 뜻밖의 결과를 적용 이유로 삼지 마세요.

적용은 별도로 판단해요

조회 후 결과를 명시적으로 선택해요.

조회 결과	판단
대상 식별이 미해결이에요	보류하고 설정을 확인해요
대기 SQL이 변경 의도와 달라요	보류하고 파일을 검토해요
대기 마이그레이션이 없어요	조회한 대상에서 대기 SQL이 식별되지 않았어요
대상과 대기 SQL이 변경 의도와 맞아요	해당 마이그레이션 검토와 적용 판단으로 진행해요

빈 목록은 앱 정상 작동, 설치 성공, 로컬·원격 일치를 증명하지 않아요.

적용 근거가 마련되면 확인한 목적지를 유지해요. 가상 로컬 예시예요.

npx wrangler d1 migrations apply example-journal-db --local

별도로 확인한 원격 대상의 예시예요.

npx wrangler d1 migrations apply example-journal-db --remote

위치 플래그를 바꾸면 검토 대상도 바뀌어요. 로컬에서 원격으로 이동할 때 대상 확인을 반복해요.

재사용할 확인 기록을 남겨요

비공개 설치 메모에 이 체크리스트를 복사하세요.

D1 migration target check

Review date:
Project and configuration context:
Intended database role:
Configured database name:
Application binding:
Explicit location flag:
Exact list command:
Pending migration files:
SQL reviewed:
Unresolved questions:
Decision: hold / no pending SQL identified / ready for apply review
Exact proposed apply command:

실패와 한계: 이 방법은 대상 혼동을 다뤄요. SQL 정확성, 런타임 호환성, 복구 준비를 증명하지 않으며, 잘못된 대상 작업 사고나 복구 성공을 주장하지 않아요.

선택적인 설치 예시인 사주 소스 라이선스는 단일 프로젝트용 한국어 사주 웹 앱 소스 패키지예요. 현재 제공물과 설치 요건은 제품 페이지에서 확인하세요. 구매자의 데이터베이스 검증을 뜻하지는 않아요.

최종 판단은 마이그레이션 적용 전에 대상 확인 기록을 완성하는 것이에요. 불확실한 항목은 데이터베이스 상태를 바꾸기 전에 해결해요.

근거	뒷받침하는 내용	한계
Google 자동완성, 2026-09-09 검토	정확한 검색어 `Cloudflare D1 migrations`가 당시 추천 화면에 나타났어요	검색어 노출 신호일 뿐 검색량·순위·구매 의도·성과는 아니에요
가상 편집 예시	여기서 다룬 항목이나 판단 경로를 보여줘요	측정한 운영 결과가 아니에요