Class Driver

Represents a database driver containing all specificities for a database engine including its SQL dialect.

Abstract
Namespace: Cake\Database

Constants

int|null

MAX_ALIAS_LENGTH ¶
```
null
```
array<int>

RETRY_ERROR_CODES ¶
```
[]
```
class-string<Cake\Database\Statement\Statement>

STATEMENT_CLASS ¶
```
Statement::class
```

Property Summary

$_autoQuoting protected

bool

Indicates whether the driver is doing automatic identifier quoting for all queries
$_baseConfig protected

array<string, mixed>

Base configuration that is merged into the user supplied configuration data.
$_config protected

array<string, mixed>

Configuration data.
$_endQuote protected

string

String used to end a database identifier quoting to make it safe
$_schemaDialect protected

Cake\Database\Schema\SchemaDialect

The schema dialect for this driver
$_startQuote protected

string

String used to start a database identifier quoting to make it safe
$_version protected

string|null

The server version
$connectRetries protected

int

The last number of connection retry attempts.
$logQueries protected

bool

Whether to log queries generated during this connection.
$logger protected

?LoggerInterface

The logger instance.
$pdo protected

PDO|null

Instance of PDO.
$quoter protected

Cake\Database\IdentifierQuoter|null

Identifier quoter

Method Summary

__construct() public

Constructor
__debugInfo() public

Returns an array that can be used to describe the internal state of this object.
__destruct() public

Destructor
_deleteQueryTranslator() protected

Apply translation steps to delete queries.
_expressionTranslators() protected

Returns an associative array of methods that will transform Expression objects to conform with the specific SQL dialect. Keys are class names and values a method in this class.
_insertQueryTranslator() protected

Apply translation steps to insert queries.
_removeAliasesFromConditions() protected

Removes aliases from the WHERE clause of a query.
_selectQueryTranslator() protected

Apply translation steps to select queries.
_transformDistinct() protected

Returns the passed query after rewriting the DISTINCT clause, so that drivers that do not support the "ON" part can provide the actual way it should be done
_updateQueryTranslator() protected

Apply translation steps to update queries.
beginTransaction() public

Starts a transaction.
commitTransaction() public

Commits a transaction.
compileQuery() public

Transforms the passed query to this Driver's dialect and returns an instance of the transformed query and the full compiled SQL string.
config() public

Get the configuration data used to create the driver.
connect() abstract public

Establishes a connection to the database server.
createLogger() protected

Create logger instance.
createPdo() protected

Establishes a connection to the database server
createQueryException() protected

Create a QueryException from a PDOException
disableAutoQuoting() public

Disable auto quoting of identifiers in queries.
disableForeignKeySQL() abstract public

Get the SQL for disabling foreign keys.
disableQueryLogging() public

Disable query logging.
disconnect() public

Disconnects from database server.
enableAutoQuoting() public

Sets whether this driver should automatically quote identifiers in queries.
enableForeignKeySQL() abstract public

Get the SQL for enabling foreign keys.
enableQueryLogging() public

Enable query logging.
enabled() abstract public

Returns whether php is able to use this driver for connecting to database.
exec() public

Execute the SQL query using the internal PDO instance.
execute() public

Executes a query using $params for interpolating values and $types as a hint for each those params.
executeStatement() protected

Execute the statement and log the query string.
getLogger() public

Get the logger instance.
getMaxAliasLength() public

Returns the maximum alias length allowed.
getPdo() protected

Get the PDO connection instance.
getResultSetDecorators() protected

Returns the decorators to be applied to the result set incase of a SelectQuery.
getRole() public

Returns the connection role this driver performs.
inTransaction() public

Returns whether a transaction is active for connection.
isAutoQuotingEnabled() public

Returns whether this driver should automatically quote identifiers in queries.
isConnected() public

Checks whether the driver is connected.
lastInsertId() public

Returns last id generated for a table or sequence in database.
log() public

Logs a message or query using the configured logger object.
newCompiler() public
newTableSchema() public

Constructs new TableSchema.
prepare() public

Prepares a sql statement to be executed.
quote() public

Quotes a database value.
quoteIdentifier() public

Quotes a database identifier (a column name, table name, etc..) to be used safely in queries without the risk of using reserved words
quoter() public

Get identifier quoter instance.
releaseSavePointSQL() public

Returns a SQL snippet for releasing a previously created save point
rollbackSavePointSQL() public

Returns a SQL snippet for rollbacking a previously created save point
rollbackTransaction() public

Rollbacks a transaction.
run() public

Executes the provided query after compiling it for the specific driver dialect and returns the executed Statement object.
savePointSQL() public

Returns a SQL snippet for creating a new transaction savepoint
schema() public

Returns the schema name that's being used.
schemaDialect() abstract public

Get the schema dialect.
schemaValue() public

Escapes values for use in schema definitions.
setLogger() public

Sets a logger.
supports() abstract public

Returns whether the driver supports the feature.
transformQuery() protected

Transform the query to accommodate any specificities of the SQL dialect in use.
version() public

Returns connected server version.

Method Detail

__construct() ¶ public

__construct(array<string, mixed> $config = [])

Constructor

Parameters

array<string, mixed> $config optional: The configuration for the driver.

Throws

InvalidArgumentException

__debugInfo() ¶ public

__debugInfo(): array<string, mixed>

Returns an array that can be used to describe the internal state of this object.

Returns

array<string, mixed>

__destruct() ¶ public

__destruct()

Destructor

_deleteQueryTranslator() ¶ protected

_deleteQueryTranslator(Cake\Database\Query\DeleteQuery $query): Cake\Database\Query\DeleteQuery

Apply translation steps to delete queries.

Chops out aliases on delete query conditions as most database dialects do not support aliases in delete queries. This also removes aliases in table names as they frequently don't work either.

We are intentionally not supporting deletes with joins as they have even poorer support.

Parameters

Cake\Database\Query\DeleteQuery $query: The query to translate

Returns

Cake\Database\Query\DeleteQuery

The modified query

_expressionTranslators() ¶ protected

_expressionTranslators(): array<class-string, string>

Returns an associative array of methods that will transform Expression objects to conform with the specific SQL dialect. Keys are class names and values a method in this class.

Returns

array<class-string, string>

_insertQueryTranslator() ¶ protected

_insertQueryTranslator(Cake\Database\Query\InsertQuery $query): Cake\Database\Query\InsertQuery

Apply translation steps to insert queries.

Parameters

Cake\Database\Query\InsertQuery $query: The query to translate

Returns

Cake\Database\Query\InsertQuery

The modified query

_removeAliasesFromConditions() ¶ protected

_removeAliasesFromConditions(Cake\Database\Query\UpdateQuery|Cake\Database\Query\DeleteQuery $query): Cake\Database\Query\UpdateQuery|Cake\Database\Query\DeleteQuery

Removes aliases from the WHERE clause of a query.

Templates


              T
               of (\Cake\Database\Query\UpdateQuery | \Cake\Database\Query\DeleteQuery)

Parameters

Cake\Database\Query\UpdateQuery|Cake\Database\Query\DeleteQuery $query: The query to process.

Returns

Cake\Database\Query\UpdateQuery|Cake\Database\Query\DeleteQuery

The modified query.

Throws

Cake\Database\Exception\DatabaseException
In case the processed query contains any joins, as removing aliases from the conditions can break references to the joined tables.

_selectQueryTranslator() ¶ protected

_selectQueryTranslator(Cake\Database\Query\SelectQuery<mixed> $query): Cake\Database\Query\SelectQuery<mixed>

Apply translation steps to select queries.

Parameters

Cake\Database\Query\SelectQuery<mixed> $query: The query to translate

Returns

Cake\Database\Query\SelectQuery<mixed>

The modified query

_transformDistinct() ¶ protected

_transformDistinct(Cake\Database\Query\SelectQuery<mixed> $query): Cake\Database\Query\SelectQuery<mixed>

Returns the passed query after rewriting the DISTINCT clause, so that drivers that do not support the "ON" part can provide the actual way it should be done

Parameters

Cake\Database\Query\SelectQuery<mixed> $query: The query to be transformed

Returns

Cake\Database\Query\SelectQuery<mixed>

_updateQueryTranslator() ¶ protected

_updateQueryTranslator(Cake\Database\Query\UpdateQuery $query): Cake\Database\Query\UpdateQuery

Apply translation steps to update queries.

Chops out aliases on update query conditions as not all database dialects do support aliases in update queries.

Just like for delete queries, joins are currently not supported for update queries.

Parameters

Cake\Database\Query\UpdateQuery $query: The query to translate

Returns

Cake\Database\Query\UpdateQuery

The modified query

beginTransaction() ¶ public

beginTransaction(): bool

Starts a transaction.

Returns

bool

True on success, false otherwise.

commitTransaction() ¶ public

commitTransaction(): bool

Commits a transaction.

Returns

bool

True on success, false otherwise.

compileQuery() ¶ public

compileQuery(Cake\Database\Query $query, Cake\Database\ValueBinder $binder): string

Transforms the passed query to this Driver's dialect and returns an instance of the transformed query and the full compiled SQL string.

Parameters

Cake\Database\Query $query: The query to compile.
Cake\Database\ValueBinder $binder: The value binder to use.

Returns

string

The compiled SQL.

config() ¶ public

config(): array<string, mixed>

Get the configuration data used to create the driver.

Returns

array<string, mixed>

connect() ¶ abstract public

connect(): void

Establishes a connection to the database server.

Returns

void

Throws

Cake\Database\Exception\MissingConnectionException
If database connection could not be established.

createLogger() ¶ protected

createLogger(string|null $className): Psr\Log\LoggerInterface

Create logger instance.

Parameters

string|null $className: Logger's class name

Returns

Psr\Log\LoggerInterface

createPdo() ¶ protected

createPdo(string $dsn, array<string, mixed> $config): PDO

Establishes a connection to the database server

Parameters

string $dsn: A Driver-specific PDO-DSN
array<string, mixed> $config: configuration to be used for creating connection

Returns

PDO

createQueryException() ¶ protected

createQueryException(PDOException $exception, Cake\Database\StatementInterface $statement, array|null $params = null): Cake\Database\Exception\QueryException

Create a QueryException from a PDOException

Parameters

PDOException $exception
Cake\Database\StatementInterface $statement
array|null $params optional

Returns

Cake\Database\Exception\QueryException

disableAutoQuoting() ¶ public

disableAutoQuoting(): $this

Disable auto quoting of identifiers in queries.

Returns

$this

disableForeignKeySQL() ¶ abstract public

disableForeignKeySQL(): string

Get the SQL for disabling foreign keys.

Returns

string

disableQueryLogging() ¶ public

disableQueryLogging(): $this

Disable query logging.

Returns

$this

disconnect() ¶ public

disconnect(): void

Disconnects from database server.

Returns

void

enableAutoQuoting() ¶ public

enableAutoQuoting(bool $enable = true): $this

Sets whether this driver should automatically quote identifiers in queries.

Parameters

bool $enable optional: Whether to enable auto quoting

Returns

$this

enableForeignKeySQL() ¶ abstract public

enableForeignKeySQL(): string

Get the SQL for enabling foreign keys.

Returns

string

enableQueryLogging() ¶ public

enableQueryLogging(): $this

Enable query logging.

Returns

$this

enabled() ¶ abstract public

enabled(): bool

Returns whether php is able to use this driver for connecting to database.

Returns

bool

True if it is valid to use this driver.

exec() ¶ public

exec(string $sql): int|false

Execute the SQL query using the internal PDO instance.

Parameters

string $sql: SQL query.

Returns

int|false

execute() ¶ public

execute(string $sql, array $params = [], array $types = []): Cake\Database\StatementInterface

Executes a query using $params for interpolating values and $types as a hint for each those params.

Parameters

string $sql: SQL to be executed and interpolated with $params
array $params optional: List or associative array of params to be interpolated in $sql as values.
array $types optional: List or associative array of types to be used for casting values in query.

Returns

Cake\Database\StatementInterface

Executed statement

executeStatement() ¶ protected

executeStatement(Cake\Database\StatementInterface $statement, array|null $params = null): void

Execute the statement and log the query string.

Parameters

Cake\Database\StatementInterface $statement: Statement to execute.
array|null $params optional: List of values to be bound to query.

Returns

void

getLogger() ¶ public

getLogger(): Psr\Log\LoggerInterface|null

Get the logger instance.

Returns

Psr\Log\LoggerInterface|null

getMaxAliasLength() ¶ public

getMaxAliasLength(): int|null

Returns the maximum alias length allowed.

This can be different from the maximum identifier length for columns.

Returns

int|null

Maximum alias length or null if no limit

getPdo() ¶ protected

getPdo(): PDO

Get the PDO connection instance.

Returns

PDO

getResultSetDecorators() ¶ protected

getResultSetDecorators(Cake\Database\Query|string $query): array<Closure>

Returns the decorators to be applied to the result set incase of a SelectQuery.

Parameters

Cake\Database\Query|string $query: The query to be decorated.

Returns

array<Closure>

getRole() ¶ public

getRole(): string

Returns the connection role this driver performs.

Returns

string

inTransaction() ¶ public

inTransaction(): bool

Returns whether a transaction is active for connection.

Returns

bool

isAutoQuotingEnabled() ¶ public

isAutoQuotingEnabled(): bool

Returns whether this driver should automatically quote identifiers in queries.

Returns

bool

isConnected() ¶ public

isConnected(): bool

Checks whether the driver is connected.

Returns

bool

lastInsertId() ¶ public

lastInsertId(string|null $table = null): string

Returns last id generated for a table or sequence in database.

Parameters

string|null $table optional: table name or sequence to get last insert value from.

Returns

string

log() ¶ public

log(Stringable|string $message, array $context = []): bool

Logs a message or query using the configured logger object.

Parameters

Stringable|string $message: Message string or query.
array $context optional: Logging context.

Returns

bool

True if message was logged.

newCompiler() ¶ public

newCompiler(): Cake\Database\QueryCompiler

Returns

Cake\Database\QueryCompiler

newTableSchema() ¶ public

newTableSchema(string $table, array<string, mixed> $columns = []): Cake\Database\Schema\TableSchemaInterface

Constructs new TableSchema.

Parameters

string $table: The table name.
array<string, mixed> $columns optional: The list of columns for the schema.

Returns

Cake\Database\Schema\TableSchemaInterface

prepare() ¶ public

prepare(Cake\Database\Query|string $query): Cake\Database\StatementInterface

Prepares a sql statement to be executed.

Parameters

Cake\Database\Query|string $query: The query to turn into a prepared statement.

Returns

Cake\Database\StatementInterface

quote() ¶ public

quote(string $value): string

Quotes a database value.

This makes values safe for concatenation in SQL queries.

Using this method is not recommended. You should use execute() instead, as it uses prepared statements which are safer than string concatenation.

This method should only be used for queries that do not support placeholders.

Parameters

string $value: The value to quote.

Returns

string

quoteIdentifier() ¶ public

quoteIdentifier(string $identifier): string

Quotes a database identifier (a column name, table name, etc..) to be used safely in queries without the risk of using reserved words

Parameters

string $identifier: The identifier to quote.

Returns

string

quoter() ¶ public

quoter(): Cake\Database\IdentifierQuoter

Get identifier quoter instance.

Returns

Cake\Database\IdentifierQuoter

releaseSavePointSQL() ¶ public

releaseSavePointSQL(string|int $name): string

Returns a SQL snippet for releasing a previously created save point

Parameters

string|int $name: save point name

Returns

string

rollbackSavePointSQL() ¶ public

rollbackSavePointSQL(string|int $name): string

Returns a SQL snippet for rollbacking a previously created save point

Parameters

string|int $name: save point name

Returns

string

rollbackTransaction() ¶ public

rollbackTransaction(): bool

Rollbacks a transaction.

Returns

bool

True on success, false otherwise.

run() ¶ public

run(Cake\Database\Query $query): Cake\Database\StatementInterface

Executes the provided query after compiling it for the specific driver dialect and returns the executed Statement object.

Parameters

Cake\Database\Query $query: The query to be executed.

Returns

Cake\Database\StatementInterface

Executed statement

savePointSQL() ¶ public

savePointSQL(string|int $name): string

Returns a SQL snippet for creating a new transaction savepoint

Parameters

string|int $name: save point name

Returns

string

schema() ¶ public

schema(): string

Returns the schema name that's being used.

Returns

string

schemaDialect() ¶ abstract public

schemaDialect(): Cake\Database\Schema\SchemaDialect

Get the schema dialect.

Used by {@link \Cake\Database\Schema} package to reflect schema and generate schema.

If all the tables that use this Driver specify their own schemas, then this may return null.

Returns

Cake\Database\Schema\SchemaDialect

schemaValue() ¶ public

schemaValue(mixed $value): string

Escapes values for use in schema definitions.

Parameters

mixed $value: The value to escape.

Returns

string

String for use in schema definitions.

setLogger() ¶ public

setLogger(LoggerInterface $logger): void

Sets a logger.

Parameters

LoggerInterface $logger

Returns

void

supports() ¶ abstract public

supports(Cake\Database\DriverFeatureEnum $feature): bool

Returns whether the driver supports the feature.

Should return false for unknown features.

Parameters

Cake\Database\DriverFeatureEnum $feature: Driver feature

Returns

bool

transformQuery() ¶ protected

transformQuery(Cake\Database\Query $query): Cake\Database\Query

Transform the query to accommodate any specificities of the SQL dialect in use.

It will also quote the identifiers if auto quoting is enabled.

Parameters

Cake\Database\Query $query: Query to transform.

Returns

Cake\Database\Query

version() ¶ public

version(): string

Returns connected server version.

Returns

string

Property Detail

`$_autoQuoting` ¶ protected

Indicates whether the driver is doing automatic identifier quoting for all queries

Type

bool

`$_baseConfig` ¶ protected

Base configuration that is merged into the user supplied configuration data.

Type

array<string, mixed>

`$_config` ¶ protected

Configuration data.

Type

array<string, mixed>

`$_endQuote` ¶ protected

String used to end a database identifier quoting to make it safe

Type

string

`$_schemaDialect` ¶ protected

The schema dialect for this driver

Type

Cake\Database\Schema\SchemaDialect

`$_startQuote` ¶ protected

String used to start a database identifier quoting to make it safe

Type

string

`$_version` ¶ protected

The server version

Type

string|null

`$connectRetries` ¶ protected

The last number of connection retry attempts.

Type

int

`$logQueries` ¶ protected

Whether to log queries generated during this connection.

Type

bool

`$logger` ¶ protected

The logger instance.

Type

?LoggerInterface

`$pdo` ¶ protected

Instance of PDO.

Type

PDO|null

`$quoter` ¶ protected

Identifier quoter

Type

Cake\Database\IdentifierQuoter|null

Namespaces

Class Driver

Constants

Property Summary

Method Summary

__construct() public

__debugInfo() public

__destruct() public

_deleteQueryTranslator() protected

_expressionTranslators() protected

_insertQueryTranslator() protected

_removeAliasesFromConditions() protected

_selectQueryTranslator() protected

_transformDistinct() protected

_updateQueryTranslator() protected

beginTransaction() public

commitTransaction() public

compileQuery() public

config() public

connect() abstract public

createLogger() protected

createPdo() protected

createQueryException() protected

disableAutoQuoting() public

disableForeignKeySQL() abstract public

disableQueryLogging() public

disconnect() public

enableAutoQuoting() public

enableForeignKeySQL() abstract public

enableQueryLogging() public

enabled() abstract public

exec() public

execute() public

executeStatement() protected

getLogger() public

getMaxAliasLength() public

getPdo() protected

getResultSetDecorators() protected

getRole() public

inTransaction() public

isAutoQuotingEnabled() public

isConnected() public

lastInsertId() public

log() public

newCompiler() public

newTableSchema() public

prepare() public

quote() public

quoteIdentifier() public

quoter() public

releaseSavePointSQL() public

rollbackSavePointSQL() public

rollbackTransaction() public

run() public

savePointSQL() public

schema() public

schemaDialect() abstract public

schemaValue() public

setLogger() public

supports() abstract public

transformQuery() protected

version() public

Method Detail

__construct() ¶ public

Parameters

Throws

__debugInfo() ¶ public

Returns

__destruct() ¶ public

_deleteQueryTranslator() ¶ protected

Parameters

Returns

_expressionTranslators() ¶ protected

Returns

_insertQueryTranslator() ¶ protected

Parameters

Returns

_removeAliasesFromConditions() ¶ protected

Templates

Parameters