Configuration

Configuration

Every entry point — DB::createImmutable(), DB::connect(), new Database(...), Model::$credentials — accepts the same connection array shape. This page is the canonical reference for every supported field, with examples for the common drivers.

The full credential shape

[
// 1. EITHER pass a fully-formed DSN ...'dsn' => 'mysql:host=localhost;port=3306;dbname=test;charset=utf8mb4',
// 2. ... OR let the package build one from the parts:'driver' => 'mysql', // mysql | pgsql | sqlite | any PDO driver name'host' => '127.0.0.1',
'port' => 3306,
'database' => 'test',
'username' => 'root',
'password' => '',
// Connection-level character set (applied via SET NAMES after connect, MySQL only)'charset' => 'utf8mb4',
'collation' => 'utf8mb4_unicode_ci',
// PDO options (passed to `new PDO(..., ..., ..., $options)`)'options' => [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
],
// Options forwarded to every prepare() (e.g. PDO::ATTR_CURSOR)'queryOptions' => [],
// Optional channels'log' => null, // null | string | callable | object | Psr\Log\LoggerInterface'debug' => false, // include compiled SQL in error messages'queryLogs' => false, // start with the in-memory query log enabled
]

If both dsn and the driver-shaped fields are present, dsn wins. The other fields are still kept on the credential object for code that reads them (getDriver(), getDatabaseName()).

Per-driver examples

MySQL / MariaDB

DB::createImmutable([
'dsn' => 'mysql:host=db.internal;port=3306;dbname=app;charset=utf8mb4',
'username' => 'app',
'password' => getenv('DB_PASSWORD') ?: '',
'charset' => 'utf8mb4',
'collation' => 'utf8mb4_unicode_ci',
]);

Equivalent without a DSN:

DB::createImmutable([
'driver' => 'mysql',
'host' => 'db.internal',
'port' => 3306,
'database' => 'app',
'username' => 'app',
'password' => getenv('DB_PASSWORD') ?: '',
'charset' => 'utf8mb4',
]);

PostgreSQL

DB::createImmutable([
'driver' => 'pgsql',
'host' => 'pg.internal',
'port' => 5432,
'database' => 'app',
'username' => 'app',
'password' => getenv('DB_PASSWORD') ?: '',
'charset' => 'UTF8',
]);

charset and collation apply only to MySQL (the package issues SET NAMES … COLLATE … after connect). On PostgreSQL the encoding comes from the cluster / database itself; leave the fields default.

SQLite — file

DB::createImmutable([
'driver' => 'sqlite',
'database' => __DIR__ . '/data/app.sqlite',
'charset' => '',
]);

SQLite — in-memory

DB::createImmutable([
'driver' => 'sqlite',
'database' => ':memory:',
'charset' => '',
]);

Each PDO handle opens its own :memory: database, so any schema / seed data must be applied to the same handle the application uses.

Field reference

Field	Type	Default	Notes
dsn	string	''	Full PDO DSN. Wins over the field-shaped form when present.
driver	string	'mysql'	Used to pick the QueryBuilder dialect (mysql, pgsql, sqlite, generic).
host	string	'127.0.0.1'	Ignored for sqlite.
port	int|string	3306	Ignored for sqlite.
database	string	''	Database name (or path for SQLite).
username	string|null	null
password	string|null	null
charset	string	'utf8mb4'	Used in SET NAMES (MySQL only). Must match ^[A-Za-z0-9_]+$.
collation	string|null	null	Appended as COLLATE … after SET NAMES. Same identifier rule.
options	array<int, mixed>	[]	Passed to new PDO(..., ..., ..., $options).
queryOptions	array<int, mixed>	[]	Passed to every prepare().
log	mixed	null	The log channel — see Query Logging.
debug	bool	false	Include compiled SQL in SQLExecuteException messages — dev only.
queryLogs	bool	false	Start the in-memory query log already enabled.

Identifier safety

The package validates charset, collation and driver against ^[A-Za-z0-9_]+$ before interpolating them into SET NAMES — that statement cannot be parameter-bound. If you set any of those to a value containing other characters, the constructor throws InitORM\DBAL\Connection\Exceptions\ConnectionInvalidArgumentException.

The rest of the package never interpolates user input into SQL — every column / table identifier flows through driver-specific escaping (backticks on MySQL/SQLite, double quotes on PostgreSQL), and every value goes through prepared-statement parameter binding. See Reserved Keywords for a worked example.

Bootstrapping patterns

Single config file

// config/database.phpreturn [
'dsn' => sprintf('mysql:host=%s;port=%d;dbname=%s;charset=utf8mb4',
getenv('DB_HOST') ?: '127.0.0.1',
(int) (getenv('DB_PORT') ?: 3306),
getenv('DB_NAME') ?: 'app',
),
'username' => getenv('DB_USER') ?: 'root',
'password' => getenv('DB_PASSWORD') ?: '',
'debug' => filter_var(getenv('APP_DEBUG'), FILTER_VALIDATE_BOOL),
];

// public/index.php
\InitPHP\Database\DB::createImmutable(require__DIR__ . '/../config/database.php');

Dependency-injected, no facade

$db = new \InitPHP\Database\Database($credentials);
$container->set(\InitORM\Database\Interfaces\DatabaseInterface::class, $db);

This skips the static facade entirely — your code references the DatabaseInterface directly. Useful in long-lived workers where you want to test substitution without globals.

Next

• Quick Start — get something running first.
• Query Builder — the chainable surface.
• Multiple Connections — secondary databases.
• Debugging — what debug=true actually does.