Adopt Doctrine DBAL for Foundation Database

[defunctl]

Foundation Database now uses Doctrine DBAL for queries, execution, and schema inspection. Applications inject their tables for ordinary work and the shared connection for transaction boundaries. Schema migrations and application database locks are separate packages, so projects can install the capabilities they need.

• foundation-database supplies the shared WordPress connection, table conveniences, naming policy, and managed transactions. DBAL ^4.4 replaces the wpdb/dbDelta implementation and duplicate query/schema APIs. Database owns the DBAL dependency constraint.
• foundation-migrations owns declarative schema changes, discovery, history, migration stubs, and the WP-CLI migration command. Register DatabaseProvider followed by MigrationsProvider; register WPCliProvider to expose commands, or inject Migrator for programmatic upgrades.
• foundation-lock-database supplies application lock storage and DatabaseLock. Applications explicitly select their Lock implementation and initialize its storage. Migration execution uses the database session's advisory lock, independently of application lock storage.
• Preserve terminal transaction failures, original business exceptions, acknowledged commits, nested savepoints, and WordPress site/session boundaries. Refresh replaced WordPress connections between operations without replaying SQL.

Migration files now return anonymous subclasses of Migration and live in db/migrations by default. For example, 20260923000001_create_reports_table.php supplies its persistent ID through the filename. Discovery includes subfolders and globally orders IDs; adding a migration requires no Composer mapping or provider-list edit. Historical declarations use literal unprefixed table names, keeping them independent of runtime table classes and PHP namespace changes.

• Configure generation and runtime discovery together through migrations.path, relative to foundation.root. Override ledger naming through migrations.table; the default derives from the application's stable foundation.prefix.
• Use make:database:table Reports --table-name=your_plugin_reports --migration for a table and its initial migration. Use make:database:migration add_status --table=your_plugin_reports for a later alteration. Generator names use colon-separated groups throughout the CLI.
• Initial migrations own their complete table; alterations own explicit additions, changes, and removals. Generic and alteration stubs inherit an irreversible rollback until the developer supplies a safe inverse. Applied filenames and declarations are persistent history.
• Optional data steps implement MigratesData::migrate(DataMigrationContext $context). The context exposes public readonly $db and $names properties plus quotedTable() for historical SQL. Foundation supplies the shared services after schema execution and before recording history.
• Support status, SQL preview, target/step rollback, and refresh. Retry committed DDL after failed history writes without rebuilding matching schema or removing unrelated additions. Full reversals require confirmation, and rollback-only commands never apply pending migrations.
• Group Foundation-owned migration failures under MigrationException, while preserving specific contention, interruption, incompatible-schema, and ledger failures for application recovery decisions.

The guides now cover package selection, complete create-and-alter workflows, standalone-plugin resource prefixes, Strauss handling of migration files, and supported inheritance contracts. Runtime packages belong in Composer require; the generation CLI belongs in require-dev. Standalone plugin archives should use split packages and production dependencies: the aggregate package includes the CLI, and a runtime package installed only through development tooling disappears with --no-dev.

WP-CLI's base Command also provides clearRuntimeCache() for long-running batch commands, clearing saved queries and supported runtime object caches while preserving persistent cache entries.

Suggested review order: src/Database/Table/Table.php, src/Migrations/stubs/, src/Migrations/DataMigrationContext.php, the three package providers, src/Migrations/Migrator.php, src/Migrations/Schema/SchemaPlanner.php, then src/Database/Connection/. The architecture review covered responsibility ownership, operational invariants, and public extension boundaries. Experiment code and research artifacts remain outside this PR.

Validation on the current working tree before commit:

• composer test:coverage: all six SLIC suites passed, covering 710 tests with three existing skips. This includes real Redis, WordPress integration, and WP-CLI execution.
• The new data context and migration provider wiring have full line coverage. Consumer fixtures exercise scoped data callbacks, interrupted transactions, generated migrations, configured discovery paths, and history recovery.
• composer analyze, composer lint, the Node 24 documentation build, and diff checks passed.
• Isolated split-package installation checks confirmed Database works without Migrations, Lock, or WP-CLI, and Migrations installs its required runtime packages.
• Earlier branch validation covered DBAL deprecation tracking, DBAL 4.4.0 consumer installation, and independently Strauss-scoped DBAL 4.4.0 and 4.4.4 installations coexisting in WordPress.
• CI runs PHP 8.3 through 8.5 and complete SLIC suites on MySQL 8 and MariaDB 11.8. Checks for the latest commit are still running at this description update.

MySQL DDL remains nontransactional, data callbacks must be safe to retry, and all migration participants must reach the same primary database server. DBAL-specific schema translation stays internal for future Rector/DBAL 3 work; Foundation 2.0 targets PHP 8.3 and DBAL 4.4. Portal adoption remains a separate follow-up.

Summary by CodeRabbit

• New Features

  • Added Doctrine DBAL-backed database connections, transactions, table operations, and declarative schema migrations.
  • Added migration previews, targeted execution, rollback by steps, refresh, status reporting, data migrations, and advisory-lock protection.
  • Added schema drift detection and safer recovery for interrupted migrations.
  • Added database import workflows with transactional rollback on failure.

• Documentation

  • Updated database, migration, locking, and query guidance for the new APIs.

• Breaking Changes

  • Removed the legacy query, schema, and migration APIs.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Documentation preview

Review this documentation update

Updated for commit f38c9cc.

[github-actions]

Coverage Report

Totals
Statements:	95.81% ( 4274 / 4461 )
Methods:	90.41% ( 622 / 688 )
Lines:	96.79% ( 3652 / 3773 )