Documentation

PrimaryReadReplicaConnection extends Connection
in package

Primary-Replica Connection

Connection can be used with primary-replica setups.

Important for the understanding of this connection should be how and when it picks the replica or primary.

  1. Replica if primary was never picked before and ONLY if 'getWrappedConnection' or 'executeQuery' is used.
  2. Primary picked when 'executeStatement', 'insert', 'delete', 'update', 'createSavepoint', 'releaseSavepoint', 'beginTransaction', 'rollback', 'commit' or 'prepare' is called.
  3. If Primary was picked once during the lifetime of the connection it will always get picked afterwards.
  4. One replica connection is randomly picked ONCE during a request.

ATTENTION: You can write to the replica with this connection if you execute a write query without opening up a transaction. For example:

 $conn = DriverManager::getConnection(...);
 $conn->executeQuery("DELETE FROM table");

Be aware that Connection#executeQuery is a method specifically for READ operations only.

Use Connection#executeStatement for any SQL statement that changes/updates state in the database (UPDATE, INSERT, DELETE or DDL statements).

This connection is limited to replica operations using the Connection#executeQuery operation only, because it wouldn't be compatible with the ORM or SchemaManager code otherwise. Both use all the other operations in a context where writes could happen to a replica, which makes this restricted approach necessary.

You can manually connect to the primary at any time by calling:

 $conn->ensureConnectedToPrimary();

Instantiation through the DriverManager looks like:

Tags
psalm-import-type

Params from DriverManager

example

$conn = DriverManager::getConnection(array( 'wrapperClass' => 'Doctrine\DBAL\Connections\PrimaryReadReplicaConnection', 'driver' => 'pdo_mysql', 'primary' => array('user' => '', 'password' => '', 'host' => '', 'dbname' => ''), 'replica' => array( array('user' => 'replica1', 'password', 'host' => '', 'dbname' => ''), array('user' => 'replica2', 'password', 'host' => '', 'dbname' => ''), ) ));

You can also pass 'driverOptions' and any other documented option to each of this drivers to pass additional information.

Table of Contents

Properties

$connections  : array<string|int, Connection>|array<string|int, null>
Primary and Replica connection (one of the randomly picked replicas).
$keepReplica  : bool
You can keep the replica connection and then switch back to it during the request if you know what you are doing.

Methods

beginTransaction()  : mixed
{@inheritDoc}
close()  : mixed
{@inheritDoc}
commit()  : mixed
{@inheritDoc}
connect()  : bool
createSavepoint()  : mixed
{@inheritDoc}
ensureConnectedToPrimary()  : bool
Connects to the primary node of the database cluster.
ensureConnectedToReplica()  : bool
Connects to a replica node of the database cluster.
executeStatement()  : mixed
{@inheritDoc}
isConnectedToPrimary()  : bool
Checks if the connection is currently towards the primary or not.
prepare()  : Statement
releaseSavepoint()  : mixed
{@inheritDoc}
rollBack()  : mixed
{@inheritDoc}
rollbackSavepoint()  : mixed
{@inheritDoc}
chooseConnectionConfiguration()  : mixed
connectTo()  : Connection
Connects to a specific connection.
performConnect()  : bool

Properties

$connections

Primary and Replica connection (one of the randomly picked replicas).

protected array<string|int, Connection>|array<string|int, null> $connections = ['primary' => null, 'replica' => null]

$keepReplica

You can keep the replica connection and then switch back to it during the request if you know what you are doing.

protected bool $keepReplica = false

Methods

connect()

public connect([string|null $connectionName = null ]) : bool
Parameters
$connectionName : string|null = null
Return values
bool

ensureConnectedToPrimary()

Connects to the primary node of the database cluster.

public ensureConnectedToPrimary() : bool

All following statements after this will be executed against the primary node.

Return values
bool

ensureConnectedToReplica()

Connects to a replica node of the database cluster.

public ensureConnectedToReplica() : bool

All following statements after this will be executed against the replica node, unless the keepReplica option is set to false and a primary connection was already opened.

Return values
bool

executeStatement()

{@inheritDoc}

public executeStatement(mixed $sql[, array<string|int, mixed> $params = [] ][, array<string|int, mixed> $types = [] ]) : mixed
Parameters
$sql : mixed
$params : array<string|int, mixed> = []
$types : array<string|int, mixed> = []

isConnectedToPrimary()

Checks if the connection is currently towards the primary or not.

public isConnectedToPrimary() : bool
Return values
bool

chooseConnectionConfiguration()

protected chooseConnectionConfiguration(string $connectionName, array<string|int, mixed> $params) : mixed
Parameters
$connectionName : string
$params : array<string|int, mixed>

performConnect()

protected performConnect([string|null $connectionName = null ]) : bool
Parameters
$connectionName : string|null = null
Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results