Connection

Type

Class

Namespace

craft\db

Inherits

craft\db\Connection » yii\db\Connection » yii\base\Component » yii\base\BaseObject

Implements

yii\base\Configurable

Uses traits

craft\db\PrimaryReplicaTrait

Since

3.0.0

View source

Public Properties

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

backupFilePath

Type

string

Default value

null

Access

Read-only

Since

3.0.38

View source

driverLabel

Type

string

Default value

null

Access

Read-only

Since

3.8.1

View source

foreignKeyName

Type

string

Default value

null

Access

Read-only

View source

ignoredBackupTables

Type

string[]

Default value

null

Access

Read-only

View source

indexName

Type

string

Default value

null

Access

Read-only

View source

isMysql

Type

boolean

Default value

null

Access

Read-only

View source

isPgsql

Type

boolean

Default value

null

Access

Read-only

View source

primaryKeyName

Type

string

Default value

null

Access

Read-only

View source

queryBuilder

Type

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

Default value

null

The query builder for the current DB connection.

View source

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

supportsMb4

Type

boolean

Default value

null

Whether the database supports 4+ byte characters.

View source

version

Type

string

Default value

null

Access

Read-only

View source

Public Methods

Method	Description
__call()	Calls the named method which is not a class method.
__clone()	Reset the connection after cloning.
__construct()	Constructor.
__get()	Returns the value of a component property.
__isset()	Checks if a property is set, i.e. defined and not null.
__set()	Sets the value of a component property.
__sleep()	Close the connection before serializing.
__unset()	Sets a component property to be null.
attachBehavior()	Attaches a behavior to this component.
attachBehaviors()	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()	Starts a transaction.
behaviors()	Returns a list of behaviors that this component should behave as.
cache()	Uses query cache for the queries performed with the callable.
canGetProperty()	Returns a value indicating whether a property can be read.
canSetProperty()	Returns a value indicating whether a property can be set.
className()	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()	Detaches a behavior from the component.
detachBehaviors()	Detaches all behaviors from the component.
ensureBehaviors()	Makes sure that the behaviors declared in behaviors() are attached to this component.
getBackupFilePath()	Returns the path for a new backup file.
getBehavior()	Returns the named behavior object.
getBehaviors()	Returns all behaviors attached to this component.
getDriverLabel()	Returns the human-facing driver label (MySQL, MariaDB, or PostgreSQL).
getDriverName()	Returns the name of the DB driver. Based on the the current dsn, 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()	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()	Returns the ID of the last inserted row or sequence value.
getMaster()	Returns the currently active master connection.
getMasterPdo()	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()	Returns a server version as a string comparable by \version_compare().
getSlave()	Returns the currently active slave connection.
getSlavePdo()	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()	Returns the currently active transaction.
getVersion()	Returns the version of the DB.
hasEventHandlers()	Returns a value indicating whether there is any handler attached to the named event.
hasMethod()	Returns a value indicating whether a method is defined.
hasProperty()	Returns a value indicating whether a property is defined for this component.
init()	Initializes the object.
noCache()	Disables query cache temporarily.
off()	Detaches an existing event handler from this component.
on()	Attaches an event handler to an event.
open()	Establishes a DB connection.
quoteColumnName()	Quotes a column name for use in a query.
quoteDatabaseName()
quoteSql()	Processes a SQL statement by quoting table and column names that are enclosed within double brackets.
quoteTableName()	Quotes a table name for use in a query.
quoteValue()	Quotes a string value for use in a query.
restore()	Restores a database at the given file path.
setDriverName()	Changes the current driver name.
setQueryBuilder()	Can be used to set yii\db\QueryBuilder configuration via Connection configuration array.
setSupportsMb4()	Sets whether the database supports 4+ byte characters.
tableExists()	Returns whether a table exists.
transaction()	Executes callback provided in a transaction.
trigger()	Triggers an event.
trimObjectName()	Ensures that an object name is within the schema's limit.
useMaster()	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

Returns

string – The file path to the database backup

Throws

• yii\base\Exception
  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

Arguments

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

Throws

• yii\base\Exception
  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

columnExists()

Checks if a column exists in a table.

View source

Arguments

• $table (string)
• $column (string)
• $refresh (boolean, null)

Returns

boolean

Throws

• yii\base\NotSupportedException
  if there is no support for the current driver type

createCommand()

Creates a command for execution.

View source

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

Arguments

• $config (craft\config\DbConfig)

Returns

static

getBackupFilePath()

Since

3.0.38

Returns the path for a new backup file.

View source

Returns

string

getDriverLabel()

Since

3.8.1

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

View source

Returns

string

getForeignKeyName()

Generates a foreign key name.

View source

Returns

string

getIgnoredBackupTables()

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

View source

Returns

string[]

getIndexName()

Generates an index name.

View source

Returns

string

getIsMysql()

Returns whether this is a MySQL connection.

View source

Returns

boolean

getIsPgsql()

Returns whether this is a PostgreSQL connection.

View source

Returns

boolean

getPrimaryKeyName()

Generates a primary key name.

View source

Returns

string

getQueryBuilder()

Returns the query builder for the current DB connection.

View source

Returns

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

getSchema()

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

View source

Returns

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

getSupportsMb4()

Returns whether the database supports 4+ byte characters.

View source

Returns

boolean

getTableSchema()

Obtains the schema information for the named table.

View source

Arguments

• $name
• $refresh

Returns

craft\db\TableSchema, null –

getVersion()

DEPRECATED

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

Returns the version of the DB.

View source

Returns

string

open()

Establishes a DB connection.

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

View source

Throws

• craft\errors\DbConnectException
  if there are any issues
• Throwable

quoteDatabaseName()

View source

Arguments

• $name (string)

Returns

string

restore()

Restores a database at the given file path.

View source

Arguments

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

Throws

• yii\base\Exception
  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

Arguments

• $supportsMb4 (boolean)

tableExists()

Returns whether a table exists.

View source

Arguments

• $table (string)
• $refresh (boolean, null)

Returns

boolean

trimObjectName()

DEPRECATED

Deprecated in 3.6.0

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

View source

Arguments

• $name (string)

Returns

string

Protected Methods

Method	Description
createPdoInstance()	Creates the PDO instance.
initConnection()	Initializes the DB connection.
openFromPool()	Opens the connection to a server in the pool.
openFromPoolSequentially()	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.

---