Database access is built directly on PDO

Context

The panel needs database access: connections, a way to build queries, and a way to build and change the schema. Existing database abstraction layers provide all of that, but each one pulls in a great deal of code and a large number of third-party libraries, which adds to the panel's footprint and complicates it.

Decision

The database component is built directly on PHP's PDO extension, with its own connections, query builder and schema builder, rather than on an existing database abstraction layer.

Alternatives

An existing database abstraction layer. Every one available pulls in so much code and so many third-party libraries that it complicates the panel and adds to its footprint.

No other alternatives were weighed.

Consequences

Easier:

• The panel's footprint stays small. The database component needs the PDO extension and no further libraries.
• The component's API follows the panel's own conventions, such as configuration held in typed objects and connections injected through an attribute.

Harder:

• The component owns everything a database abstraction layer would otherwise provide, and its correctness: connection handling, differences between drivers, SQL generation, identifier quoting and bindings.

Constrained:

• Supporting another database means writing that support inside the component, as the hidden driver support in ADR-0007 anticipates.

Sources

• Commit 4e4b8bf, "Create connection factory", 2026-03-29, on the branch of PR #30: the first code creating connections directly with PDO, which is created.
• PR #30, feat(database): Add the database component, merged 2026-04-17 and squashed as 560e9ab: the component built on PDO, which is decided.
• composer.json at 560e9ab: the PDO extension required, and no database abstraction layer.
• The decision and its reason, that existing database abstraction layers pull in so much code and so many third-party libraries that they complicate the panel and add to its footprint: first written down on 2026-09-14, with no record of when they were weighed.
• Issues #41, #42 and #48, 2026-08-07 and 2026-08-08: defects in identifier quoting, bindings and connection options, which show the correctness the component owns, taken from what followed rather than anticipated.