Database

Foundation Database provides a configured Doctrine DBAL connection, convenient application tables, and reliable WordPress migration and transaction behavior. Use Doctrine directly for expressions, joins, parameter binding, results, and advanced operations.

Get started

Install the runtime package:

composer require stellarwp/foundation-database

Foundation requires PHP 8.3, mysqli, and Doctrine DBAL 4.4. Database services borrow the active WordPress connection. Use the primary MySQL or MariaDB database and InnoDB tables for transactional application data.

Set a stable, unique application prefix in your root configuration:

config.php

<?php declare(strict_types=1);

return [
	'foundation' => [
		'prefix' => $_ENV['FOUNDATION_PREFIX'] ?? 'your-plugin',
	],
];

Create your container using ContainerFactory, then register providers once, in dependency order:

use StellarWP\Foundation\Database\DatabaseProvider;
use StellarWP\Foundation\WPCli\WPCliProvider;
use Plugin\Database\Provider;

$container->register( WPCliProvider::class );
$container->register( DatabaseProvider::class );
$container->register( Provider::class ); // Your application tables and migrations.

DatabaseProvider supplies one shared Doctrine\DBAL\Connection. Tables and repositories resolved from the container participate in that connection’s transactions. Registration is lazy: it creates no database tables.

Query an application table

Application tables declare their stable name and inherit their infrastructure constructor:

src/Database/Tables/Reports_Table.php

<?php declare(strict_types=1);

namespace Plugin\Database\Tables;

use StellarWP\Foundation\Database\Table\Table;

final readonly class Reports_Table extends Table {
	public function unprefixedName(): string {
		return 'your_plugin_reports';
	}
}

Inject Reports_Table into your service and call its operations:

$id = $this->reports->insertGetId( [ 'title' => 'Weekly report' ] );

$report = $this->reports->query()
	->select( 'id', 'title' )
	->where( 'id = :id' )
	->setParameter( 'id', $id )
	->fetchAssociative();

Create the table through a migration, then use the query and transaction guide for results, writes, and failure handling.

Configure resource names

foundation.prefix = your-plugin gives the migration ledger the unprefixed name your_plugin_foundation_migrations. The optional database lock uses your_plugin_foundation_locks. WordPress adds its current site prefix. The migration advisory lock is derived from the database and ledger names, so applications with different ledgers migrate independently.

Override table names when necessary:

config.php

return [
	'foundation' => [
		'prefix' => $_ENV['FOUNDATION_PREFIX'] ?? 'your-plugin',
	],
	'database' => [
		'migrations_table' => $_ENV['FOUNDATION_DATABASE_MIGRATIONS_TABLE'] ?? 'your_plugin_migrations',
		'locks_table'      => $_ENV['FOUNDATION_DATABASE_LOCKS_TABLE'] ?? 'your_plugin_locks',
	],
];

These are names without a WordPress prefix. Physical names must contain only ASCII letters, numbers, and underscores, and fit within 64 bytes including the WordPress prefix. Application tables choose their own unique names, such as your_plugin_reports.

Keep the Foundation prefix and configured storage names stable across releases. Changing a ledger name makes recorded migrations appear pending. PHP namespace changes and Strauss scoping do not change migration IDs or these resource names.

Multisite and customization

A shared container may be reused after switch_to_blog() between complete operations. Tables resolve the active prefix when called; a query already built retains its original table name. Build a fresh query after switching sites. Run migrations separately for each site, for example wp --url=https://site.example your-plugin migrate --run.

Transactions and migrations capture their starting scope and reject detected site or connection changes. Never switch sites, even temporarily, during those operations.

Applications can replace DatabaseScope and TableNameResolver when they own a different naming policy. Register replacements after DatabaseProvider, before resolving database services. Replacing the Doctrine connection also requires preserving Foundation’s documented transaction and migration guarantees, including terminal failure tracking, acknowledged commits, and the shared WordPress session. A plain DBAL connection alone does not provide those guarantees.

MigrationsGenerate historical changes, preview SQL, and recover interrupted deployments.

Queries and transactionsUse application tables and native Doctrine operations.

Database LockChoose database-backed coordination for application work.