Class Connection
Represents a connection with a database server.
Properties summary
-
$_config protected
array
Contains the configuration params for this connection.
-
$_driver protected
\Cake\Database\DriverInterface
Driver object, responsible for creating the real connection and provide specific SQL dialect.
-
$_logQueries protected
bool
Whether to log queries generated during this connection.
-
$_logger protected
\Psr\Log\LoggerInterface|null
Logger object instance.
-
$_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.
-
$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.
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
-
_newLogger() protected
Returns a new statement object that will log the activity for the passed original statement instance.
-
begin() public
Starts a new transaction.
-
cacheMetadata() public
Enables or disables metadata caching for this connection
-
cast() public
Converts a give value to a suitable database value based on type and return relevant internal statement type
-
commit() public
Commits current transaction.
-
compileQuery() public
Compiles a Query object into a SQL string according to the dialect for this connection's driver
-
config() public
Get the configuration data used to create the connection.
-
configName() public
Get the configuration name for this connection.
-
connect() public
Connects to the configured database.
-
createSavePoint() public
Creates a new save point for nested transactions.
-
delete() public
Executes a DELETE statement on the specified table.
-
disableConstraints() public
Run an operation with constraints disabled.
-
disableForeignKeys() public
Run driver specific SQL to disable foreign key checks.
-
disableQueryLogging() public
Disable query logging
-
disableSavePoints() public
Disables the usage of savepoints.
-
disconnect() public
Disconnects from database server.
-
enableForeignKeys() public
Run driver specific SQL to enable foreign key checks.
-
enableQueryLogging() public
Enable/disable query logging
-
enableSavePoints() public
Enables/disables the usage of savepoints, enables only if driver the 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 driver instance.
-
getLogger() public
Gets the logger object
-
getSchemaCollection() public
Gets a Schema\Collection object for this connection.
-
inTransaction() public
Checks if a transaction is running.
-
insert() public
Executes an INSERT query on the specified table.
-
isConnected() public
Returns whether connection to database server was already established.
-
isQueryLoggingEnabled() public
Check if query logging is enabled.
-
isSavePointsEnabled() public
Returns whether this connection is using savepoints for nested transactions
-
log() public
Logs a Query string using the configured logger object.
-
matchTypes() public
Matches columns to corresponding types
-
newQuery() public
Create a new Query instance for this connection.
-
prepare() public
Prepares a SQL statement to be executed.
-
query() public
Executes a SQL statement and returns the Statement object as result.
-
quote() public
Quotes value to be used safely in database query.
-
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.
-
releaseSavePoint() public
Releases a save point by its name.
-
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.
-
setCacher() public
Set a cacher.
-
setDriver() public
Sets the driver instance. If a string is passed it will be treated as a class name and will be instantiated.
-
setLogger() public
Sets a logger
-
setSchemaCollection() public
Sets a Schema\Collection object for this connection.
-
supportsDynamicConstraints() public
Returns whether the driver supports adding or dropping constraints to already created tables.
-
supportsQuoting() public
Checks if the driver supports quoting.
-
transactional() public
Executes a callable function inside a transaction, if any exception occurs while executing the passed callable, the transaction will be rolled back If the result of the callable function 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.
-
wasNestedTransactionRolledback() protected
Returns whether some nested transaction has been already rolled back.
Method Detail
__construct() public ¶
__construct(array $config)
Constructor.
Available options:
driver
Sort name or FCQN 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
$config Configuration array.
__debugInfo() public ¶
__debugInfo()
Returns an array that can be used to describe the internal state of this object.
Returns
array
_newLogger() protected ¶
_newLogger(\Cake\Database\StatementInterface $statement)
Returns a new statement object that will log the activity for the passed original statement instance.
Parameters
-
\Cake\Database\StatementInterface
$statement the instance to be decorated
Returns
\Cake\Database\Log\LoggingStatement
cacheMetadata() public ¶
cacheMetadata(mixed $cache)
Enables or disables metadata caching for this connection
Changing this setting will not modify existing schema collections objects.
Parameters
-
bool|string
$cache Either boolean false to disable metadata caching, or true to use
_cake_model_
or the name of the cache config to use.
cast() public ¶
cast(mixed $value, mixed $type)
Converts a give value to a suitable database value based on type and return relevant internal statement type
Parameters
-
mixed
$value The value to cast
-
\Cake\Database\TypeInterface|string|int
$type optional The type name or type instance to use.
Returns
array
list containing converted value and internal type
commit() public ¶
commit()
Commits current transaction.
Returns
bool
true on success, false otherwise
compileQuery() public ¶
compileQuery(\Cake\Database\Query $query, \Cake\Database\ValueBinder $generator)
Compiles a Query object into a SQL string according to the dialect for this connection's driver
Parameters
-
\Cake\Database\Query
$query The query to be compiled
-
\Cake\Database\ValueBinder
$generator The placeholder generator to use
Returns
string
connect() public ¶
connect()
Connects to the configured database.
Returns
bool
true, if the connection was already established or the attempt was successful.
Throws
Cake\Database\Exception\MissingConnectionException
If database connection could not be established.
createSavePoint() public ¶
createSavePoint(mixed $name)
Creates a new save point for nested transactions.
Parameters
-
string|int
$name The save point name.
delete() public ¶
delete(string $table, array $conditions, array $types)
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
$types optional list of associative array containing the types to be used for casting
Returns
\Cake\Database\StatementInterface
disableConstraints() public ¶
disableConstraints(callable $operation)
Run an operation with constraints disabled.
Constraints should be re-enabled after the callback succeeds/fails.
Example:
$connection->disableConstraints(function ($connection) {
$connection->newQuery()->delete('users')->execute();
});
Parameters
-
callable
$operation 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.
disableForeignKeys() public ¶
disableForeignKeys()
Run driver specific SQL to disable foreign key checks.
enableForeignKeys() public ¶
enableForeignKeys()
Run driver specific SQL to enable foreign key checks.
enableQueryLogging() public ¶
enableQueryLogging(bool $value)
Enable/disable query logging
Parameters
-
bool
$value optional Enable/disable query logging
Returns
$this
enableSavePoints() public ¶
enableSavePoints(bool $enable)
Enables/disables the usage of savepoints, enables only if driver the allows it.
If you are trying to enable this feature, make sure you check the return value of this function to verify it was enabled successfully.
Example:
$connection->enableSavePoints(true)
Returns true if drivers supports save points, false otherwise
$connection->enableSavePoints(false)
Disables usage of savepoints and returns false
Parameters
-
bool
$enable optional Whether or not save points should be used.
Returns
$this
execute() public ¶
execute(string $query, array $params, array $types)
Executes a query using $params for interpolating values and $types as a hint for each those params.
Parameters
-
string
$query SQL to be executed and interpolated with $params
-
array
$params optional list or associative array of params to be interpolated in $query 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()
Get a cacher.
Returns
\Psr\SimpleCache\CacheInterface
$cacher Cacher object
getDisconnectRetry() public ¶
getDisconnectRetry()
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
getLogger() public ¶
getLogger()
Gets the logger object
Returns
\Psr\Log\LoggerInterface
logger instance
getSchemaCollection() public ¶
getSchemaCollection()
Gets a Schema\Collection object for this connection.
Returns
\Cake\Database\Schema\CollectionInterface
inTransaction() public ¶
inTransaction()
Checks if a transaction is running.
Returns
bool
True if a transaction is running else false.
insert() public ¶
insert(string $table, array $data, array $types)
Executes an INSERT query on the specified table.
Parameters
-
string
$table the table to insert values in
-
array
$data values to be inserted
-
array
$types optional list of associative array containing the types to be used for casting
Returns
\Cake\Database\StatementInterface
isConnected() public ¶
isConnected()
Returns whether connection to database server was already established.
Returns
bool
isQueryLoggingEnabled() public ¶
isQueryLoggingEnabled()
Check if query logging is enabled.
Returns
bool
isSavePointsEnabled() public ¶
isSavePointsEnabled()
Returns whether this connection is using savepoints for nested transactions
Returns
bool
true if enabled, false otherwise
log() public ¶
log(string $sql)
Logs a Query string using the configured logger object.
Parameters
-
string
$sql string to be logged
matchTypes() public ¶
matchTypes(array $columns, array $types)
Matches columns to corresponding types
Both $columns and $types should either be numeric based or string key based at the same time.
Parameters
-
array
$columns list or associative array of columns and parameters to be bound with types
-
array
$types list or associative array of types
Returns
array
newQuery() public ¶
newQuery()
Create a new Query instance for this connection.
Returns
\Cake\Database\Query
prepare() public ¶
prepare(mixed $sql)
Prepares a SQL statement to be executed.
Parameters
-
string|\Cake\Database\Query
$sql The SQL to convert into a prepared statement.
Returns
\Cake\Database\StatementInterface
query() public ¶
query(string $sql)
Executes a SQL statement and returns the Statement object as result.
Parameters
-
string
$sql The SQL query to execute.
Returns
\Cake\Database\StatementInterface
quote() public ¶
quote(mixed $value, mixed $type)
Quotes value to be used safely in database query.
Parameters
-
mixed
$value The value to quote.
-
string|int|\Cake\Database\TypeInterface
$type optional Type to be used for determining kind of quoting to perform
Returns
string
Quoted value
quoteIdentifier() public ¶
quoteIdentifier(string $identifier)
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
releaseSavePoint() public ¶
releaseSavePoint(mixed $name)
Releases a save point by its name.
Parameters
-
string|int
$name The save point name.
rollback() public ¶
rollback(?bool $toBeginning)
Rollback current transaction.
Parameters
-
bool|null
$toBeginning optional Whether or not 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(mixed $name)
Rollback a save point by its name.
Parameters
-
string|int
$name The save point name.
run() public ¶
run(\Cake\Database\Query $query)
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
setCacher() public ¶
setCacher(\Psr\SimpleCache\CacheInterface $cacher)
Set a cacher.
Parameters
-
\Psr\SimpleCache\CacheInterface
$cacher Cacher object
Returns
$this
setDriver() public ¶
setDriver(mixed $driver, mixed $config)
Sets the driver instance. If a string is passed it will be treated as a class name and will be instantiated.
Parameters
-
\Cake\Database\DriverInterface|string
$driver The driver instance to use.
-
array
$config optional Config for a new driver.
Returns
$this
Throws
Cake\Database\Exception\MissingDriverException
When a driver class is missing.
Cake\Database\Exception\MissingExtensionException
When a driver's PHP extension is missing.
setLogger() public ¶
setLogger(\Psr\Log\LoggerInterface $logger)
Sets a logger
Parameters
-
\Psr\Log\LoggerInterface
$logger Logger object
Returns
$this
setSchemaCollection() public ¶
setSchemaCollection(\Cake\Database\Schema\CollectionInterface $collection)
Sets a Schema\Collection object for this connection.
Parameters
-
\Cake\Database\Schema\CollectionInterface
$collection The schema collection object
Returns
$this
supportsDynamicConstraints() public ¶
supportsDynamicConstraints()
Returns whether the driver supports adding or dropping constraints to already created tables.
Returns
bool
true if driver supports dynamic constraints
transactional() public ¶
transactional(callable $transaction)
Executes a callable function inside a transaction, if any exception occurs
while executing the passed callable, the transaction will be rolled back
If the result of the callable function 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->newQuery()->delete('users')->execute();
});
Parameters
-
callable
$transaction 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 $data, array $conditions, array $types)
Executes an UPDATE statement on the specified table.
Parameters
-
string
$table the table to update rows from
-
array
$data values to be updated
-
array
$conditions optional conditions to be set for update statement
-
array
$types optional list of associative array containing the types to be used for casting
Returns
\Cake\Database\StatementInterface
wasNestedTransactionRolledback() protected ¶
wasNestedTransactionRolledback()
Returns whether some nested transaction has been already rolled back.
Returns
bool
Property Detail
$_driver ¶ protected
Driver object, responsible for creating the real connection and provide specific SQL dialect.
Type
\Cake\Database\DriverInterface
$_schemaCollection ¶ protected
The schema collection object
Type
\Cake\Database\Schema\CollectionInterface|null
$_useSavePoints ¶ protected
Whether this connection can and should use savepoints for nested transactions.
Type
bool
$nestedTransactionRollbackException ¶ protected
NestedTransactionRollbackException object instance, will be stored if the rollback method is called in some nested transaction.
Type
\Cake\Database\Exception\NestedTransactionRollbackException|null