Connection

Type

Class

Namespace

craft\db

Inherits

craft\db\Connection » yii\db\Connection (opens new window) » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)

Implements

yii\base\Configurable (opens new window)

Uses traits

craft\db\PrimaryReplicaTrait

Since

3.0.0

View source (opens new window)

Public Properties

Property	Description
attributes (opens new window)	array (opens new window) – PDO attributes (name => value) that should be set when calling open() (opens new window) to establish a DB connection.
backupFilePath	string (opens new window)
behaviors (opens new window)	yii\base\Behavior (opens new window) – List of behaviors attached to this component.
charset (opens new window)	string (opens new window), null (opens new window) – The charset used for database connection.
commandClass (opens new window)	string (opens new window) – The class used to create new database yii\db\Command (opens new window) objects.
commandMap (opens new window)	array (opens new window) – Mapping between PDO driver names and yii\db\Command (opens new window) classes.
driverLabel	string (opens new window)
driverName (opens new window)	string (opens new window), null (opens new window) – Name of the DB driver.
dsn (opens new window)	string (opens new window) – The Data Source Name, or DSN, contains the information required to connect to the database.
emulatePrepare (opens new window)	boolean (opens new window), null (opens new window) – Whether to turn on prepare emulation.
enableLogging (opens new window)	boolean (opens new window) – Whether to enable logging of database queries.
enableProfiling (opens new window)	boolean (opens new window) – Whether to enable profiling of opening database connection and database queries.
enableQueryCache (opens new window)	boolean (opens new window) – Whether to enable query caching.
enableReplicas	boolean (opens new window) – whether to enable read/write splitting by using replicas to read data.
enableSavepoint (opens new window)	boolean (opens new window) – Whether to enable [savepoint](https://en.
enableSchemaCache (opens new window)	boolean (opens new window) – Whether to enable schema caching.
enableSlaves (opens new window)	boolean (opens new window) – Whether to enable read/write splitting by using slaves (opens new window) to read data.
foreignKeyName	string (opens new window)
ignoredBackupTables	string (opens new window)[]
indexName	string (opens new window)
isActive (opens new window)	boolean (opens new window) – Whether the DB connection is established.
isMysql	boolean (opens new window)
isPgsql	boolean (opens new window)
isSybase (opens new window)	boolean (opens new window) – If the database connected via pdo_dblib is SyBase.
lastInsertID (opens new window)	string (opens new window) – The row ID of the last row inserted, or the last value retrieved from the sequence object.
master (opens new window)	yii\db\Connection (opens new window), null (opens new window) – The currently active master connection.
masterConfig (opens new window)	array (opens new window) – The configuration that should be merged with every master configuration listed in masters (opens new window).
masterPdo (opens new window)	PDO (opens new window) – The PDO instance for the currently active master connection.
masters (opens new window)	array (opens new window) – List of master connection configurations.
password (opens new window)	string (opens new window), null (opens new window) – The password for establishing DB connection.
pdo (opens new window)	PDO (opens new window), null (opens new window) – The PHP PDO instance associated with this DB connection.
pdoClass (opens new window)	string (opens new window), null (opens new window) – Custom PDO wrapper class.
primaries	array (opens new window) – list of primary connection configurations.
primary	craft\db\Connection, null (opens new window) – The currently active primary connection.
primaryConfig	array (opens new window) – the configuration that should be merged with every primary configuration listed in primaries.
primaryKeyName	string (opens new window)
primaryPdo	PDO (opens new window) – The PDO instance for the currently active primary connection.
queryBuilder	craft\db\mysql\QueryBuilder, craft\db\pgsql\QueryBuilder – The query builder for the current DB connection.
queryCache (opens new window)	yii\caching\CacheInterface (opens new window), string (opens new window) – The cache object or the ID of the cache application component that is used for query caching.
queryCacheDuration (opens new window)	integer (opens new window) – The default number of seconds that query results can remain valid in cache.
replica	craft\db\Connection – The currently active replica connection.
replicaConfig	array (opens new window) – the configuration that should be merged with every replica configuration listed in replicas.
replicaPdo	PDO (opens new window) – The PDO instance for the currently active replica connection.
replicas	array (opens new window) – list of replica connection configurations.
schema	craft\db\mysql\Schema, craft\db\pgsql\Schema – The schema information for the database opened by this connection.
schemaCache (opens new window)	yii\caching\CacheInterface (opens new window), string (opens new window) – The cache object or the ID of the cache application component that is used to cache the table metadata.
schemaCacheDuration (opens new window)	integer (opens new window) – Number of seconds that table metadata can remain valid in cache.
schemaCacheExclude (opens new window)	array (opens new window) – List of tables whose metadata should NOT be cached.
schemaMap (opens new window)	array (opens new window) – Mapping between PDO driver names and yii\db\Schema (opens new window) classes.
serverRetryInterval (opens new window)	integer (opens new window) – The retry interval in seconds for dead servers listed in masters (opens new window) and slaves (opens new window).
serverStatusCache (opens new window)	yii\caching\CacheInterface (opens new window), string (opens new window), false (opens new window) – The cache object or the ID of the cache application component that is used to store the health status of the DB servers specified in masters (opens new window) and slaves (opens new window).
serverVersion (opens new window)	string (opens new window) – Server version as a string.
shuffleMasters (opens new window)	boolean (opens new window) – Whether to shuffle masters (opens new window) before getting one.
shufflePrimaries	boolean (opens new window) – whether to shuffle primaries before getting one.
slave (opens new window)	yii\db\Connection (opens new window), null (opens new window) – The currently active slave connection.
slaveConfig (opens new window)	array (opens new window) – The configuration that should be merged with every slave configuration listed in slaves (opens new window).
slavePdo (opens new window)	PDO (opens new window), null (opens new window) – The PDO instance for the currently active slave connection.
slaves (opens new window)	array (opens new window) – List of slave connection configurations.
supportsMb4	boolean (opens new window) – Whether the database supports 4+ byte characters.
tablePrefix (opens new window)	string (opens new window) – The common prefix or suffix for table names.
transaction (opens new window)	yii\db\Transaction (opens new window), null (opens new window) – The currently active transaction.
username (opens new window)	string (opens new window), null (opens new window) – The username for establishing DB connection.
version	string (opens new window)

backupFilePath

Type

string (opens new window)

Default value

null

Access

Read-only

Since

3.0.38

View source (opens new window)

driverLabel

Type

string (opens new window)

Default value

null

Access

Read-only

Since

3.8.1

View source (opens new window)

foreignKeyName

Type

string (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

ignoredBackupTables

Type

string (opens new window)[]

Default value

null

Access

Read-only

View source (opens new window)

indexName

Type

string (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

isMysql

Type

boolean (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

isPgsql

Type

boolean (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

primaryKeyName

Type

string (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

queryBuilder

Type

craft\db\mysql\QueryBuilder, craft\db\pgsql\QueryBuilder

Default value

null

The query builder for the current DB connection.

View source (opens new window)

schema

Type

craft\db\mysql\Schema, craft\db\pgsql\Schema

Default value

null

The schema information for the database opened by this connection.

View source (opens new window)

supportsMb4

Type

boolean (opens new window)

Default value

null

Whether the database supports 4+ byte characters.

View source (opens new window)

version

Type

string (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

Public Methods

Method	Description
__call() (opens new window)	Calls the named method which is not a class method.
__clone() (opens new window)	Reset the connection after cloning.
__construct() (opens new window)	Constructor.
__get() (opens new window)	Returns the value of a component property.
__isset() (opens new window)	Checks if a property is set, i.e. defined and not null.
__set() (opens new window)	Sets the value of a component property.
__sleep() (opens new window)	Close the connection before serializing.
__unset() (opens new window)	Sets a component property to be null.
attachBehavior() (opens new window)	Attaches a behavior to this component.
attachBehaviors() (opens new window)	Attaches a list of behaviors to the component.
backup()	Performs a backup operation. If a backupCommand config setting has been set, will execute it. If not, will execute the default database schema specific backup defined in getDefaultBackupCommand(), which uses pg_dump for PostgreSQL and mysqldump for MySQL.
backupTo()	Performs a backup operation. If a backupCommand config setting has been set, will execute it. If not, will execute the default database schema specific backup defined in getDefaultBackupCommand(), which uses pg_dump for PostgreSQL and mysqldump for MySQL.
beginTransaction() (opens new window)	Starts a transaction.
behaviors() (opens new window)	Returns a list of behaviors that this component should behave as.
cache() (opens new window)	Uses query cache for the queries performed with the callable.
canGetProperty() (opens new window)	Returns a value indicating whether a property can be read.
canSetProperty() (opens new window)	Returns a value indicating whether a property can be set.
className() (opens new window)	Returns the fully qualified name of this class.
close()	Closes the currently active DB connection.
columnExists()	Checks if a column exists in a table.
createCommand()	Creates a command for execution.
createFromConfig()	Creates a new Connection instance based off the given DbConfig object.
detachBehavior() (opens new window)	Detaches a behavior from the component.
detachBehaviors() (opens new window)	Detaches all behaviors from the component.
ensureBehaviors() (opens new window)	Makes sure that the behaviors declared in behaviors() (opens new window) are attached to this component.
getBackupFilePath()	Returns the path for a new backup file.
getBehavior() (opens new window)	Returns the named behavior object.
getBehaviors() (opens new window)	Returns all behaviors attached to this component.
getDriverLabel()	Returns the human-facing driver label (MySQL, MariaDB, or PostgreSQL).
getDriverName() (opens new window)	Returns the name of the DB driver. Based on the the current dsn (opens new window), in case it was not set explicitly by an end user.
getForeignKeyName()	Generates a foreign key name.
getIgnoredBackupTables()	Returns the core table names whose data should be excluded from database backups.
getIndexName()	Generates an index name.
getIsActive() (opens new window)	Returns a value indicating whether the DB connection is established.
getIsMysql()	Returns whether this is a MySQL connection.
getIsPgsql()	Returns whether this is a PostgreSQL connection.
getLastInsertID() (opens new window)	Returns the ID of the last inserted row or sequence value.
getMaster() (opens new window)	Returns the currently active master connection.
getMasterPdo() (opens new window)	Returns the PDO instance for the currently active master connection.
getPrimary()	Returns the currently active primary connection.
getPrimaryKeyName()	Generates a primary key name.
getPrimaryPdo()	Returns the PDO instance for the currently active primary connection.
getQueryBuilder()	Returns the query builder for the current DB connection.
getReplica()	Returns the currently active replica connection.
getReplicaPdo()	Returns the PDO instance for the currently active replica connection.
getSchema()	Returns the schema information for the database opened by this connection.
getServerVersion() (opens new window)	Returns a server version as a string comparable by \version_compare().
getSlave() (opens new window)	Returns the currently active slave connection.
getSlavePdo() (opens new window)	Returns the PDO instance for the currently active slave connection.
getSupportsMb4()	Returns whether the database supports 4+ byte characters.
getTableSchema()	Obtains the schema information for the named table.
getTransaction() (opens new window)	Returns the currently active transaction.
getVersion()	Returns the version of the DB.
hasEventHandlers() (opens new window)	Returns a value indicating whether there is any handler attached to the named event.
hasMethod() (opens new window)	Returns a value indicating whether a method is defined.
hasProperty() (opens new window)	Returns a value indicating whether a property is defined for this component.
init() (opens new window)	Initializes the object.
noCache() (opens new window)	Disables query cache temporarily.
off() (opens new window)	Detaches an existing event handler from this component.
on() (opens new window)	Attaches an event handler to an event.
open()	Establishes a DB connection.
quoteColumnName() (opens new window)	Quotes a column name for use in a query.
quoteDatabaseName()
quoteSql() (opens new window)	Processes a SQL statement by quoting table and column names that are enclosed within double brackets.
quoteTableName() (opens new window)	Quotes a table name for use in a query.
quoteValue() (opens new window)	Quotes a string value for use in a query.
restore()	Restores a database at the given file path.
setDriverName() (opens new window)	Changes the current driver name.
setQueryBuilder() (opens new window)	Can be used to set yii\db\QueryBuilder (opens new window) configuration via Connection configuration array.
setSupportsMb4()	Sets whether the database supports 4+ byte characters.
tableExists()	Returns whether a table exists.
transaction() (opens new window)	Executes callback provided in a transaction.
trigger() (opens new window)	Triggers an event.
trimObjectName()	Ensures that an object name is within the schema's limit.
useMaster() (opens new window)	Executes the provided callback by using the master connection.
usePrimary()	Executes the provided callback by using the primary connection.

backup()

Performs a backup operation. If a backupCommand config setting has been set, will execute it. If not, will execute the default database schema specific backup defined in getDefaultBackupCommand(), which uses pg_dump for PostgreSQL and mysqldump for MySQL.

View source (opens new window)

Returns

string (opens new window) – The file path to the database backup

Throws

• yii\base\Exception (opens new window)
  if the backupCommand config setting is false
• craft\errors\ShellCommandException
  in case of failure

backupTo()

Performs a backup operation. If a backupCommand config setting has been set, will execute it. If not, will execute the default database schema specific backup defined in getDefaultBackupCommand(), which uses pg_dump for PostgreSQL and mysqldump for MySQL.

View source (opens new window)

Arguments

• $filePath (string (opens new window)) – The file path the database backup should be saved at

Throws

• yii\base\Exception (opens new window)
  if the backupCommand config setting is false
• craft\errors\ShellCommandException
  in case of failure

close()

Since

3.4.11

Closes the currently active DB connection.

It does nothing if the connection is already closed.

View source (opens new window)

columnExists()

Checks if a column exists in a table.

View source (opens new window)

Arguments

• $table (string (opens new window))
• $column (string (opens new window))
• $refresh (boolean (opens new window), null (opens new window))

Returns

boolean (opens new window)

Throws

• yii\base\NotSupportedException (opens new window)
  if there is no support for the current driver type

createCommand()

Creates a command for execution.

View source (opens new window)

Arguments

• $sql
• $params

Returns

craft\db\Command –

createFromConfig()

DEPRECATED

Deprecated in 3.0.18. Use craft\helpers\App::dbConfig() instead.

Creates a new Connection instance based off the given DbConfig object.

View source (opens new window)

Arguments

• $config (craft\config\DbConfig)

Returns

static

getBackupFilePath()

Since

3.0.38

Returns the path for a new backup file.

View source (opens new window)

Returns

string (opens new window)

getDriverLabel()

Since

3.8.1

Returns the human-facing driver label (MySQL, MariaDB, or PostgreSQL).

View source (opens new window)

Returns

string (opens new window)

getForeignKeyName()

Generates a foreign key name.

View source (opens new window)

Returns

string (opens new window)

getIgnoredBackupTables()

Returns the core table names whose data should be excluded from database backups.

View source (opens new window)

Returns

string (opens new window)[]

getIndexName()

Generates an index name.

View source (opens new window)

Returns

string (opens new window)

getIsMysql()

Returns whether this is a MySQL connection.

View source (opens new window)

Returns

boolean (opens new window)

getIsPgsql()

Returns whether this is a PostgreSQL connection.

View source (opens new window)

Returns

boolean (opens new window)

getPrimaryKeyName()

Generates a primary key name.

View source (opens new window)

Returns

string (opens new window)

getQueryBuilder()

Returns the query builder for the current DB connection.

View source (opens new window)

Returns

craft\db\mysql\QueryBuilder, craft\db\pgsql\QueryBuilder –

getSchema()

Returns the schema information for the database opened by this connection.

View source (opens new window)

Returns

craft\db\mysql\Schema, craft\db\pgsql\Schema –

getSupportsMb4()

Returns whether the database supports 4+ byte characters.

View source (opens new window)

Returns

boolean (opens new window)

getTableSchema()

Obtains the schema information for the named table.

View source (opens new window)

Arguments

• $name
• $refresh

Returns

craft\db\TableSchema, null (opens new window) –

getVersion()

DEPRECATED

Deprecated in 3.4.21. Use yii\db\Schema::getServerVersion() (opens new window) instead.

Returns the version of the DB.

View source (opens new window)

Returns

string (opens new window)

open()

Establishes a DB connection.

It does nothing if a DB connection has already been established.

View source (opens new window)

Throws

• craft\errors\DbConnectException
  if there are any issues
• Throwable (opens new window)

quoteDatabaseName()

View source (opens new window)

Arguments

• $name (string (opens new window))

Returns

string (opens new window)

restore()

Restores a database at the given file path.

View source (opens new window)

Arguments

• $filePath (string (opens new window)) – The path of the database backup to restore.

Throws

• yii\base\Exception (opens new window)
  if the restoreCommand config setting is false
• craft\errors\ShellCommandException
  in case of failure

setSupportsMb4()

Sets whether the database supports 4+ byte characters.

View source (opens new window)

Arguments

• $supportsMb4 (boolean (opens new window))

tableExists()

Returns whether a table exists.

View source (opens new window)

Arguments

• $table (string (opens new window))
• $refresh (boolean (opens new window), null (opens new window))

Returns

boolean (opens new window)

trimObjectName()

DEPRECATED

Deprecated in 3.6.0

Ensures that an object name is within the schema's limit.

View source (opens new window)

Arguments

• $name (string (opens new window))

Returns

string (opens new window)

Protected Methods

Method	Description
createPdoInstance() (opens new window)	Creates the PDO instance.
initConnection() (opens new window)	Initializes the DB connection.
openFromPool() (opens new window)	Opens the connection to a server in the pool.
openFromPoolSequentially() (opens new window)	Opens the connection to a server in the pool.

Constants

Constant	Description
DRIVER_MYSQL
DRIVER_PGSQL

Events

EVENT_AFTER_CREATE_BACKUP

Type

craft\events\BackupEvent

The event that is triggered after the backup is created.

EVENT_AFTER_RESTORE_BACKUP

Type

craft\events\RestoreEvent

The event that is triggered after the restore occurred.

EVENT_BEFORE_CREATE_BACKUP

Type

craft\events\BackupEvent

The event that is triggered before the backup is created.

EVENT_BEFORE_RESTORE_BACKUP

Type

craft\events\RestoreEvent

The event that is triggered before the restore is started.