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) – 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.
driverName (opens new window) string (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) – 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)
enableSavepoint (opens new window) boolean (opens new window) – Whether to enable [savepoint](http://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.
ignoredBackupTables 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) – 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) – The password for establishing DB connection.
pdo (opens new window) PDO (opens new window) – The PHP PDO instance associated with this DB connection.
pdoClass (opens new window) string (opens new window) – Custom PDO wrapper class.
primaries array (opens new window)
primary craft\db\Connection, null (opens new window) – The currently active primary connection.
primaryConfig array (opens new window)
primaryPdo PDO (opens new window) – The PDO instance for the currently active primary connection.
queryBuilder (opens new window) yii\db\QueryBuilder (opens new window) – 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, null (opens new window) – The currently active replica connection.
replicaConfig array (opens new window)
replicaPdo PDO (opens new window), null (opens new window) – The PDO instance for the currently active replica connection.
replicas array (opens new window)
schema (opens new window) yii\db\Schema (opens new window) – 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)
slave (opens new window) yii\db\Connection (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) – 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)
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) – 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)

# ignoredBackupTables

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)

# supportsMb4

Type
boolean (opens new window)
Default value
null

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 an object property.
__isset() (opens new window) Checks if a property is set, i.e. defined and not null.
__set() (opens new window) Sets value of an object property.
__sleep() (opens new window) Close the connection before serializing.
__unset() (opens new window) Sets an object property to 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() (opens new window) 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.
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() Returns a foreign key name based on the table and column names.
getIgnoredBackupTables() Returns the core table names whose data should be excluded from database backups.
getIndexName() Returns an index name based on the table, column names, and whether it should be unique.
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() Returns a primary key name based on the table and column names.
getPrimaryPdo() Returns the PDO instance for the currently active primary connection.
getQueryBuilder() (opens new window) 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() (opens new window) 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() (opens new window) 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.
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

# 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

Throws

# 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

Returns

boolean (opens new window)

Throws

# 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

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)

# getForeignKeyName()

Returns a foreign key name based on the table and column names.

View source (opens new window)

Arguments

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

Returns an index name based on the table, column names, and whether it should be unique.

View source (opens new window)

Arguments

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

Returns a primary key name based on the table and column names.

View source (opens new window)

Arguments

Returns

string (opens new window)

# getSupportsMb4()

Returns whether the database supports 4+ byte characters.

View source (opens new window)

Returns

boolean (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

# quoteDatabaseName()

View source (opens new window)

Arguments

Returns

string (opens new window)

# restore()

Restores a database at the given file path.

View source (opens new window)

Arguments

Throws

# setSupportsMb4()

Sets whether the database supports 4+ byte characters.

View source (opens new window)

Arguments

# tableExists()

Returns whether a table exists.

View source (opens new window)

Arguments

Returns

boolean (opens new window)

# trimObjectName()

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

View source (opens new window)

Arguments

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.