Motivation

In my recent project, I had to organize database migrations by feature or module, using sub-folders under migrations/. Until now, sqlx migrate run only looked at top-level migration files, which made those nested setups hard to use directly.

This PR adds optional recursive migration discovery, so developers can structure migrations cleanly without changing the default behavior.

New Behavior (Opt-in)

• Default: No change — existing behavior stays the same (non-recursive).

• New flag: --recursive
  When provided, sqlx will walk through sub-directories inside the migration folder and apply all valid migrations in version order.

  sqlx migrate run --recursive

Implementation Details

sqlx-core/src/migrate/source.rs

• Added recursive: bool to ResolveConfig with a set_recursive(bool) method.
• Refactored resolve_blocking_with_config(...) to use a directory walker helper.
• When recursive is true, sub-folders are traversed; otherwise, only top-level files are read.

sqlx-cli/src/opt.rs

• Added a new CLI flag: --recursive.
• Hooked it into the resolver via set_recursive(self.recursive) before building the migrator.

sqlx-cli/README.md

• Added usage example for --recursive.

sqlx-core/Cargo.toml

• Added tempfile dev-dependency for migration-related tests.

Tests

Added two unit tests in sqlx-core/src/migrate/source.rs:

• Non-recursive: nested files are ignored (existing behavior).
• Recursive: nested files are included and applied in version order.

✅ All workspace tests pass:
test result: ok. 29 passed; 0 failed; 31 ignored; ...

Backwards Compatibility

• Default behavior remains unchanged (non-recursive unless flag provided).
• Version/checksum validation logic is untouched — duplicate version numbers across sub-folders still cause the same error as before.

Performance Notes

• Recursive traversal adds extra I/O for large directory trees, so it’s opt-in only.
• No change in performance for the default case.

Future Work

• Allow configuring recursive discovery via sqlx.toml (project-level default).
  Happy to add that in a follow-up PR if the maintainers are interested!

Files Touched

• sqlx-cli/src/opt.rs
• sqlx-core/src/migrate/source.rs
• sqlx-cli/README.md
• sqlx-core/Cargo.toml

Thanks

Appreciate your time reviewing this! 🙏
Let me know if you’d like me to include a sqlx.toml config toggle or add an integration test for a nested migration directory — I can update the PR accordingly.