PrimaryReplicaTrait
- Type
- Trait
- Namespace
- craft\db
- Implemented by
- craft\db\Connection
- Since
- 3.4.25
View source (opens new window)
# Public Properties
Property | Description |
---|---|
enableReplicas | boolean (opens new window) – whether to enable read/write splitting by using replicas to read data. |
primaries | array (opens new window) – list of primary connection configurations. |
primary | yii\db\Connection (opens new window), 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. |
primaryPdo | PDO (opens new window) – The PDO instance for the currently active primary connection. |
replica | yii\db\Connection (opens new window) – 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. |
shufflePrimaries | boolean (opens new window) – whether to shuffle primaries before getting one. |
# enableReplicas
- Type
- boolean (opens new window)
- 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 (opens new window)
# primaries
- Type
- array (opens new window)
- 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 (opens new window)
# primary
- Type
- yii\db\Connection (opens new window), null (opens new window)
- Default value
null
The currently active primary connection. null
is returned if no primary
connection is available. This property is read-only.
View source (opens new window)
# primaryConfig
- Type
- array (opens new window)
- Default value
null
the configuration that should be merged with every primary configuration listed in primaries. For example,
[
'username' => 'primary',
'password' => 'primary',
'attributes' => [
// use a smaller connection timeout
PDO::ATTR_TIMEOUT => 10,
],
]
View source (opens new window)
# primaryPdo
- Type
- PDO (opens new window)
- Default value
null
The PDO instance for the currently active primary connection. This property is read-only.
View source (opens new window)
# replica
- Type
- yii\db\Connection (opens new window)
- Default value
null
The currently active replica connection. This property is read-only.
View source (opens new window)
# replicaConfig
- Type
- array (opens new window)
- Default value
null
the configuration that should be merged with every replica configuration listed in replicas. For example,
[
'username' => 'replica',
'password' => 'replica',
'attributes' => [
// use a smaller connection timeout
PDO::ATTR_TIMEOUT => 10,
],
]
View source (opens new window)
# replicaPdo
- Type
- PDO (opens new window)
- Default value
null
The PDO instance for the currently active replica connection. This property is read-only.
View source (opens new window)
# replicas
- Type
- array (opens new window)
- 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 (opens new window)
# shufflePrimaries
- Type
- boolean (opens new window)
- Default value
null
whether to shuffle primaries before getting one.
View source (opens new window)
# 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 (opens new window)
Returns
yii\db\Connection (opens new window), null (opens new window) – 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 (opens new window)
Returns
PDO (opens new window) – 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 (opens new window)
Arguments
$fallbackToPrimary
(boolean (opens new window)) – Whether to return the primary connection if no replica connections are available.
Returns
yii\db\Connection (opens new window), null (opens new window) – 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 (opens new window)
Arguments
$fallbackToPrimary
(boolean (opens new window)) – Whether to return the primary PDO if no replica connections are available.
Returns
PDO (opens new window), null (opens new window) – 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 (opens new window)
Arguments
$callback
(callable (opens new window)) – A PHP callable to be executed by this method. Its signature isfunction (Connection $db)
. Its return value will be returned by this method.
Returns
mixed
– The return value of the callback
Throws
- Throwable (opens new window)
if there is any exception thrown from the callback