D1 migrations can now read your nested folders!

Hi everyone, it's me, Shii-chan! Today I found a nice little update to D1, so let me tell you about it.

Cloudflare Changelog developers.cloudflare.com

What was announced?

Over on the Cloudflare Changelog, they announced that D1 migrations now support nested (sub-folder) layouts. A new option called migrations_pattern was added, so wrangler d1 migrations apply can now discover migrations placed inside subdirectories too.

This is a folder layout that ORMs like Drizzle tend to use.

The story so far

Until now, migration files were expected to sit directly inside the folder you pointed at with migrations_dir. So when an ORM emitted things in a nested "one migration = one folder" style, Wrangler wouldn't pick them up as-is, and you had to rearrange them by hand.

What changes

If you write a glob pattern in migrations_pattern, files matching that pattern get treated as migrations. That means you can feed an ORM's nested folder layout straight into wrangler d1 migrations apply. For folks living in ORM land, this is a quietly helpful one!

Dive Deep

You set it inside d1_databases in your Wrangler config file, like this.

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

A few points to keep in mind.

• The glob pattern is written relative to your Wrangler config file.
• If you don't set migrations_pattern, the default is ${migrations_dir}/*.sql, so if your layout is unchanged you don't have to touch anything, it's backward compatible.
• Migration names are recorded as paths relative to migrations_dir.

For the full details, check the nested migration layouts documentation.

Wrap-up

• D1 migrations now support nested folders, with a new migrations_pattern option.
• You specify it with a glob pattern, and the default is ${migrations_dir}/*.sql, so it stays backward compatible.
• Migration names are recorded relative to migrations_dir.
• This one lands nicely for everyone pairing an ORM like Drizzle with D1!