PrimaryReplicaTrait

Type

Trait

Namespace

craft\db

Implemented by

craft\db\Connection

Since

3.4.25

View source

Public Properties

Property	Description
enableReplicas	boolean – whether to enable read/write splitting by using replicas to read data.
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.
primaryPdo	PDO – The PDO instance for the currently active primary connection.
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.
shufflePrimaries	boolean – 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,

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,

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

Method	Description
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,

$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