split database driver from dialect

[withinboredom]

Many (exotic) databases use the postgres wire protocol but use different dialects. Right now, the postgres package assumes a postgres (14+) dialect. But people should be able to build and use other dialects as well -- such as cockroachdb.

[markshust]

Valid request — thanks for raising this.

The current architecture already has the right seams for this: SqlGeneratorInterface, IntrospectorInterface, and ConnectionInterface are all swappable via DI. The plan would be to add a new database-cockroachdb package that:

• Reuses (or extends) the pgsql wire protocol connection layer
• Provides its own SqlGeneratorInterface implementation for CockroachDB's DDL dialect (e.g., unique_rowid() instead of SERIAL, different introspection queries, etc.)
• Provides a CockroachDB-specific introspector

This is moderate effort and doesn't require changes to the core database package. Tagging as post-1.0 — the interfaces are already in place so this can be built without breaking changes when the time comes.

[markshust]

Looked at this with fresh eyes and the conclusion is: the architectural split is already largely in place, and what was missing was a supported override mechanism for downstream dialect packages — which also already exists. No package splits or framework changes needed.

What's already true today

packages/database-pgsql/module.php exposes the dialect via 5 separate bindings, not one monolithic bundle:

Binding	Role
ConnectionInterface	Wire protocol (PDO, postgres DSN)
SqlGeneratorInterface	Dialect (DDL)
IntrospectorInterface	Dialect (schema read)
QueryBuilderInterface	Dialect (SELECT/INSERT/UPDATE/DELETE)
QueryBuilderFactoryInterface	Dialect (builder factory)

And PgSqlConnection itself is dialect-clean — pure PDO with a SET NAMES call, no embedded postgres-specific SQL. So the "wire vs dialect" separation the issue asks for already exists at the interface level.

What was missing — and where it actually lives

The friction point: if you simply ship acme/database-cockroachdb declaring the 4 dialect interfaces in its static bindings, you'd hit BindingConflictException because two vendor-priority modules can't bind the same interface.

But Container::bind() is intentionally a direct write that bypasses conflict detection, and module boot callbacks run after all static bindings are registered. So a variant package can do this in its own module.php:

return [
    'boot' => function (Container $container): void {
        // Override the 4 dialect bindings — ConnectionInterface stays bound to PgSqlConnection
        $container->bind(SqlGeneratorInterface::class, CockroachDbGenerator::class);
        $container->bind(IntrospectorInterface::class, CockroachDbIntrospector::class);
        $container->bind(QueryBuilderInterface::class, CockroachDbQueryBuilder::class);
        $container->bind(QueryBuilderFactoryInterface::class, CockroachDbQueryBuilderFactory::class);
    },
];

(Variant packages live under their own vendor namespace — acme/ here — since marko/ is reserved for core packages.)

Why this is better than splitting packages

The alternative (splitting marko/database-pgsql into wire-only + dialect-only sub-packages, plus separate packages per variant) would have meant a real rename + breaking change + package proliferation. The boot-callback approach keeps the user-facing package count at one per database (e.g. acme/database-cockroachdb), avoids breaking current pgsql users, and uses existing framework primitives the way they were designed to be used.

What landed in #85

• Integration test (packages/database-pgsql/tests/Module/DialectOverrideTest.php) proving the override resolves correctly, ConnectionInterface stays bound to PgSqlConnection, and the static-bindings path still throws loudly. Includes a regression guard so none of the 4 dialect interfaces can be silently promoted to singletons (which would defeat the override via cached instances).
• Generic pattern documented in concepts/dependency-injection.md (applies to any sibling driver — cache variants, queue variants, etc.)
• Database-specific worked CockroachDB example in packages/database.md
• Cross-link from database-pgsql.md for discoverability

No new packages, no renames, no framework changes. Closing on merge of #85.