Migrations

Database migrations are a way of versioning your database. Each migration is stored as an .sql file in your migrations folder. The migrations folder is created in your project directory when you create your first migration. This enables you to store and track changes throughout database development.

Features

Currently, the migrations system aims to be simple yet effective. With the current implementation, you can:

• Create an empty migration file.
• List unapplied migrations.
• Apply remaining migrations.

Every migration file in the migrations folder has a specified version number in the filename. Files are listed in sequential order. Every migration file is an SQL file where you can specify queries to be run.

Wrangler customizations

By default, migrations are created in the migrations/ folder in your Worker project directory. Creating migrations will keep a record of applied migrations in the d1_migrations table found in your database.

This location and table name can be customized in your wrangler.toml file, inside the D1 binding.

wrangler.toml

[[ 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

wrangler.json

{
  "d1_databases": [
    {
      "binding": "<BINDING_NAME>",
      "database_name": "<DATABASE_NAME>",
      "database_id": "<UUID>",
      "preview_database_id": "<UUID>",
      "migrations_table": "<d1_migrations>",
      "migrations_dir": "<FOLDER_NAME>"
    }
  ]
}

Foreign key constraints

When applying a migration, you may need to temporarily disable foreign key constraints. To do so, call PRAGMA defer_foreign_keys = true before making changes that would violate foreign keys.

Refer to the foreign key documentation to learn more about how to work with foreign keys and D1.

Was this helpful?

What did you like?

Accurate

Easy to understand

Solved my problem

Helped me decide to use the product

Other

What went wrong?

Hard to understand

Incorrect information

Missing the information

Other

Thank you for helping improve Cloudflare's documentation!