Database Driver Interface

The DbDriverInterface is the core interface for all database drivers in AnyDataset-DB. It defines the standard methods that all database drivers must implement, providing a consistent API for interacting with different database systems.

Important

The high-level query methods of DbDriverInterface, deprecated in version 6.0, were removed in version 7.0 in favor of DatabaseExecutor. See the removed methods below and the DatabaseExecutor documentation for the recommended approach.

Interface Definition

All drivers in the AnyDataset-DB library implement this interface, which extends DbTransactionInterface:

interface DbDriverInterface extends DbTransactionInterface
{
    // Methods to implement
}

Available Methods

Connection Management

Method	Description
`schema()`	Static method that returns the supported schema(s) for the driver (e.g., 'mysql', 'pgsql')
`isConnected(bool $softCheck = false, bool $throwError = false): bool`	Checks if the connection is active
`reconnect(bool $force = false): bool`	Re-establishes a connection to the database
`disconnect(): void`	Closes the connection to the database
`getDbConnection(): mixed`	Returns the low-level database connection object
`getUri(): Uri`	Returns the connection URI

Low-Level Query Execution

Method	Description
`prepareStatement(string $sql, ?array $params = null, ?array &$cacheInfo = []): mixed`	Prepares an SQL statement for execution
`executeCursor(mixed $statement): void`	Executes a prepared statement
`processMultiRowset(mixed $statement): void`	Processes multiple result sets
`getDriverIterator(mixed $statement, int $preFetch = 0, ?string $entityClass = null, ?PropertyHandlerInterface $entityTransformer = null): GenericDbIterator\|GenericIterator`	Creates a driver-specific iterator from a statement
`getStatementFields(mixed $statement): array`	Returns the column names of an executed statement

High-Level Query Execution (Removed in 7.0)

Removed

Deprecated in version 6.0 and removed in version 7.0. Use DatabaseExecutor instead for these operations.

Method	Description	Replacement
`getIterator(string\|SqlStatement $sql, ?array $params = null, int $preFetch = 0): GenericDbIterator\|GenericIterator`	Executes a SELECT query and returns an iterator	`DatabaseExecutor::using($driver)->getIterator()`
`getScalar(mixed $sql, ?array $array = null): mixed`	Returns a single value from the first column of the first row	`DatabaseExecutor::using($driver)->getScalar()`
`execute(mixed $sql, ?array $array = null): bool`	Executes a non-query SQL statement	`DatabaseExecutor::using($driver)->execute()`
`executeAndGetId(string\|SqlStatement $sql, ?array $array = null): mixed`	Executes a query and returns the last inserted ID	`DatabaseExecutor::using($driver)->executeAndGetId()`
`getAllFields(string $tablename): array`	Gets all field names from a table	`DatabaseExecutor::using($driver)->getAllFields()`

Database Metadata and Helpers

Method	Description
`getSqlDialect(): SqlDialectInterface`	Returns a helper object with database-specific functions
`getSqlDialectClass(): string`	Returns the class name of the SQL dialect implementation

Advanced Settings

Method	Description
`isSupportMultiRowset(): bool`	Checks if the driver supports multiple result sets
`setSupportMultiRowset(bool $multipleRowSet): void`	Sets whether the driver should support multiple result sets

Logging

Method	Description
`enableLogger(LoggerInterface $logger): void`	Sets a PSR-3 compliant logger for the driver
`log(string $message, array $context = []): void`	Logs a message using the configured logger

Transaction Methods (from DbTransactionInterface)

The interface extends DbTransactionInterface, so it also includes these transaction methods:

Method	Description
`beginTransaction(?IsolationLevelEnum $isolationLevel = null, bool $allowJoin = false)`	Starts a new transaction (or joins the active one when `$allowJoin` is true)
`commitTransaction(): void`	Commits the current transaction
`rollbackTransaction(): void`	Rolls back the current transaction
`hasActiveTransaction(): bool`	Checks if there is an active transaction
`activeIsolationLevel(): ?IsolationLevelEnum`	Returns the isolation level of the current transaction
`remainingCommits(): int`	Number of commits left before the real commit (nested transactions)
`requiresTransaction(): void`	Throws `TransactionNotStartedException` if no transaction is active

Usage Example

Recommended Approach (Using DatabaseExecutor)

<?php
use ByJG\AnyDataset\Db\Factory;
use ByJG\AnyDataset\Db\DatabaseExecutor;
use ByJG\AnyDataset\Db\SqlStatement;
use ByJG\AnyDataset\Db\IsolationLevelEnum;

// Get a database driver instance
$dbDriver = Factory::getDbInstance('mysql://user:password@host/database');

// Create a DatabaseExecutor (recommended)
$executor = DatabaseExecutor::using($dbDriver);

// Connection management (still done through driver)
if (!$dbDriver->isConnected()) {
    $dbDriver->reconnect();
}

// Basic query execution (using executor)
$iterator = $executor->getIterator("SELECT * FROM users WHERE active = :active", [':active' => true]);
foreach ($iterator as $row) {
    echo $row->get('name') . "\n";
}

// Using SqlStatement
$sqlStatement = new SqlStatement(
    "SELECT * FROM users WHERE active = :active AND role = :role",
    [':active' => true]
);
$iterator = $executor->getIterator($sqlStatement, [':role' => 'admin']);

// Transaction example (can use either executor or driver)
$executor->beginTransaction(IsolationLevelEnum::Serializable);
try {
    $userId = $executor->executeAndGetId("INSERT INTO users (name, email) VALUES (:name, :email)", [
        ':name' => 'John Doe',
        ':email' => '[email protected]'
    ]);

    $executor->execute(
        "INSERT INTO user_roles (user_id, role) VALUES (:user_id, :role)",
        [':user_id' => $userId, ':role' => 'admin']
    );

    $executor->commitTransaction();
} catch (Exception $ex) {
    $executor->rollbackTransaction();
    throw $ex;
}

// Clean up (still done through driver)
$dbDriver->disconnect();

Legacy Approach (Deprecated)

<?php
use ByJG\AnyDataset\Db\Factory;

// Get a database driver instance
$dbDriver = Factory::getDbInstance('mysql://user:password@host/database');

// ⚠️ Removed in version 7.0: direct query methods on the driver no longer exist (6.x only)
$iterator = $dbDriver->getIterator("SELECT * FROM users WHERE active = :active", [':active' => true]);
foreach ($iterator as $row) {
    echo $row->get('name') . "\n";
}

Creating Custom Drivers

To create a custom database driver, you must implement the DbDriverInterface interface. The easiest way is to extend the DbPdoDriver abstract class, which provides many of the required implementations.

<?php
namespace MyApp\Database;

use ByJG\AnyDataset\Db\DbPdoDriver;
use Override;

class MyCustomDriver extends DbPdoDriver
{
    #[Override]
    public static function schema()
    {
        return "mycustom";
    }
    
    // Override other methods as needed
}

// Register your driver
\ByJG\AnyDataset\Db\Factory::registerDbDriver(MyCustomDriver::class);

// Now you can use it
$db = \ByJG\AnyDataset\Db\Factory::getDbInstance("mycustom://user:pass@host/db");

Removed Methods

The following methods were deprecated in version 6.0 and removed in version 7.0:

getIterator() - Use DatabaseExecutor::using($driver)->getIterator() instead
getScalar() - Use DatabaseExecutor::using($driver)->getScalar() instead
execute() - Use DatabaseExecutor::using($driver)->execute() instead
executeAndGetId() - Use DatabaseExecutor::using($driver)->executeAndGetId() instead
getAllFields() - Use DatabaseExecutor::using($driver)->getAllFields() instead

For a complete migration guide, see Deprecated Features.

Available Implementations

AnyDataset-DB provides several implementations of the DbDriverInterface:

Class	Schema	Description
`PdoMysql`	mysql, mariadb	MySQL and MariaDB driver
`PdoPgsql`	pgsql, postgres, postgresql	PostgreSQL driver
`PdoSqlite`	sqlite	SQLite driver
`PdoDuckdb`	duckdb	DuckDB driver (embedded analytics)
`PdoDblib`	dblib	SQL Server driver (using FreeTDS)
`PdoSqlsrv`	sqlsrv	SQL Server driver (using Microsoft driver)
`PdoOci`	oci, oracle	Oracle driver (using PDO OCI)
`DbOci8Driver`	oci8	Oracle driver (using OCI8 extension)
`PdoOdbc`	odbc	ODBC driver
`PdoPdo`	pdo	Generic PDO driver
`DbD1Driver`	d1	Cloudflare D1 driver (using the REST API)
`DatabaseRouter`	N/A	Special driver for routing queries to different databases

Interface Definition​

Available Methods​

Connection Management​

Low-Level Query Execution​

High-Level Query Execution (Removed in 7.0)​

Database Metadata and Helpers​

Advanced Settings​

Logging​

Transaction Methods (from DbTransactionInterface)​

Usage Example​

Recommended Approach (Using DatabaseExecutor)​

Legacy Approach (Deprecated)​

Creating Custom Drivers​

Removed Methods​

Available Implementations​

See Also​