Class Connection

Represents a connection with a database server.

Events

Connection.afterCommit Fired after the outermost transaction commits. Listeners receive the connection as the event subject. Not fired on rollback or for nested commits.

Namespace: Cake\Database

Constants

string

ROLE_READ ¶
```
'read'
```
string

ROLE_WRITE ¶
```
'write'
```

Property Summary

$_config protected

array<string, mixed>

Contains the configuration params for this connection.
$_eventClass protected

string

Default class name for new event objects.
$_eventManager protected

Cake\Event\EventManagerInterface

Instance of the Cake\Event\EventManager this object is using to dispatch inner events.
$_schemaCollection protected

Cake\Database\Schema\CollectionInterface|null

The schema collection object
$_transactionLevel protected

int

Contains how many nested transactions have been started.
$_transactionStarted protected

bool

Whether a transaction is active in this connection.
$_useSavePoints protected

bool

Whether this connection can and should use savepoints for nested transactions.
$afterCommitCallbacks protected

array<Closure>

Callbacks to execute after the outermost transaction commits.
$cacher protected

Psr\SimpleCache\CacheInterface|null

Cacher object instance.
$nestedTransactionRollbackException protected

Cake\Database\Exception\NestedTransactionRollbackException|null

NestedTransactionRollbackException object instance, will be stored if the rollback method is called in some nested transaction.
$queryFactory protected

QueryFactory
$readDriver protected

Cake\Database\Driver
$writeDriver protected

Cake\Database\Driver

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
afterCommit() public

Register a callback to run after the outermost transaction commits.
begin() public

Starts a new transaction.
cacheMetadata() public

Enables or disables metadata caching for this connection
commit() public

Commits current transaction.
config() public

Get the configuration data used to create the connection.
configName() public

Get the configuration name for this connection.
createDrivers() protected

Creates read and write drivers.
createSavePoint() public

Creates a new save point for nested transactions.
delete() public

Executes a DELETE statement on the specified table.
deleteQuery() public

Create a new DeleteQuery instance for this connection.
disableConstraints() public

Run an operation with constraints disabled.
disableForeignKeys() public

Run driver specific SQL to disable foreign key checks.
disableSavePoints() public

Disables the usage of savepoints.
dispatchEvent() public

Wrapper for creating and dispatching events.
enableForeignKeys() public

Run driver specific SQL to enable foreign key checks.
enableSavePoints() public

Enables/disables the usage of savepoints, enables only if the driver allows it.
execute() public

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

Get a cacher.
getDisconnectRetry() public

Get the retry wrapper object that is allows recovery from server disconnects while performing certain database actions, such as executing a query.
getDriver() public

Gets the role-specific driver instance.
getEventManager() public

Returns the Cake\Event\EventManager manager instance for this object.
getReadDriver() public

Gets the read-role driver instance.
getSchemaCollection() public

Gets a Schema\Collection object for this connection.
getWriteDriver() public

Gets the write-role driver instance.
inTransaction() public

Checks if a transaction is running.
insert() public

Executes an INSERT query on the specified table.
insertQuery() public

Create a new InsertQuery instance for this connection.
isSavePointsEnabled() public

Returns whether this connection is using savepoints for nested transactions
queryFactory() public

Get query factory instance.
releaseSavePoint() public

Releases a save point by its name.
role() public

Returns the connection role: read or write.
rollback() public

Rollback current transaction.
rollbackSavepoint() public

Rollback a save point by its name.
run() public

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

Create a new SelectQuery instance for this connection.
setCacher() public

Set a cacher.
setEventManager() public

Returns the Cake\Event\EventManagerInterface instance for this object.
setSchemaCollection() public

Sets a Schema\Collection object for this connection.
transactional() public

Executes a callback inside a transaction, if any exception occurs while executing the passed callback, the transaction will be rolled back If the result of the callback is false, the transaction will also be rolled back. Otherwise the transaction is committed after executing the callback.
update() public

Executes an UPDATE statement on the specified table.
updateQuery() public

Create a new UpdateQuery instance for this connection.
wasNestedTransactionRolledback() protected

Returns whether some nested transaction has been already rolled back.

Method Detail

__construct() ¶ public

__construct(array<string, mixed> $config)

Constructor.

Available options:

driver Sort name or FQCN for driver.
log Boolean indicating whether to use query logging.
name Connection name.
cacheMetaData Boolean indicating whether metadata (datasource schemas) should be cached. If set to a string it will be used as the name of cache config to use.
cacheKeyPrefix Custom prefix to use when generation cache keys. Defaults to connection name.

Parameters

array<string, mixed> $config: Configuration array.

Throws

Cake\Database\Exception\MissingDriverException
when the driver class cannot be found
Cake\Database\Exception\MissingExtensionException
when the database extension is not enabled

__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

Disconnects the driver to release the connection.

afterCommit() ¶ public

afterCommit(Closure $callback): void

If no transaction is active, the callback executes immediately. Callbacks are discarded on rollback.

Parameters

Closure $callback: Callback to execute after commit.

Returns

void

begin() ¶ public

begin(): void

Starts a new transaction.

Returns

void

cacheMetadata() ¶ public

cacheMetadata(string|bool $cache): void

Enables or disables metadata caching for this connection

Changing this setting will not modify existing schema collections objects.

Parameters

string|bool $cache: Either boolean false to disable metadata caching, or true to use _cake_model_ or the name of the cache config to use.

Returns

void

commit() ¶ public

commit(): bool

Commits current transaction.

Returns

bool

true on success, false otherwise

Throws

Cake\Database\Exception\NestedTransactionRollbackException
when a nested transaction was rolled back

config() ¶ public

config(): array<string, mixed>

Get the configuration data used to create the connection.

Returns

array<string, mixed>

configName() ¶ public

configName(): string

Get the configuration name for this connection.

Returns

string

createDrivers() ¶ protected

createDrivers(array<string, mixed> $config): array

Creates read and write drivers.

Parameters

array<string, mixed> $config: Connection config

Returns

array

createSavePoint() ¶ public

createSavePoint(string|int $name): void

Creates a new save point for nested transactions.

Parameters

string|int $name: Save point name or id

Returns

void

delete() ¶ public

delete(string $table, array $conditions = [], array<string, string> $types = []): Cake\Database\StatementInterface

Executes a DELETE statement on the specified table.

Parameters

string $table: the table to delete rows from
array $conditions optional: conditions to be set for delete statement
array<string, string> $types optional: list of associative array containing the types to be used for casting

Returns

Cake\Database\StatementInterface

deleteQuery() ¶ public

deleteQuery(string|null $table = null, array $conditions = [], array<string, string> $types = []): Cake\Database\Query\DeleteQuery

Create a new DeleteQuery instance for this connection.

Parameters

string|null $table optional: The table to delete rows from.
array $conditions optional: Conditions to be set for the delete statement.
array<string, string> $types optional: Associative array containing the types to be used for casting.

Returns

Cake\Database\Query\DeleteQuery

disableConstraints() ¶ public

disableConstraints(Closure $callback): mixed

Run an operation with constraints disabled.

Constraints should be re-enabled after the callback succeeds/fails.

Example:

$connection->disableConstraints(function ($connection) {
  $connection->insertQuery('users')->execute();
});

Parameters

Closure $callback: Callback to run with constraints disabled

Returns

mixed

The return value of the callback.

Throws

Exception
Will re-throw any exception raised in $callback after rolling back the transaction.

disableForeignKeys() ¶ public

disableForeignKeys(): void

Run driver specific SQL to disable foreign key checks.

Returns

void

disableSavePoints() ¶ public

disableSavePoints(): $this

Disables the usage of savepoints.

Returns

$this

dispatchEvent() ¶ public

dispatchEvent(string $name, array $data = [], TSubject|null $subject = null): Cake\Event\EventInterface<TSubject>

Wrapper for creating and dispatching events.

Returns a dispatched event.

Templates


              TSubject
               of object               = $this

Parameters

string $name: Name of the event.
array $data optional: Any value you wish to be transported with this event to it can be read by listeners.
TSubject|null $subject optional: The object that this event applies to ($this by default).

Returns

Cake\Event\EventInterface<TSubject>

enableForeignKeys() ¶ public

enableForeignKeys(): void

Run driver specific SQL to enable foreign key checks.

Returns

void

enableSavePoints() ¶ public

enableSavePoints(bool $enable = true): $this

Enables/disables the usage of savepoints, enables only if the driver allows it.

If you are trying to enable this feature, make sure you check isSavePointsEnabled() to verify that savepoints were enabled successfully.

Parameters

bool $enable optional: Whether save points should be used.

Returns

$this

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

getCacher() ¶ public

getCacher(): Psr\SimpleCache\CacheInterface

Get a cacher.

Returns

Psr\SimpleCache\CacheInterface

getDisconnectRetry() ¶ public

getDisconnectRetry(): Cake\Core\Retry\CommandRetry

Get the retry wrapper object that is allows recovery from server disconnects while performing certain database actions, such as executing a query.

Returns

Cake\Core\Retry\CommandRetry

The retry wrapper

getDriver() ¶ public

getDriver(string $role = self::ROLE_WRITE): Cake\Database\Driver

Gets the role-specific driver instance.

Parameters

string $role optional: Connection role ('read' or 'write')

Returns

Cake\Database\Driver

getEventManager() ¶ public

getEventManager(): Cake\Event\EventManagerInterface

Returns the Cake\Event\EventManager manager instance for this object.

You can use this instance to register any new listeners or callbacks to the object events, or create your own events and trigger them at will.

Returns

Cake\Event\EventManagerInterface

getReadDriver() ¶ public

getReadDriver(): Cake\Database\Driver

Gets the read-role driver instance.

Returns

Cake\Database\Driver

getSchemaCollection() ¶ public

getSchemaCollection(): Cake\Database\Schema\CollectionInterface

Gets a Schema\Collection object for this connection.

Returns

Cake\Database\Schema\CollectionInterface

getWriteDriver() ¶ public

getWriteDriver(): Cake\Database\Driver

Gets the write-role driver instance.

Returns

Cake\Database\Driver

inTransaction() ¶ public

inTransaction(): bool

Checks if a transaction is running.

Returns

bool

True if a transaction is running else false.

insert() ¶ public

insert(string $table, array $values, array<string, string> $types = []): Cake\Database\StatementInterface

Executes an INSERT query on the specified table.

Parameters

string $table: the table to insert values in
array $values: values to be inserted
array<string, string> $types optional: Array containing the types to be used for casting

Returns

Cake\Database\StatementInterface

insertQuery() ¶ public

insertQuery(string|null $table = null, array $values = [], array<int|string, string> $types = []): Cake\Database\Query\InsertQuery

Create a new InsertQuery instance for this connection.

Parameters

string|null $table optional: The table to insert rows into.
array $values optional: Associative array of column => value to be inserted.
array<int|string, string> $types optional: Associative array containing the types to be used for casting.

Returns

Cake\Database\Query\InsertQuery

isSavePointsEnabled() ¶ public

isSavePointsEnabled(): bool

Returns whether this connection is using savepoints for nested transactions

Returns

bool

true if enabled, false otherwise

queryFactory() ¶ public

queryFactory(): Cake\Database\Query\QueryFactory

Get query factory instance.

Returns

Cake\Database\Query\QueryFactory

releaseSavePoint() ¶ public

releaseSavePoint(string|int $name): void

Releases a save point by its name.

Parameters

string|int $name: Save point name or id

Returns

void

role() ¶ public

role(): string

Returns the connection role: read or write.

Returns

string

rollback() ¶ public

rollback(bool|null $toBeginning = null): bool

Rollback current transaction.

Parameters

bool|null $toBeginning optional: Whether the transaction should be rolled back to the beginning of it. Defaults to false if using savepoints, or true if not.

Returns

bool

rollbackSavepoint() ¶ public

rollbackSavepoint(string|int $name): void

Rollback a save point by its name.

Parameters

string|int $name: Save point name or id

Returns

void

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

selectQuery() ¶ public

selectQuery(Cake\Database\ExpressionInterface|Closure|array|string|float|int $fields = [], array|string $table = [], array<string, string> $types = []): Cake\Database\Query\SelectQuery<mixed>

Create a new SelectQuery instance for this connection.

Parameters

Cake\Database\ExpressionInterface|Closure|array|string|float|int $fields optional: Fields/columns list for the query.
array|string $table optional: The table or list of tables to query.
array<string, string> $types optional: Associative array containing the types to be used for casting.

Returns

Cake\Database\Query\SelectQuery<mixed>

setCacher() ¶ public

setCacher(Psr\SimpleCache\CacheInterface $cacher): $this

Set a cacher.

Parameters

Psr\SimpleCache\CacheInterface $cacher

Returns

$this

setEventManager() ¶ public

setEventManager(Cake\Event\EventManagerInterface $eventManager): $this

Returns the Cake\Event\EventManagerInterface instance for this object.

You can use this instance to register any new listeners or callbacks to the object events, or create your own events and trigger them at will.

Parameters

Cake\Event\EventManagerInterface $eventManager: the eventManager to set

Returns

$this

setSchemaCollection() ¶ public

setSchemaCollection(Cake\Database\Schema\CollectionInterface $collection): $this

Sets a Schema\Collection object for this connection.

Parameters

Cake\Database\Schema\CollectionInterface $collection: The schema collection object

Returns

$this

transactional() ¶ public

transactional(Closure $callback): mixed

Executes a callback inside a transaction, if any exception occurs while executing the passed callback, the transaction will be rolled back If the result of the callback is false, the transaction will also be rolled back. Otherwise the transaction is committed after executing the callback.

The callback will receive the connection instance as its first argument.

Example:

$connection->transactional(function ($connection) {
  $connection->deleteQuery('users')->execute();
});

Parameters

Closure $callback: The callback to execute within a transaction.

Returns

mixed

The return value of the callback.

Throws

Exception
Will re-throw any exception raised in $callback after rolling back the transaction.

update() ¶ public

update(string $table, array $values, array $conditions = [], array<string, string> $types = []): Cake\Database\StatementInterface

Executes an UPDATE statement on the specified table.

Parameters

string $table: the table to update rows from
array $values: values to be updated
array $conditions optional: conditions to be set for update statement
array<string, string> $types optional: list of associative array containing the types to be used for casting

Returns

Cake\Database\StatementInterface

updateQuery() ¶ public

updateQuery(Cake\Database\ExpressionInterface|string|null $table = null, array $values = [], array $conditions = [], array<string, string> $types = []): Cake\Database\Query\UpdateQuery

Create a new UpdateQuery instance for this connection.

Parameters

Cake\Database\ExpressionInterface|string|null $table optional: The table to update rows of.
array $values optional: Values to be updated.
array $conditions optional: Conditions to be set for the update statement.
array<string, string> $types optional: Associative array containing the types to be used for casting.

Returns

Cake\Database\Query\UpdateQuery

wasNestedTransactionRolledback() ¶ protected

wasNestedTransactionRolledback(): bool

Returns whether some nested transaction has been already rolled back.

Returns

bool

Property Detail

`$_config` ¶ protected

Contains the configuration params for this connection.

Type

array<string, mixed>

`$_eventClass` ¶ protected

Default class name for new event objects.

Type

string

`$_eventManager` ¶ protected

Instance of the Cake\Event\EventManager this object is using to dispatch inner events.

Type

Cake\Event\EventManagerInterface

`$_schemaCollection` ¶ protected

The schema collection object

Type

Cake\Database\Schema\CollectionInterface|null

`$_transactionLevel` ¶ protected

Contains how many nested transactions have been started.

Type

int

`$_transactionStarted` ¶ protected

Whether a transaction is active in this connection.

Type

bool

`$_useSavePoints` ¶ protected

Whether this connection can and should use savepoints for nested transactions.

Type

bool

`$afterCommitCallbacks` ¶ protected

Callbacks to execute after the outermost transaction commits.

Type

array<Closure>

`$cacher` ¶ protected

Cacher object instance.

Type

Psr\SimpleCache\CacheInterface|null

`$nestedTransactionRollbackException` ¶ protected

NestedTransactionRollbackException object instance, will be stored if the rollback method is called in some nested transaction.

Type

Cake\Database\Exception\NestedTransactionRollbackException|null

`$queryFactory` ¶ protected

Type

QueryFactory

`$readDriver` ¶ protected

Type

Cake\Database\Driver

`$writeDriver` ¶ protected

Type

Cake\Database\Driver

Namespaces

Class Connection

Events

Constants

Property Summary

Method Summary

__construct() public

__debugInfo() public

__destruct() public

afterCommit() public

begin() public

cacheMetadata() public

commit() public

config() public

configName() public

createDrivers() protected

createSavePoint() public

delete() public

deleteQuery() public

disableConstraints() public

disableForeignKeys() public

disableSavePoints() public

dispatchEvent() public

enableForeignKeys() public

enableSavePoints() public

execute() public

getCacher() public

getDisconnectRetry() public

getDriver() public

getEventManager() public

getReadDriver() public

getSchemaCollection() public

getWriteDriver() public

inTransaction() public

insert() public

insertQuery() public

isSavePointsEnabled() public

queryFactory() public

releaseSavePoint() public

role() public

rollback() public

rollbackSavepoint() public

run() public

selectQuery() public

setCacher() public

setEventManager() public

setSchemaCollection() public

transactional() public

update() public

updateQuery() public

wasNestedTransactionRolledback() protected

Method Detail

__construct() ¶ public

Available options:

Parameters

Throws

__debugInfo() ¶ public

Returns

__destruct() ¶ public

afterCommit() ¶ public

Parameters

Returns

begin() ¶ public

Returns

cacheMetadata() ¶ public

Parameters

Returns

commit() ¶ public

Returns

Throws

config() ¶ public

Returns

configName() ¶ public

Returns

createDrivers() ¶ protected

Parameters

Returns

createSavePoint() ¶ public

Parameters

Returns