[vitest-pool-workers] readD1Migrations() does not read the nested migration layout that migrations_pattern supports

[gradyat]

What versions & operating system are you using?

System:
    OS: Windows 11 10.0.26200
    CPU: (8) x64 11th Gen Intel(R) Core(TM) i7-1165G7 @ 2.80GHz
    Memory: 1.06 GB / 15.71 GB
  Binaries:
    Node: 24.18.0 - C:\Users\Grady\.vite-plus\js_runtime\node\24.18.0\node.EXE
    npm: 11.16.0 - C:\Users\Grady\.vite-plus\js_runtime\node\24.18.0\npm.CMD
    pnpm: 10.32.1 - C:\Users\Grady\.vite-plus\package_manager\pnpm\10.32.1\pnpm\bin\pnpm.CMD
  npmPackages:
    @cloudflare/vite-plugin: ^1.47.0 => 1.47.0
    @cloudflare/vitest-pool-workers: ^0.18.8 => 0.18.8
    wrangler: ^4.114.0 => 4.114.0

Please provide a link to a minimal reproduction

workers-sdk/packages/vitest-pool-workers/src/pool/d1.ts

Lines 20 to 22 in afaecee

	const names = fs
	.readdirSync(migrationsPath)
	.filter((name) => name.endsWith(".sql"));

Describe the Bug

readD1Migrations() reads only *.sql files sitting directly in the directory it is given. It does not handle the nested <timestamp>_<name>/migration.sql layout that D1 added support for in May via migrations_pattern, so for a project using that layout it returns an empty array and applyD1Migrations() then applies nothing.

I've linked the source line rather than a repro repo, because the failure is entirely inside the reader — there's no interaction between components to reproduce, just a few lines of Wrangler config against one line of source, both inline below.

Setup

Wrangler config using the nested layout:

"d1_databases": [
  {
    "binding": "DB",
    "database_name": "example-db",
    "migrations_dir": "drizzle",
    "migrations_pattern": "drizzle/*/migration.sql"
  }
]

On disk — this is drizzle-kit's default output shape:

drizzle/
  20260101000000_init/
    migration.sql
    snapshot.json

Steps to reproduce

1. wrangler d1 migrations apply example-db --local — reads and applies the migration.
2. In vitest.config.ts:

const migrations = await readD1Migrations("./drizzle");
console.log(migrations.length); // 0

3. applyD1Migrations() therefore applies nothing, and every test fails against an empty database.

Same directory, same Wrangler config, two different answers from the same toolchain.

Cause

packages/vitest-pool-workers/src/pool/d1.ts (permalinked above):

const names = fs
  .readdirSync(migrationsPath)
  .filter((name) => name.endsWith(".sql"));

A single non-recursive read, so a directory of per-migration subdirectories matches nothing. This matches only migrations_pattern's default value of ${migrations_dir}/*.sql.

Expected

readD1Migrations() reads the same migrations Wrangler applies.

Honouring migrations_dir / migrations_pattern from the Wrangler config the pool is usually already pointed at (via wrangler.configPath) would keep the test path and the deploy path from drifting. Globbing one level deeper would also fix the immediate problem.

Context

migrations_pattern shipped on May 29, 2026, explicitly to support this layout:

• Changelog: D1 migrations support nested layouts via migrations_pattern — "You can now point wrangler d1 migrations apply at a nested migrations layout — such as the one produced by Drizzle (migrations/0001_init/migration.sql)"
• D1 docs: Nested migration layouts — "If you use an ORM such as Drizzle that writes each migration as its own subdirectory (for example, migrations/0001_init/migration.sql), set migrations_pattern to the glob that matches your layout"
• Config reference: migrations_pattern

So Wrangler gained first-class support for the Drizzle layout two months ago, and the Workers Vitest integration's migration reader — the officially documented way to apply migrations in tests — cannot read it. Following the D1 docs to configure a Drizzle project leaves you with a test suite that runs against an empty database.

Related, smaller

Finding zero migrations returns [] silently, which is what makes this expensive to diagnose — the first symptom is no such table pointing at your own query, several layers from the cause. readD1Migrations() already throws a TypeError when migrationsPath isn't a string, so throwing when it finds nothing to apply would be consistent with its existing behaviour, and an empty migration set is never what the caller wanted.

Also adjacent, and more directly tied to the fix — the sort immediately below the code above:

names.sort((a, b) => {
	const aNumber = parseInt(a.split("_")[0]);
	const bNumber = parseInt(b.split("_")[0]);
	return aNumber - bNumber;
});

This is safe today, because wrangler d1 migrations create always produces NNNN_name.sql and parseInt always succeeds. If nested layouts are read and names become paths relative to migrations_dir — per the D1 docs, e.g. 0001_init/migration.sql — that guarantee no longer holds: a directory without a numeric prefix gives NaN on both sides, and a comparator returning NaN leaves the ordering implementation-defined. Migration order isn't cosmetic, so it may be worth pinning explicitly as part of whatever the fix turns out to be.

Finally, unrelated to the bug itself but in the same area and cheap to fix: the JSDoc on applyD1Migrations (types/cloudflare-test.d.ts#L183-L184) and the Test APIs reference both say to call readD1Migrations() from the @cloudflare/vitest-pool-workers/config package, which is no longer in the exports map. The configuration reference already shows the correct root-package import.

Please provide any relevant error logs

Error: D1_ERROR: no such table: users: SQLITE_ERROR
 ❯ D1DatabaseSessionAlwaysPrimary._sendOrThrow cloudflare-internal:d1-api:146:19
 ❯ cloudflare-internal:d1-api:97:27

Every test in the project fails this way. Nothing in the output mentions migrations, the migrations
directory, or the fact that zero were applied.

[workers-devprod]

Note

This is an automated, advisory triage report generated by workers-devprod. It is not an official maintainer response — a maintainer will follow up.

🤖 Automated triage report

Issue Triage: #14866

Summary

readD1Migrations() in vitest-pool-workers only reads flat *.sql files and silently returns [] for the nested <timestamp>_<name>/migration.sql layout that Wrangler now supports via migrations_pattern, so tests run against an empty database.

Classification

• Type: Bug
• Component: packages/vitest-pool-workers
• Severity: Medium
• Has Reproduction: Yes (source permalink + inline config/steps; no repo, but the bug is self-contained in the reader)
• Quality: Complete

Findings

• Created: 2026-07-26
• Author: gradyat
• Version: @cloudflare/vitest-pool-workers 0.18.8, @cloudflare/vite-plugin 1.47.0, wrangler 4.114.0, Node 24.18.0, Windows 11
• Labels: none
• Comments: 0

Analysis

• The reporter pinpoints the root cause at packages/vitest-pool-workers/src/pool/d1.ts (permalinked at commit afaecee, L20-22): a single non-recursive fs.readdirSync(...).filter(name => name.endsWith(".sql")). This matches only the default ${migrations_dir}/*.sql layout, not nested subdirectory layouts.
• The mismatch is real and clearly motivated: Wrangler shipped migrations_pattern (May/June 2026) explicitly to support ORM layouts like Drizzle (migrations/0001_init/migration.sql). wrangler d1 migrations apply honors it, but readD1Migrations() — the documented way to apply migrations in Workers tests — does not, so the test path and deploy path drift.
• Impact: readD1Migrations() returns [], applyD1Migrations() applies nothing, and every test fails with a confusing D1_ERROR: no such table that never mentions migrations. This is a diagnosability problem as much as a correctness one.
• Reporter proposes two fixes: (1) honor migrations_dir/migrations_pattern from the Wrangler config the pool is already pointed at, or, more minimally, (2) glob one level deeper. Also suggests readD1Migrations() throw (rather than silently return []) when it finds no migrations, consistent with its existing TypeError behavior for a non-string path.
• Note: this checkout does not contain packages/vitest-pool-workers/src/pool/d1.ts at the expected path, so the exact current source could not be re-verified locally; assessment relies on the reporter's permalink. A maintainer should confirm against the current source before implementing.

Recommendation

Status: KEEP OPEN

Reasoning: This is a well-scoped, credible bug with a clear root cause, a documented feature gap (migrations_pattern support), and reasonable proposed fixes. It is actionable as-is and does not fall into any closeable category.

Action: Confirm the current readD1Migrations() implementation against the permalinked source, decide between reading migrations_pattern from config vs. a recursive/glob read, and add coverage for the nested layout. Consider throwing (or at least warning) when zero migrations are found to improve diagnosability.

Suggested Labels: none applied — omitted to avoid guessing labels that may not exist in the repo

Suggested Comment

Thanks for the detailed write-up — this is a clear one. You're right that readD1Migrations() does a flat .sql read and doesn't honor the nested migrations_pattern layout that wrangler d1 migrations apply supports, so Drizzle-style projects end up applying zero migrations. We'll look into aligning the reader with the Wrangler config (migrations_dir / migrations_pattern) so the test path and deploy path don't drift, and we agree that silently returning an empty array here is a diagnosability trap worth fixing. We'll follow up on this issue with progress.

Structured summary (JSON)

{
  "issueNumber": 14866,
  "title": "[vitest-pool-workers] readD1Migrations() does not read the nested migration layout that migrations_pattern supports",
  "githubUrl": "https://github.com/cloudflare/workers-sdk/issues/14866",
  "recommendation": "KEEP OPEN",
  "difficulty": "medium",
  "reasoning": "Well-scoped, credible bug: readD1Migrations() does a flat .sql read and ignores the nested migrations_pattern layout Wrangler supports, so tests run against an empty database. Clear root cause and reasonable proposed fixes.",
  "suggestedAction": "Confirm the current readD1Migrations() source, align it with migrations_dir/migrations_pattern (or glob one level deeper), add nested-layout test coverage, and consider throwing/warning when zero migrations are found.",
  "hasSuggestedComment": true,
  "suggestedLabels": []
}