Architecture

Architecture

BerlinDB is organized around explicit database objects rather than active-record models.

The normal flow is:

1. Table owns table installation, upgrades, maintenance, and the registered WordPress table name.
2. Schema owns the collection of Column and Index objects.
3. Query asks the schema which columns are queryable, builds SQL, runs CRUD operations, and shapes results.
4. Row receives raw values and applies application-level casting or compatibility.
5. Parser and Operator objects turn query vars into SQL fragments.
6. Connection adapters isolate BerlinDB from a raw database object such as WordPress' wpdb.

Directories

src/Database/Adapters

Adapters implement BerlinDB\Database\Interfaces\Connection.

• Wpdb wraps WordPress' wpdb.
• NullConnection is returned when a database global is not yet available.

src/Database/Interfaces

Interfaces define contracts. The main contract is Connection, which contains the database operations BerlinDB needs.

src/Database/Kern

Core objects:

• Column
• Index
• Query
• Row
• Schema
• Table

The directory is named Kern to avoid colliding with common application namespaces while still grouping the central objects together.

src/Database/Operators

Operators represent SQL comparisons such as =, !=, IN, NOT IN, BETWEEN, LIKE, REGEXP, and their negations.

src/Database/Parsers

Parsers transform query vars into JOIN, WHERE, and ORDER BY fragments. Built-in parsers cover:

• direct by clauses
• compare clauses
• date clauses
• __in
• __not_in
• meta clauses
• search clauses

src/Database/Traits

Traits provide shared implementation details such as booting, casting, environment detection, logging, magic access, parser helpers, sanitization, and lifecycle state.

Object Relationships

Table and Query both point to a schema. The schema may be a class name or a Schema object built at runtime.

Query points to a row shape. Returned database rows are converted into that row class.

Column flags decide which query vars are registered. For example, a column marked searchable can participate in search, a column marked date_query can be queried with date clauses, and a column marked in can support column__in.

Design Principles

• Prefer explicit schemas over reflection-heavy behavior.
• Keep database storage separate from application-facing row objects.
• Use WordPress conventions where BerlinDB runs inside WordPress.
• Keep custom database tables approachable: a few small classes are easier to maintain than one magical class.
• Isolate database access behind an interface so WordPress-specific behavior can be abstracted over time.