Skip to content

Database

Jump to bottom
Precious Lyson edited this page Nov 11, 2026 · 1 revision

Database

PDO

Database access is optional: configure it only if your application needs persisted data. Machinjiri's DatabaseConnection accepts driver configuration and provides an SQL query builder and model layer. The app skeleton is responsible for loading configuration during bootstrap.

Configure a connection

The framework API accepts a configuration array via DatabaseConnection::setConfig(). For example, an application bootstrap can configure a MySQL connection like this:

use Mlangeni\Machinjiri\Core\Database\DatabaseConnection;

DatabaseConnection::setConfig([
    'driver' => 'mysql',
    'host' => getenv('DB_HOST') ?: '127.0.0.1',
    'port' => (int) (getenv('DB_PORT') ?: 3306),
    'database' => getenv('DB_DATABASE'),
    'username' => getenv('DB_USERNAME'),
    'password' => getenv('DB_PASSWORD'),
]);

This is the framework-level API, not a promise that every generated app uses these exact environment variable names or invokes configuration in the same file. Use the configuration loader and environment conventions already present in your application.

Supported configuration drivers documented by DatabaseConnection include mysql, pgsql, sqlite, mongodb, and a custom PDO option. Driver-specific requirements and optional client packages apply. The framework package does not make a database server available for you.

Query builder

Build a query with QueryBuilder::builder():

use Mlangeni\Machinjiri\Core\Database\Builders\QueryBuilder;

$user = QueryBuilder::builder('users')
    ->where('email', '=', $email)
    ->first();

Read multiple rows:

$activeUsers = QueryBuilder::builder('users')
    ->where('active', '=', 1)
    ->orderBy('name')
    ->limit(50)
    ->get();

Insert, update, and delete operations use the builder's corresponding methods and execute():

QueryBuilder::builder('users')
    ->insert(['name' => $name, 'email' => $email])
    ->execute();

QueryBuilder::builder('users')
    ->where('id', '=', $id)
    ->update(['name' => $name])
    ->execute();

Use bound values for user-supplied data; do not interpolate values into SQL strings. Query-builder method return values differ by operation, so consult the exact installed version when you need affected-row counts or inserted identifiers.

Models

Application models may extend Mlangeni\Machinjiri\Core\Artisans\Base\AbstractModel. The base model supports fillable/guarded attributes, casts, timestamps, events, optional caching, and soft-delete features. Define the table and mass-assignment policy explicitly:

<?php

namespace App\Models;

use Mlangeni\Machinjiri\Core\Artisans\Base\AbstractModel;

class Post extends AbstractModel
{
    protected string $table = 'posts';

    protected array $fillable = ['title', 'body'];
}

Do not make every field mass assignable without reviewing what clients can submit. The model query/create APIs use magic static methods; check their documented return types and verify connection bootstrap in your app before relying on them.

Migrations and seeders

The framework's CLI includes migration and seeder commands such as:

php artisan db:migration:create
php artisan db:migration:list
php artisan db:migration:migrate
php artisan db:migration:rollback
php artisan db:seeder:create
php artisan db:seeder:run

These are application CLI commands and may prompt for additional arguments. Use php artisan list and the command's help output in your generated app for the precise syntax. Review a migration before running it against shared or production data; take backups and use a controlled release process.

Transactions

DatabaseConnection exposes transaction methods:

DatabaseConnection::beginTransaction();

try {
    // Perform related database work.
    DatabaseConnection::commit();
} catch (\Throwable $exception) {
    DatabaseConnection::rollback();
    throw $exception;
}

Prefer a try/catch/finally or an application transaction helper that guarantees cleanup. Never swallow the exception after rolling back unless the failure has been handled intentionally.

Connection pooling

Pooling can be configured through the optional pool array in DatabaseConnection::setConfig(). Options include enabled, max_connections, min_connections, idle_timeout, wait_timeout, and persistent. Enable pooling only after understanding your runtime model (short-lived PHP requests versus long-running workers) and testing capacity and cleanup.

Safe database practices

  • Use parameterized query-builder values or prepared statements.
  • Validate and authorize before writing or returning records.
  • Limit result sets for list endpoints and paginate large collections.
  • Keep connection credentials in environment-specific secrets, never committed code.
  • Use least-privilege database accounts.
  • Treat migrations as data-changing production operations.

More

Machinjiri Docs

Clone this wiki locally