Craft 3 Class Reference

Appearance

PrimaryReplicaTrait ​

Type
Trait
Namespace
craft\db
Implemented by
craft\db\Connection
Since
3.4.25

View source

Public Properties ​

PropertyDescription
enableReplicasboolean – whether to enable read/write splitting by using replicas to read data.
primariesarray – list of primary connection configurations.
primarycraft\db\Connection, null – The currently active primary connection.
primaryConfigarray – the configuration that should be merged with every primary configuration listed in primaries.
primaryPdoPDO – The PDO instance for the currently active primary connection.
replicacraft\db\Connection – The currently active replica connection.
replicaConfigarray – the configuration that should be merged with every replica configuration listed in replicas.
replicaPdoPDO – The PDO instance for the currently active replica connection.
replicasarray – list of replica connection configurations.
shufflePrimariesboolean – whether to shuffle primaries before getting one.

enableReplicas ​

Type
boolean
Default value
null

whether to enable read/write splitting by using replicas to read data. Note that if replicas is empty, read/write splitting will NOT be enabled no matter what value this property takes.

View source

primaries ​

Type
array
Default value
null

list of primary connection configurations. Each configuration is used to create a primary DB connection. When \craft\db\open() is called, one of these configurations will be chosen and used to create a DB connection which will be used by this object. Note that when this property is not empty, the connection setting (e.g. dsn, username) of this object will be ignored.

View source

primary ​

Type
craft\db\Connection, null
Default value
null

The currently active primary connection. null is returned if no primary connection is available. This property is read-only.

View source

primaryConfig ​

Type
array
Default value
null

the configuration that should be merged with every primary configuration listed in primaries. For example,

php
[
    'username' => 'primary',
    'password' => 'primary',
    'attributes' => [
        // use a smaller connection timeout
        PDO::ATTR_TIMEOUT => 10,
    ],
]

View source

primaryPdo ​

Type
PDO
Default value
null

The PDO instance for the currently active primary connection. This property is read-only.

View source

replica ​

Type
craft\db\Connection
Default value
null

The currently active replica connection. This property is read-only.

View source

replicaConfig ​

Type
array
Default value
null

the configuration that should be merged with every replica configuration listed in replicas. For example,

php
[
    'username' => 'replica',
    'password' => 'replica',
    'attributes' => [
        // use a smaller connection timeout
        PDO::ATTR_TIMEOUT => 10,
    ],
]

View source

replicaPdo ​

Type
PDO
Default value
null

The PDO instance for the currently active replica connection. This property is read-only.

View source

replicas ​

Type
array
Default value
null

list of replica connection configurations. Each configuration is used to create a replica DB connection. When enableReplicas is true, one of these configurations will be chosen and used to create a DB connection for performing read queries only.

View source

shufflePrimaries ​

Type
boolean
Default value
null

whether to shuffle primaries before getting one.

View source

Public Methods ​

MethodDescription
getPrimary()Returns the currently active primary connection.
getPrimaryPdo()Returns the PDO instance for the currently active primary connection.
getReplica()Returns the currently active replica connection.
getReplicaPdo()Returns the PDO instance for the currently active replica connection.
usePrimary()Executes the provided callback by using the primary connection.

getPrimary() ​

Returns the currently active primary connection.

If this method is called for the first time, it will try to open a primary connection.

View source

Returns ​

craft\db\Connection, null – The currently active primary connection. null is returned if no primary connection is available.

getPrimaryPdo() ​

Returns the PDO instance for the currently active primary connection.

This method will open the primary DB connection and then return \craft\db\pdo.

View source

Returns ​

PDO – The PDO instance for the currently active primary connection.

getReplica() ​

Returns the currently active replica connection.

If this method is called for the first time, it will try to open a replica connection when enableReplicas is true.

View source

Arguments ​

  • $fallbackToPrimary (boolean) – Whether to return the primary connection if no replica connections are available.

Returns ​

craft\db\Connection, null – The currently active replica connection. null is returned if no replica connections are available and $fallbackToPrimary is false.

getReplicaPdo() ​

Returns the PDO instance for the currently active replica connection.

When enableReplicas is true, one of the replicas will be used for read queries, and its PDO instance will be returned by this method.

View source

Arguments ​

  • $fallbackToPrimary (boolean) – Whether to return the primary PDO if no replica connections are available.

Returns ​

PDO, null – The PDO instance for the currently active replica connection. null is returned if no replica connections are available and $fallbackToPrimary is false.

usePrimary() ​

Executes the provided callback by using the primary connection.

This method is provided so that you can temporarily force using the primary connection to perform DB operations even if they are read queries. For example,

php
$result = $db->usePrimary(function ($db) {
    return $db->createCommand('SELECT * FROM user LIMIT 1')->queryOne();
});

View source

Arguments ​

  • $callback (callable) – A PHP callable to be executed by this method. Its signature is function (Connection $db). Its return value will be returned by this method.

Returns ​

mixed – The return value of the callback

Throws ​

  • Throwable
    if there is any exception thrown from the callback