본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

마이그레이션 (Migrations)

원문 보기 위키 갱신

D1 데이터베이스 마이그레이션(버전 관리)에 대해 다루는 문서예요. 데이터베이스 개발 과정에서 변경 사항을 버전별로 저장하고 추적하는 방법을 알려줘요.

출처: 문서

본문

Migrations

데이터베이스 마이그레이션은 데이터베이스에 버전을 매기는 방법이에요. 각 마이그레이션은 migrations 폴더 안에 .sql 파일로 저장돼요. migrations 폴더는 첫 마이그레이션을 만들 때 프로젝트 디렉터리에 생성돼요. 이렇게 하면 데이터베이스 개발 과정에서 변경 사항을 저장하고 추적할 수 있어요.

기능 (Features)

현재 마이그레이션 시스템은 단순하지만 효과적이도록 설계됐어요. 현재 구현으로 다음과 같은 작업을 할 수 있어요.

  • 빈 마이그레이션 파일을 생성하세요.
  • 적용되지 않은 마이그레이션을 나열하세요.
  • 남은 마이그레이션을 적용하세요.

migrations 폴더의 모든 마이그레이션 파일은 파일명에 지정된 버전 번호가 있어요. 파일은 순차적으로 나열돼요. 모든 마이그레이션 파일은 실행할 쿼리를 지정할 수 있는 SQL 파일이에요.

Wrangler 사용자 지정

기본적으로 마이그레이션은 Worker 프로젝트 디렉터리의 migrations/ 폴더에 생성돼요. 마이그레이션을 만들면 데이터베이스에 있는 d1_migrations 테이블에 적용된 마이그레이션 기록이 유지돼요.

이 위치와 테이블 이름은 Wrangler 파일의 D1 바인딩 안에서 사용자 지정할 수 있어요.

{
	"d1_databases": [
		{
			"binding": "<BINDING_NAME>", // i.e. if you set this to "DB", it will be available in your Worker at `env.DB`
			"database_name": "<DATABASE_NAME>",
			"database_id": "<UUID>",
			"preview_database_id": "<UUID>",
			"migrations_table": "<d1_migrations>", // Customize this value to change your applied migrations table name
			"migrations_dir": "<FOLDER_NAME>", // Specify your custom migration directory
			"migrations_pattern": "<GLOB>" // Optional: discover migrations using a glob pattern (see below)
		}
	]
}

[[d1_databases]]
binding = "<BINDING_NAME>"
database_name = "<DATABASE_NAME>"
database_id = "<UUID>"
preview_database_id = "<UUID>"
migrations_table = "<d1_migrations>"
migrations_dir = "<FOLDER_NAME>"
migrations_pattern = "<GLOB>"

중첩 마이그레이션 레이아웃 (Nested migration layouts)

기본적으로 wrangler d1 migrations apply는 migrations_dir 안의 최상위 .sql 파일을 찾아요. Drizzle ↗︎ 같은 ORM을 사용해 각 마이그레이션을 별도의 하위 디렉터리(예: migrations/0001_init/migration.sql)로 작성한다면, migrations_pattern을 레이아웃에 맞는 glob으로 설정하세요.

{
	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "my-database",
			"database_id": "<UUID>",
			"migrations_dir": "migrations",
			"migrations_pattern": "migrations/*/migration.sql"
		}
	]
}

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "<UUID>"
migrations_dir = "migrations"
migrations_pattern = "migrations/*/migration.sql"

migrations_pattern의 규칙:

  • 설정하면 migrations_dir도 반드시 설정해야 해요.
  • 패턴은 migrations_dir에 설정된 값으로 시작해야 해요.
  • 각 마이그레이션의 이름은 migrations_dir 기준 상대 경로(예: 0001_init/migration.sql)로 마이그레이션 테이블에 기록돼요. 이렇게 하면 테이블이 다른 머신 간에 이식 가능해져요.

패턴은 표준 glob이에요. *는 한 경로 세그먼트와 일치하고, **는 임의 개수의 세그먼트와 일치해요. migrations/**/*.sql은 임의로 깊은 .sql 파일을 모두 선택해요.

wrangler d1 migrations create는 migrations_dir 안의 최상위 파일만 작성해요. 따라서 migrations_pattern이 중첩 파일만 일치한다면(Drizzle 레이아웃처럼), 대신 ORM의 명령(예: drizzle-kit generate)으로 새 마이그레이션을 생성하세요.

외래 키 제약 조건 (Foreign key constraints)

마이그레이션을 적용할 때 외래 키 제약 조건을 일시적으로 비활성화해야 할 수도 있어요. 그렇게 하려면 외래 키를 위반하는 변경을 하기 전에 PRAGMA defer_foreign_keys = true를 호출하세요.

외래 키와 D1을 다루는 방법에 대한 자세한 내용은 외래 키 문서를 참조하세요.

더 알아보기 (Learn more)