Persistence

Database Layer

Sdílená database infrastruktura, provider boundaries, schema API a základní praktické použití.

Architecture

DatabaseServiceProvider registers shared database infrastructure: ConnectionFactory, DatabaseFactory, DatabaseDriverRegistry, DatabaseConfig, ConnectionInterface, Database, DatabaseDriverInterface, SchemaGrammarInterface, SchemaCompiler and Schema. Concrete driver providers register executable drivers and schema grammars into the registry.

Configuration contract

Database config is read from database.default and database.connections.{name}. A connection supports driver, dialect, host, port, database, username, password, charset, collation, prefix, strict, persistent, dsn and options. The framework default has no configured connections; applications provide them through app config.

return [
    'default' => 'default',
    'connections' => [
        'default' => [
            'driver' => 'mysql',
            'dialect' => 'mysql',
            'host' => '127.0.0.1',
            'port' => 3306,
            'database' => 'app',
            'username' => 'root',
            'password' => '',
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix' => '',
            'strict' => true,
            'persistent' => false,
            'dsn' => '',
            'options' => [],
        ],
    ],
];

Environment examples

The application config may map environment variables to the database config contract. SQLite is not a driver value; it uses PDO as the connection backend and sqlite as the dialect.

DB_CONNECTION=default
DB_DRIVER=pdo
DB_DIALECT=sqlite
DB_DSN=sqlite:storage/skeleton.sqlite

DB_DRIVER=mysql
DB_DIALECT=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=app
DB_USER=root
DB_PASS=

Drivers and dialects

Supported driver values are mysql, odbc and pdo. Supported dialect values are mysql, odbc and sqlite. Driver selects the connection backend and executable DatabaseDriverInterface implementation; dialect selects SQL/schema grammar behavior, especially for PDO where the backend can connect to different databases.

Database service

Database is the high-level runtime query service. It wraps ConnectionInterface for select(), statement(), cursor(), transaction(), lastInsertId(), affectedRows(), reconnect(), close(), serverVersion() and escapeString(), and creates QueryBuilder through table().

use Lemonade\Framework\Database\Database;

$db = $container->get(Database::class);

$users = $db->select('SELECT * FROM users WHERE active = ?', [1]);
$affected = $db->statement('UPDATE users SET active = ? WHERE id = ?', [0, $id]);

$db->transaction(static function (Database $db): void {
    $db->statement('INSERT INTO audit_logs (message) VALUES (?)', ['Created user']);
});

Driver interface

DatabaseDriverInterface is the low-level compatibility surface. query() returns DatabaseResultInterface or false; cursor() streams associative rows; simple_query() executes raw SQL; affected_rows(), insert_id(), escape(), escape_str(), escape_like_str(), escape_identifiers(), protect_identifiers(), platform() and version() expose driver-specific behavior.

Query builder

Use Database::table() for fluent query composition. QueryBuilder protects identifiers for normal table/column APIs and uses bindings for values. Raw methods are available for explicit SQL fragments; user input should still be passed through bindings, not string concatenation.

$rows = $db->table('articles')
    ->select(['id', 'title', 'created_at'])
    ->where('published', 1)
    ->orderBy('created_at', 'DESC')
    ->limit(20)
    ->getArray();

Schema service

Schema executes DDL through DatabaseDriverInterface. SchemaCompiler compiles SQL without executing it. SchemaGrammarInterface owns grammar-specific SQL compilation. Use Schema and TableBlueprint for framework-managed DDL.

use Lemonade\Framework\Database\Schema\Blueprint\TableBlueprint;
use Lemonade\Framework\Database\Schema\Schema;

$schema = $container->get(Schema::class);

$schema->create('articles', static function (TableBlueprint $table): void {
    $table->id();
    $table->string('title', 160);
    $table->longText('body');
    $table->unsignedInteger('created_at');
}, ifNotExists: true);

SQLite runtime note

SQLite needs pdo_sqlite and sqlite3 enabled in the PHP runtime that opens the connection. CLI PHP and web PHP can use different php.ini files. The PDO error "could not find driver" means the current runtime does not have the PDO SQLite driver enabled. If a SQLite DSN points into storage, the storage directory must exist before the file is created.

Provider boundary

Database providers register infrastructure and driver specifics. They do not define business repositories, application tables or domain persistence policy. Application services, models and repositories consume the database services as needed.