PHP Luminova: PDO Database Driver
Learn how to use Luminova's PDO database driver to establish database connections, execute queries, manage transactions, and access native PDO functionality.
The PdoDriver class is Luminova's PDO based database driver. It implements DatabaseDriverInterface and gives you one API for prepared statements, value binding, result fetching, transactions, savepoints, and database level locks.
You normally don't create it yourself. The Connection class builds it when the connection setting is pdo.
Getting Started
Get the driver from a connection instance:
use Luminova\Database\Connection;
$db = Connection::getInstance()->database();Or create a standalone driver from a configuration object:
use App\Config\Database;
use Luminova\Database\Connection;
$db = Connection::with(Database::fromArray([
'connection' => 'pdo',
'pdo_driver' => 'mysql',
'host' => 'localhost',
'port' => 3306,
'database' => 'my_db',
'username' => 'root',
'password' => 'password',
]));Configuration keys used by this driver:
| Key | Default | Description |
|---|---|---|
pdo_driver | mysql | PDO driver name. Supported: mysql, pgsql, sqlite, sqlsrv, dblib, cubrid, oci. Any other value throws a DatabaseException. |
host | localhost | Database server host. |
port | 3306 | Database server port. |
database | '' | Database name. |
username | root | Database username. Ignored for SQLite. |
password | '' | Database password. Ignored for SQLite. |
charset | utf8mb4 | Connection charset. utf8 and utf-8 are converted to utf8mb4. |
sqlite_path | null | Path to the SQLite file. Required when pdo_driver is sqlite. |
emulate_prepares | true | Sets PDO::ATTR_EMULATE_PREPARES. |
persistent | false | Sets PDO::ATTR_PERSISTENT. Always enabled when running in the CLI. |
socket | false | MySQL only. Connect through a Unix socket instead of TCP. |
socket_path | '' | MySQL only. Unix socket path. |
buffered_query | false | MySQL only. Sets PDO::MYSQL_ATTR_USE_BUFFERED_QUERY. |
timeout | 0 | MySQL only. Sets PDO::ATTR_TIMEOUT in seconds when greater than zero. |
commands | [] | MySQL only. List of SET statements to run when the connection opens. |
Additional Notes
Error mode and fetch mode:The driver always connects with
PDO::ERRMODE_EXCEPTIONandPDO::FETCH_OBJas the default fetch mode.Unix socket (MySQL):A socket connection is used when running in the CLI, when
socketistrue, or when running inside thenovakitcontainer. The driver readssocket_path, then falls back topdo_mysql.default_socketfromphp.ini. ADatabaseExceptionis thrown when neither is set.Init commands (MySQL):Only
SETstatements are allowed incommands, any other statement throws aDatabaseException. If none of them is aSET NAMESstatement,SET NAMES <charset>is added automatically.SSL (MySQL):Server certificate verification is turned on in production.
Missing connection:Methods that need a live connection throw a
DatabaseExceptionwhen called beforeconnect()or afterclose().Differences from MySQLi:Row counts, binding lifetime, and savepoint handling differ between the two drivers. See Driver differences in the MySQLi driver docs.
Basic Usage
Select rows with a prepared statement:
use Luminova\Database\Connection;
$db = Connection::getInstance()->database();
$db->prepare('SELECT * FROM users WHERE status = :status')
->bind(':status', 'active')
->execute();
$users = $db->fetchAll();Insert a row and read its ID:
$db->prepare('INSERT INTO users (name, email) VALUES (:name, :email)')
->execute([':name' => 'John Doe', ':email' => '[email protected]']);
$id = $db->getLastInsertId();Read rows one at a time:
$db->query('SELECT id, name FROM users');
while ($row = $db->fetchNext()) {
echo $row->name;
}Run a transaction:
use Throwable;
try {
$db->beginTransaction();
$db->prepare('UPDATE accounts SET balance = balance - :amount WHERE id = :id')
->execute([':amount' => 100, ':id' => 1]);
$db->prepare('UPDATE accounts SET balance = balance + :amount WHERE id = :id')
->execute([':amount' => 100, ':id' => 2]);
$db->commit();
} catch (Throwable $e) {
$db->rollback();
throw $e;
}Class Definition
- Class namespace:
Luminova\Database\Driver\PdoDriver - This class is
finaland extendsLuminova\Database\Driver\Helpers\AbstractBaseDriver - This class implements: \Luminova\Interface\DatabaseDriverInterface
Constants
Inherited from AbstractBaseDriver and accessed through the driver class, for example PdoDriver::TRANSACTION_READ_ONLY.
| Constant | Value | Used with |
|---|---|---|
TRANSACTION_MODE_NONE | 0 | Skips changing the transaction mode. |
TRANSACTION_WITH_CONSISTENT_SNAPSHOT | 1 | beginTransaction() flag. |
TRANSACTION_READ_WRITE | 2 | beginTransaction() flag. |
TRANSACTION_READ_UNCOMMITTED | 3 | setTransactionIsolation() level. |
TRANSACTION_READ_ONLY | 4 | beginTransaction() flag. |
TRANSACTION_READ_COMMITTED | 5 | setTransactionIsolation() level. |
TRANSACTION_REPEATABLE_READ | 6 | setTransactionIsolation() level. |
TRANSACTION_SERIALIZABLE | 7 | setTransactionIsolation() level. |
Only
TRANSACTION_WITH_CONSISTENT_SNAPSHOT,TRANSACTION_READ_WRITEandTRANSACTION_READ_ONLYare bit flags. Don't pass isolation level constants tobeginTransaction(), their values overlap with the flag bits.
Methods
constructor
Creates the driver from a configuration object. The PDO driver name is read from pdo_driver and lowercased. It does not connect, call connect() to open the connection.
public __construct(Luminova\Config\DatabaseConfig $config)getInstance
Returns a shared driver instance, creating it with $config on the first call. The $config argument is ignored on later calls.
public static getInstance(Luminova\Config\DatabaseConfig $config): DatabaseDriverInterfaceThe shared instance is stored on
AbstractBaseDriver, soPdoDriverand MysqliDriver` share one slot. Whichever driver is created first is returned by later calls on either class.
connect
Opens the PDO connection. If the connection already exists, it returns true without reconnecting.
public connect(): boolReturn Value:
bool - Return true when connected.
Throws:
- \Luminova\Exceptions\DatabaseException - If the PDO driver is unsupported, the SQLite path is missing, an init command is invalid, a socket path is required but missing, or the connection fails. Other errors are wrapped in a
DatabaseException.
isConnected
Checks the driver's connection state. It does not ping the server.
public isConnected(): boolclose
Frees the active statement, releases the PDO object, and decrements the open connection count.
public close(): voidgetDriver
Gets the PDO driver name reported by PDO::ATTR_DRIVER_NAME, for example mysql.
public getDriver(): ?stringReturn Value:
string|null - Return the driver name, or null when not connected.
getVersion
Gets the database server version string for the active PDO driver.
public getVersion(): ?stringReturn Value:
string|null - Return the version string, or null if it cannot be determined.
getConfig
Gets one configuration value, or all values when $property is null. Property names are trimmed and case insensitive.
public getConfig(?string $property): mixedReturn Value:
mixed - Return the value, null for an empty or unknown key, or the full configuration array when $property is null.
getConn
Gets the driver connection wrapper, which gives access to the native PDO object.
public getConn(): Luminova\Interface\DriverConnectionInterfacegetOpenConnections
Gets the number of open driver connections. The counter is static, so it is shared by all driver instances.
public static getOpenConnections(): intexists
Checks whether a table exists in the current database. It runs its own prepared statement, so it replaces the current statement.
public exists(string $table): boolExample:
if ($db->exists('users')) {
// The table is there
}prepare
Prepares an SQL statement and resets the previous query state. Use named placeholders such as :id.
public prepare(string $query): selfThrows:
- \Luminova\Exceptions\DatabaseException - If there is no active connection.
bind
Binds a value to a named placeholder using PDOStatement::bindValue().
public bind(string $param, mixed $value, ?int $type = null): selfParameters:
| Parameter | Type | Description |
|---|---|---|
$param | string | Named placeholder, for example :id. |
$value | mixed | The value to bind. |
$type | int|null | A PARAM_* constant or a native PDO::PARAM_* value. null resolves the type from the value with getType(). |
Return Value:
self - Return the driver instance.
Throws:
- \Luminova\Exceptions\DatabaseException - If there is no prepared statement.
PARAM_FLOATis bound as a string, because PDO has no float type.
value
Alias of bind().
public value(string $param, mixed $value, ?int $type = null): selfparam
Binds a variable by reference using PDOStatement::bindParam(). The variable is read when execute() runs, so changes made before then are used.
public param(string $param, mixed &$value, ?int $type = null): selfExample:
$status = 'active';
$db->prepare('UPDATE users SET status = :status WHERE id = :id')
->param(':status', $status)
->bind(':id', 100);
$status = 'inactive';
$db->execute();getType
Resolves the PDO parameter type for a value.
public static getType(mixed $value): int| Value | Result |
|---|---|
null | PDO::PARAM_NULL |
bool | PDO::PARAM_BOOL |
int | PDO::PARAM_INT |
| resource | PDO::PARAM_LOB |
| string with any byte outside tab, line breaks and printable ASCII | PDO::PARAM_LOB |
| everything else | PDO::PARAM_STR |
The string check is byte based, so multibyte UTF-8 text is resolved as
PDO::PARAM_LOB. Pass an explicit$typetobind()if you needPARAM_STR.
execute
Executes the prepared statement. When $params is given, PDO uses it as the full set of input parameters.
public execute(?array $params = null): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$params | array|null | Values for the placeholders, keyed by name (:id) or in positional order. |
Return Value:
bool - Return true on success.
Throws:
- \Luminova\Exceptions\DatabaseException - If there is no prepared statement or the execution fails. On failure the statement is freed.
query
Runs an SQL query immediately, without placeholders, and keeps the result for fetching.
public query(string $query): selfExample:
$users = $db->query('SELECT * FROM users')->fetchAll();exec
Runs an SQL statement without placeholders and returns the affected row count.
public exec(string $query): intReturn Value:
int - Return 0 when the statement fails, otherwise the affected rows with a minimum of 1. DDL statements that report no row count return 1.
Example:
$affected = $db->exec("UPDATE users SET status = 'active' WHERE last_login > NOW() - INTERVAL 30 DAY");ok
Checks whether the last query was executed successfully.
public ok(): boolExample:
$db->prepare('SELECT * FROM users WHERE id = :id')->bind(':id', 100);
$db->execute();
if ($db->ok()) {
$user = $db->fetchNext();
}getResult
Retrieves a result in the shape given by $returnMode.
public getResult(int $returnMode = RETURN_ALL, int $fetchAS = FETCH_OBJ): mixed| Return mode | Same as |
|---|---|
RETURN_NEXT | fetchNext($fetchAS) |
RETURN_ALL | fetchAll($fetchAS) |
RETURN_2D_NUM | getInt() |
RETURN_INT | getCount() |
RETURN_ID | getLastInsertId() |
RETURN_COUNT | rowCount() |
RETURN_COLUMN | getColumns() |
RETURN_STMT | getStatement() |
RETURN_RESULT | The PDOStatement, or null when there is none. |
| Any other value | fetch($returnMode, $fetchAS) |
$fetchAS is only used with RETURN_NEXT, RETURN_ALL, and the fallback to fetch().
fetch
Fetches rows from the active statement.
public fetch(int $returnMode = RETURN_ALL, int $fetchAS = FETCH_OBJ): mixedParameters:
| Parameter | Type | Description |
|---|---|---|
$returnMode | int | RETURN_ALL fetches all rows. RETURN_NEXT and RETURN_STREAM fetch one row per call. |
$fetchAS | int | One of FETCH_ASSOC, FETCH_BOTH, FETCH_OBJ, FETCH_COLUMN, FETCH_KEY_PAIR, FETCH_NUM, FETCH_CLASS. An unknown value falls back to FETCH_OBJ. |
Return Value:
mixed - Return an array of rows for RETURN_ALL (empty when there are none), or a single row, or false when no more rows are left.
Throws:
- \Luminova\Exceptions\DatabaseException - If there is no statement.
With
FETCH_CLASSrows are returned asstdClass. To hydrate your own class, usefetchObject()orfetchAllObject().
Example:
$db->query('SELECT id, name FROM users');
$names = $db->fetch(RETURN_ALL, FETCH_KEY_PAIR);fetchNext
Fetches the next row.
public fetchNext(int $mode = FETCH_OBJ): array|object|boolReturn Value:
array|object|false - Return the row, or false when no more rows are available.
getNext
Alias of fetchNext().
public getNext(int $mode = FETCH_OBJ): array|object|boolfetchAll
Fetches all remaining rows.
public fetchAll(int $mode = FETCH_OBJ): array|object|boolReturn Value:
array|object|false - Return the rows, or false when the result is empty.
getAll
Alias of fetchAll().
public getAll(int $mode = FETCH_OBJ): array|object|boolfetchObject
Fetches the next row as an instance of a class. Without $class, a stdClass is returned.
public fetchObject(?string $class = null, mixed ...$arguments): ?objectParameters:
| Parameter | Type | Description |
|---|---|---|
$class | class-string|null | Class to instantiate. Defaults to stdClass. |
...$arguments | mixed | Constructor arguments for the class. |
Return Value:
object|null - Return the instance, or null when there is no row.
Example:
$db->prepare('SELECT * FROM users WHERE id = :id');
$db->execute([':id' => 1]);
$user = $db->fetchObject(App\Models\User::class);fetchAllObject
Fetches all remaining rows as instances of a class. Without $class, stdClass objects are returned.
public fetchAllObject(?string $class = null, mixed ...$arguments): arrayReturn Value:
array - Return a list of instances, empty when there are no rows.
getColumns
Fetches all rows using a column oriented fetch mode.
public getColumns(int $mode = FETCH_COLUMN): arrayReturn Value:
array - Return the values of the first column by default, or an empty array.
getInt
Fetches all rows as numeric arrays.
public getInt(): arraygetCount
Reads the first value of the first row as an integer, which suits queries like SELECT COUNT(*).
public getCount(): intReturn Value:
int - Return the value, or 0 when there are no results.
getLastInsertId
Gets the ID generated by the last INSERT. Pass a sequence name for databases that use sequences, such as PostgreSQL.
public getLastInsertId(?string $name = null): mixedReturn Value:
mixed - Return the ID, or null when there is none or the driver is not connected.
rowCount
Gets the number of rows affected or returned by the active statement, as reported by PDOStatement::rowCount().
public rowCount(): intcolumnCount
Gets the number of columns in the active result set.
public columnCount(): intgetStatement
Gets the active PDOStatement.
public getStatement(): ?PDOStatementisStatement
Checks whether there is an active PDOStatement.
public isStatement(): boolisResult
Checks whether the last operation was run through query() or exec() and nothing has been bound since.
public isResult(): boolhasActiveCursor
Checks whether the active statement has columns, meaning it can return rows. This method exists on PdoDriver only.
public hasActiveCursor(): boolfree
Closes the statement cursor and clears the active statement.
public free(): voidbeginTransaction
Starts a transaction, optionally with flags and a savepoint name.
public beginTransaction(int $flags = PdoDriver::TRANSACTION_MODE_NONE, ?string $name = null): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$flags | int | Combine TRANSACTION_WITH_CONSISTENT_SNAPSHOT, TRANSACTION_READ_WRITE and TRANSACTION_READ_ONLY with \|. They are sent as START TRANSACTION .... |
$name | string|null | Creates a savepoint with this name after the transaction starts. Required when a transaction is already active. |
Return Value:
bool - Return true when the transaction (and savepoint) started.
Throws:
- \Luminova\Exceptions\DatabaseException - If a transaction is active and
$nameis null, the savepoint name is invalid or already used, or the transaction fails to start.
Example:
$db->beginTransaction(
PdoDriver::TRANSACTION_WITH_CONSISTENT_SNAPSHOT | PdoDriver::TRANSACTION_READ_ONLY
);tryBeginTransaction
Same as beginTransaction(), but returns false instead of throwing.
public tryBeginTransaction(int $flags = PdoDriver::TRANSACTION_MODE_NONE, ?string $name = null): boolbeginNestedTransaction
Starts a transaction when none is active, otherwise creates a savepoint with a generated name.
public beginNestedTransaction(int $flags = PdoDriver::TRANSACTION_MODE_NONE, bool $closeCursor = false): string|bool|nullParameters:
| Parameter | Type | Description |
|---|---|---|
$flags | int | Transaction flags, used only when a new transaction starts. |
$closeCursor | bool | Free the active statement before starting. |
Return Value:
string|bool|null - Return null when a new transaction started, the savepoint name for a nested transaction, or false on failure.
Example:
$name = $db->beginNestedTransaction();
if ($name === false) {
return;
}
try {
// Run queries...
if ($name !== null) {
$db->release($name);
} else {
$db->commit();
}
} catch (Throwable $e) {
$db->rollback();
throw $e;
}tryBeginNestedTransaction
Same as beginNestedTransaction(), but returns false instead of throwing.
public tryBeginNestedTransaction(
int $flags = PdoDriver::TRANSACTION_MODE_NONE,
bool $closeCursor = false
): string|bool|nullsavepoint
Creates a savepoint inside the active transaction.
public savepoint(string $name): boolNames are cleaned before use: characters other than letters, digits and underscores are removed, purely numeric names get a tnx_ prefix, and the result is cut to 64 characters. The same cleaning is applied in commit(), rollback() and release(), so you can pass the original name to them.
Throws:
- \Luminova\Exceptions\DatabaseException - If there is no active transaction, the name is empty after cleaning, or the savepoint already exists.
commit
Commits the active transaction, or releases a savepoint when $name is given. Returns true when no transaction is active.
public commit(int $flags = 0, ?string $name = null): bool
$flagsis not used by the PDO driver.
Throws:
- \Luminova\Exceptions\DatabaseException - If the savepoint does not exist or the commit fails.
rollback
Rolls back the active transaction, or rolls back to a savepoint when $name is given. Returns true when no transaction is active.
public rollback(int $flags = 0, ?string $name = null): bool
$flagsis not used by the PDO driver.
Throws:
- \Luminova\Exceptions\DatabaseException - If the savepoint does not exist or the rollback fails.
release
Releases a savepoint without ending the transaction. Returns false when no transaction is active.
public release(string $name): boolinTransaction
Checks whether a transaction is active, using the native PDO::inTransaction().
public inTransaction(): boolsetTransactionIsolation
Sets the isolation level with SET TRANSACTION ISOLATION LEVEL. Call it before a transaction starts.
public setTransactionIsolation(int $level = PdoDriver::TRANSACTION_READ_COMMITTED): boolParameters:
| Parameter | Type | Description |
|---|---|---|
$level | int | TRANSACTION_READ_UNCOMMITTED, TRANSACTION_READ_COMMITTED, TRANSACTION_REPEATABLE_READ or TRANSACTION_SERIALIZABLE. TRANSACTION_MODE_NONE does nothing and returns true. |
Throws:
- \Luminova\Exceptions\DatabaseException - If the level is invalid, a transaction is already active, or the database rejects the statement.
TRANSACTION_READ_WRITEandTRANSACTION_READ_ONLYare not isolation levels. Pass them as flags tobeginTransaction()instead.
lock
Acquires a named database lock and waits up to $timeout seconds.
public lock(string|int $identifier, int $timeout = 300): boolThe lock mechanism depends on the database: MySQL named locks, PostgreSQL advisory locks (non numeric identifiers are hashed), and for SQLite a lease table named dbms_locks, created on first use. $timeout does not apply to PostgreSQL.
Return Value:
bool - Return true if the lock was acquired.
Example:
if ($db->lock('daily-report', 30)) {
try {
// Do the work
} finally {
$db->unlock('daily-report');
}
}tryLock
Attempts to acquire a lock without waiting.
public tryLock(string|int $identifier): boolThis method currently returns
falsewhatever the outcome. The result is stored internally, so callisLocked()to find out whether the lock was acquired.
unlock
Releases a named lock.
public unlock(string|int $identifier): boolisLocked
Checks whether a lock is held. A lock acquired or released through this driver instance is answered from memory, otherwise the database is queried.
public isLocked(string|int $identifier): boolerror
Gets the last error message from the active statement, or from the connection when there is no statement.
public error(): stringReturn Value:
string - Return the message, an empty string if none, or Connection not established when not connected.
errors
Gets statement and connection error details.
public errors(): arrayReturn Value:
array - Return the following structure.
| Key | Description |
|---|---|
statement.errno | SQLSTATE code, or -1 when there is no statement. |
statement.error | Driver error message, or null. |
statement.num_rows | Row count of the statement, or null when there is no statement. |
connection.errno | SQLSTATE code, or -1 when not connected. |
connection.error | Driver error message, or Connection not established. |
info
Gets the parsed PDO::ATTR_CONNECTION_STATUS value as key and value pairs.
public info(): arrayReturn Value:
array - Return ['status' => 'disconnected'] when not connected, ['status' => 'idle'] when the driver reports nothing, otherwise the parsed pairs (empty if the status text has no key: value parts).
setDebug
Enables or disables debug mode.
public setDebug(bool $debug): selfdumpDebug
Dumps the active statement's parameters with PDOStatement::debugDumpParams() when debug mode is on.
public dumpDebug(): boolReturn Value:
bool - Return false when debug mode is off or there is no statement.
profiling
Starts or stops query timing. Timing is recorded only when profiling is enabled by the debug.show.performance.profiling environment setting. The driver calls it for you around each query, so you rarely need it directly.
public profiling(bool $start = true, bool $finishedTransaction = false, ?string $fn = null): voidWhile a transaction is active, timing is held back until the transaction is committed or rolled back. Results are stored under Runtime::QUERY_PROFILING:
use Luminova\Runtime;
$profiling = Runtime::get(Runtime::QUERY_PROFILING);getQueryTime
Gets the total query execution time in seconds.
public getQueryTime(): float|intgetLastQueryTime
Gets the last query execution time in seconds.
public getLastQueryTime(): float|intBoth timing methods return
0unless profiling is enabled.