Documentation

MasterSlaveConnection extends Connection
in package

Application

Master-Slave Connection

Connection can be used with master-slave setups.

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

Slave if master was never picked before and ONLY if 'getWrappedConnection' or 'executeQuery' is used.
Master picked when 'exec', 'executeUpdate', 'insert', 'delete', 'update', 'createSavepoint', 'releaseSavepoint', 'beginTransaction', 'rollback', 'commit', 'query' or 'prepare' is called.
If master was picked once during the lifetime of the connection it will always get picked afterwards.
One slave connection is randomly picked ONCE during a request.

ATTENTION: You can write to the slave 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.

This connection is limited to slave 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 slave, which makes this restricted approach necessary.

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

 $conn->connect('master');

Instantiation through the DriverManager looks like:

ARRAY_PARAM_OFFSET

Offset by which PARAM_* constants are detected as arrays of the param type.


    public
    int
    ARRAY_PARAM_OFFSET
    = 100

PARAM_INT_ARRAY

Represents an array of ints to be expanded by Doctrine SQL parsing.


    public
    int
    PARAM_INT_ARRAY
    = 101

PARAM_STR_ARRAY

Represents an array of strings to be expanded by Doctrine SQL parsing.


    public
    int
    PARAM_STR_ARRAY
    = 102

TRANSACTION_READ_COMMITTED

Constant for transaction isolation level READ COMMITTED.


    public
    mixed
    TRANSACTION_READ_COMMITTED
    = 2

TRANSACTION_READ_UNCOMMITTED

Constant for transaction isolation level READ UNCOMMITTED.


    public
    mixed
    TRANSACTION_READ_UNCOMMITTED
    = 1

TRANSACTION_REPEATABLE_READ

Constant for transaction isolation level REPEATABLE READ.


    public
    mixed
    TRANSACTION_REPEATABLE_READ
    = 3

TRANSACTION_SERIALIZABLE

Constant for transaction isolation level SERIALIZABLE.


    public
    mixed
    TRANSACTION_SERIALIZABLE
    = 4

$_config


    protected
        Configuration
    $_config

$_conn

The wrapped driver connection.


    protected
        Connection
    $_conn

$_driver

The used DBAL driver.


    protected
        Driver
    $_driver

$_eventManager


    protected
        EventManager
    $_eventManager

$_expr


    protected
        ExpressionBuilder
    $_expr

$_schemaManager

The schema manager.


    protected
        AbstractSchemaManager
    $_schemaManager

$connections

Master and slave connection (one of the randomly picked slaves).


    protected
        array<string|int, Connection>
    $connections
     = array('master' => null, 'slave' => null)

$defaultFetchMode


    protected
        int
    $defaultFetchMode
     = PDO::FETCH_ASSOC

$keepSlave

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


    protected
        bool
    $keepSlave
     = false

$_isConnected

Whether or not a connection has been established.


    private
        bool
    $_isConnected
     = false

$_isRollbackOnly

Flag that indicates whether the current transaction is marked for rollback only.


    private
        bool
    $_isRollbackOnly
     = false

$_nestTransactionsWithSavepoints

If nested transactions should use savepoints.


    private
        bool
    $_nestTransactionsWithSavepoints
     = false

$_params

The parameters used during creation of the Connection instance.


    private
        array<string|int, mixed>
    $_params
     = array()

$_transactionIsolationLevel

The currently active transaction isolation level.


    private
        int
    $_transactionIsolationLevel

$_transactionNestingLevel

The transaction nesting level.


    private
        int
    $_transactionNestingLevel
     = 0

$autoCommit

The current auto-commit mode of this connection.


    private
        bool
    $autoCommit
     = true

$platform

The DatabasePlatform object that provides information about the database platform used by the connection.


    private
        AbstractPlatform
    $platform

__construct()

Creates Master Slave Connection.


    public
                __construct(array<string|int, mixed> $params, Driver $driver[, Configuration|null $config = null ][, EventManager|null $eventManager = null ]) : mixed

Parameters

$params : array<string|int, mixed>
$driver : Driver
$config : Configuration|null = null
$eventManager : EventManager|null = null

Return values

mixed —

beginTransaction()

Starts a transaction by suspending auto-commit mode.


    public
                beginTransaction() : void

Return values

void —

close()

Closes the connection.


    public
                close() : void

Return values

void —

commit()

Commits the current transaction.


    public
                commit() : void

Return values

void —

connect()

Establishes the connection with the database.


    public
                connect([mixed $connectionName = null ]) : bool

Parameters

$connectionName : mixed = null

Return values

bool —

TRUE if the connection was successfully established, FALSE if the connection is already open.

convertToDatabaseValue()

Converts a given value to its database representation according to the conversion rules of a specific DBAL mapping type.


    public
                convertToDatabaseValue(mixed $value, string $type) : mixed

Parameters

$value : mixed: The value to convert.
$type : string: The name of the DBAL mapping type.

Return values

mixed —

The converted value.

convertToPHPValue()

Converts a given value to its PHP representation according to the conversion rules of a specific DBAL mapping type.


    public
                convertToPHPValue(mixed $value, string $type) : mixed

Parameters

$value : mixed: The value to convert.
$type : string: The name of the DBAL mapping type.

Return values

mixed —

The converted type.

createQueryBuilder()

Creates a new instance of a SQL query builder.


    public
                createQueryBuilder() : QueryBuilder

Return values

QueryBuilder —

createSavepoint()

Creates a new savepoint.


    public
                createSavepoint(mixed $savepoint) : void

Parameters

$savepoint : mixed: The name of the savepoint to create.

Return values

void —

delete()

Executes an SQL DELETE statement on a table.


    public
                delete(mixed $tableName, array<string|int, mixed> $identifier[, array<string|int, mixed> $types = array() ]) : int

Parameters

$tableName : mixed
$identifier : array<string|int, mixed>: The deletion criteria. An associative array containing column-value pairs.
$types : array<string|int, mixed> = array(): The types of identifiers.

Return values

int —

The number of affected rows.

errorCode()

Fetches the SQLSTATE associated with the last database operation.


    public
                errorCode() : int

Return values

int —

The last error code.

errorInfo()

Fetches extended error information associated with the last database operation.


    public
                errorInfo() : array<string|int, mixed>

Return values

array<string|int, mixed> —

The last error information.

exec()

Executes an SQL statement and return the number of affected rows.


    public
                exec(mixed $statement) : int

Parameters

$statement : mixed

Return values

int —

The number of affected rows.

executeCacheQuery()

Executes a caching query.


    public
                executeCacheQuery(string $query, array<string|int, mixed> $params, array<string|int, mixed> $types, QueryCacheProfile $qcp) : ResultStatement

Parameters

$query : string: The SQL query to execute.
$params : array<string|int, mixed>: The parameters to bind to the query, if any.
$types : array<string|int, mixed>: The types the previous parameters are in.
$qcp : QueryCacheProfile: The query cache profile.

Return values

ResultStatement —

executeQuery()

Executes an, optionally parametrized, SQL query.


    public
                executeQuery(string $query[, array<string|int, mixed> $params = array() ][, array<string|int, mixed> $types = array() ][, QueryCacheProfile|null $qcp = null ]) : Statement

If the query is parametrized, a prepared statement is used. If an SQLLogger is configured, the execution is logged.

Parameters

$query : string: The SQL query to execute.
$params : array<string|int, mixed> = array(): The parameters to bind to the query, if any.
$types : array<string|int, mixed> = array(): The types the previous parameters are in.
$qcp : QueryCacheProfile|null = null: The query cache profile, optional.

Return values

Statement —

The executed statement.

executeUpdate()

Executes an SQL INSERT/UPDATE/DELETE query with the given parameters and returns the number of affected rows.


    public
                executeUpdate(mixed $query[, array<string|int, mixed> $params = array() ][, array<string|int, mixed> $types = array() ]) : int

Parameters

$query : mixed: The SQL query.
$params : array<string|int, mixed> = array(): The query parameters.
$types : array<string|int, mixed> = array(): The parameter types.

Return values

int —

The number of affected rows.

fetchAll()

Prepares and executes an SQL query and returns the result as an associative array.


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

Parameters

$sql : string: The SQL query.
$params : array<string|int, mixed> = array(): The query parameters.
$types : array<string|int, mixed> = array(): The query parameter types.

Return values

array<string|int, mixed> —

fetchArray()

Prepares and executes an SQL query and returns the first row of the result as a numerically indexed array.


    public
                fetchArray(string $statement[, array<string|int, mixed> $params = array() ][, array<string|int, mixed> $types = array() ]) : array<string|int, mixed>

Parameters

$statement : string: The SQL query to be executed.
$params : array<string|int, mixed> = array(): The prepared statement params.
$types : array<string|int, mixed> = array(): The query parameter types.

Return values

array<string|int, mixed> —

fetchAssoc()

Prepares and executes an SQL query and returns the first row of the result as an associative array.


    public
                fetchAssoc(string $statement[, array<string|int, mixed> $params = array() ][, array<string|int, mixed> $types = array() ]) : array<string|int, mixed>

Parameters

$statement : string: The SQL query.
$params : array<string|int, mixed> = array(): The query parameters.
$types : array<string|int, mixed> = array(): The query parameter types.

Return values

array<string|int, mixed> —

fetchColumn()

Prepares and executes an SQL query and returns the value of a single column of the first row of the result.


    public
                fetchColumn(string $statement[, array<string|int, mixed> $params = array() ], int $column[, array<string|int, mixed> $types = array() ]) : mixed

Parameters

$statement : string: The SQL query to be executed.
$params : array<string|int, mixed> = array(): The prepared statement params.
$column : int: The 0-indexed column number to retrieve.
$types : array<string|int, mixed> = array(): The query parameter types.

Return values

mixed —

getConfiguration()

Gets the Configuration used by the Connection.


    public
                getConfiguration() : Configuration

Return values

Configuration —

getDatabase()

Gets the name of the database this Connection is connected to.


    public
                getDatabase() : string

Return values

string —

getDatabasePlatform()

Gets the DatabasePlatform for the connection.


    public
                getDatabasePlatform() : AbstractPlatform

Return values

AbstractPlatform —

getDriver()

Gets the DBAL driver instance.


    public
                getDriver() : Driver

Return values

Driver —

getEventManager()

Gets the EventManager used by the Connection.


    public
                getEventManager() : EventManager

Return values

EventManager —

getExpressionBuilder()

Gets the ExpressionBuilder for the connection.


    public
                getExpressionBuilder() : ExpressionBuilder

Return values

ExpressionBuilder —

getHost()

Gets the hostname of the currently connected database.


    public
                getHost() : string|null

Return values

string|null —

getNestTransactionsWithSavepoints()

Gets if nested transactions should use savepoints.


    public
                getNestTransactionsWithSavepoints() : bool

Return values

bool —

getParams()

Gets the parameters used during instantiation.


    public
                getParams() : array<string|int, mixed>

Return values

array<string|int, mixed> —

getPassword()

Gets the password used by this connection.


    public
                getPassword() : string|null

Return values

string|null —

getPort()

Gets the port of the currently connected database.


    public
                getPort() : mixed

Return values

mixed —

getSchemaManager()

Gets the SchemaManager that can be used to inspect or change the database schema through the connection.


    public
                getSchemaManager() : AbstractSchemaManager

Return values

AbstractSchemaManager —

getTransactionIsolation()

Gets the currently active transaction isolation level.


    public
                getTransactionIsolation() : int

Return values

int —

The current transaction isolation level.

getTransactionNestingLevel()

Returns the current transaction nesting level.


    public
                getTransactionNestingLevel() : int

Return values

int —

The nesting level. A value of 0 means there's no active transaction.

getUsername()

Gets the username used by this connection.


    public
                getUsername() : string|null

Return values

string|null —

getWrappedConnection()

Gets the wrapped driver connection.


    public
                getWrappedConnection() : Connection

Return values

Connection —

insert()

Inserts a table row with specified data.


    public
                insert(mixed $tableName, array<string|int, mixed> $data[, array<string|int, mixed> $types = array() ]) : int

Parameters

$tableName : mixed
$data : array<string|int, mixed>: An associative array containing column-value pairs.
$types : array<string|int, mixed> = array(): Types of the inserted data.

Return values

int —

The number of affected rows.

isAutoCommit()

Returns the current auto-commit mode for this connection.


    public
                isAutoCommit() : bool

Return values

bool —

True if auto-commit mode is currently enabled for this connection, false otherwise.

isConnected()

Whether an actual connection to the database is established.


    public
                isConnected() : bool

Return values

bool —

isConnectedToMaster()

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


    public
                isConnectedToMaster() : bool

Return values

bool —

isRollbackOnly()

Checks whether the current transaction is marked for rollback only.


    public
                isRollbackOnly() : bool

Return values

bool —

isTransactionActive()

Checks whether a transaction is currently active.


    public
                isTransactionActive() : bool

Return values

bool —

TRUE if a transaction is currently active, FALSE otherwise.

lastInsertId()

Returns the ID of the last inserted row, or the last value from a sequence object, depending on the underlying driver.


    public
                lastInsertId([string|null $seqName = null ]) : string

Note: This method may not return a meaningful or consistent result across different drivers, because the underlying database may not even support the notion of AUTO_INCREMENT/IDENTITY columns or sequences.

Parameters

$seqName : string|null = null: Name of the sequence object from which the ID should be returned.

Return values

string —

A string representation of the last inserted ID.

ping()

Ping the server


    public
                ping() : bool

When the server is not available the method returns FALSE. It is responsibility of the developer to handle this case and abort the request or reconnect manually:

Return values

bool —

prepare()

Prepares an SQL statement.


    public
                prepare(mixed $statement) : Statement

Parameters

$statement : mixed: The SQL statement to prepare.

Return values

Statement —

The prepared statement.

project()

Executes an, optionally parametrized, SQL query and returns the result, applying a given projection/transformation function on each row of the result.


    public
                project(string $query, array<string|int, mixed> $params, Closure $function) : array<string|int, mixed>

Parameters

$query : string: The SQL query to execute.
$params : array<string|int, mixed>: The parameters, if any.
$function : Closure: The transformation function that is applied on each row. The function receives a single parameter, an array, that represents a row of the result set.

Return values

array<string|int, mixed> —

The projected result of the query.

query()

Executes an SQL statement, returning a result set as a Statement object.


    public
                query() : Statement

Return values

Statement —

quote()

Quotes a given input parameter.


    public
                quote(mixed $input[, string|null $type = null ]) : string

Parameters

$input : mixed: The parameter to be quoted.
$type : string|null = null: The type of the parameter.

Return values

string —

The quoted parameter.

quoteIdentifier()

Quotes a string so it can be safely used as a table or column name, even if it is a reserved name.


    public
                quoteIdentifier(string $str) : string

Delimiting style depends on the underlying database platform that is being used.

NOTE: Just because you CAN use quoted identifiers does not mean you SHOULD use them. In general, they end up causing way more problems than they solve.

Parameters

$str : string: The name to be quoted.

Return values

string —

The quoted name.

releaseSavepoint()

Releases the given savepoint.


    public
                releaseSavepoint(mixed $savepoint) : void

Parameters

$savepoint : mixed: The name of the savepoint to release.

Return values

void —

rollBack()

Cancels any database changes done during the current transaction.


    public
                rollBack() : bool

Return values

bool —

TRUE on success or FALSE on failure.

rollbackSavepoint()

Rolls back to the given savepoint.


    public
                rollbackSavepoint(mixed $savepoint) : void

Parameters

$savepoint : mixed: The name of the savepoint to rollback to.

Return values

void —

setAutoCommit()

Sets auto-commit mode for this connection.


    public
                setAutoCommit(bool $autoCommit) : mixed

If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either the method commit or the method rollback. By default, new connections are in auto-commit mode.

NOTE: If this method is called during a transaction and the auto-commit mode is changed, the transaction is committed. If this method is called and the auto-commit mode is not changed, the call is a no-op.

Parameters

$autoCommit : bool: True to enable auto-commit mode; false to disable it.

Return values

mixed —

setFetchMode()

Sets the fetch mode.


    public
                setFetchMode(int $fetchMode) : void

Parameters

$fetchMode : int

Return values

void —

setNestTransactionsWithSavepoints()

Sets if nested transactions should use savepoints.


    public
                setNestTransactionsWithSavepoints(bool $nestTransactionsWithSavepoints) : void

Parameters

$nestTransactionsWithSavepoints : bool

Return values

void —

setRollbackOnly()

Marks the current transaction so that the only possible outcome for the transaction to be rolled back.


    public
                setRollbackOnly() : void

Return values

void —

setTransactionIsolation()

Sets the transaction isolation level.


    public
                setTransactionIsolation(int $level) : int

Parameters

$level : int: The level to set.

Return values

int —

transactional()

Executes a function in a transaction.


    public
                transactional(Closure $func) : void

The function gets passed this Connection instance as an (optional) parameter.

If an exception occurs during execution of the function or transaction commit, the transaction is rolled back and the exception re-thrown.

Parameters

$func : Closure: The function to execute transactionally.

Return values

void —

update()

Executes an SQL UPDATE statement on a table.


    public
                update(mixed $tableName, array<string|int, mixed> $data, array<string|int, mixed> $identifier[, array<string|int, mixed> $types = array() ]) : int

Parameters

$tableName : mixed
$data : array<string|int, mixed>: An associative array containing column-value pairs.
$identifier : array<string|int, mixed>: The update criteria. An associative array containing column-value pairs.
$types : array<string|int, mixed> = array(): Types of the merged $data and $identifier arrays in that order.

Return values

int —

The number of affected rows.

_getNestedTransactionSavePointName()

Returns the savepoint name to use for nested transactions are false if they are not supported "savepointFormat" parameter is not set


    protected
                _getNestedTransactionSavePointName() : mixed

Return values

mixed —

A string with the savepoint name or false.

chooseConnectionConfiguration()


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

Parameters

$connectionName : string
$params : array<string|int, mixed>

Return values

mixed —

connectTo()

Connects to a specific connection.


    protected
                connectTo(string $connectionName) : Driver

Parameters

$connectionName : string

Return values

Driver —

commitAll()

Commits all current nesting transactions.


    private
                commitAll() : mixed

Return values

mixed —

detectDatabasePlatform()

Detects and sets the database platform.


    private
                detectDatabasePlatform() : mixed

Evaluates custom platform class and version in order to set the correct platform.

Return values

mixed —

extractTypeValues()

Extract ordered type list from an ordered column list and type map.


    private
                extractTypeValues(array<string|int, mixed> $columnList, array<string|int, mixed> $types) : array<string|int, mixed>

Parameters

$columnList : array<string|int, mixed>
$types : array<string|int, mixed>

Return values

array<string|int, mixed> —

getBindingInfo()

Gets the binding type of a given type. The given type can be a PDO or DBAL mapping type.


    private
                getBindingInfo(mixed $value, mixed $type) : array<string|int, mixed>

Parameters

$value : mixed: The value to bind.
$type : mixed: The type to bind (PDO or DBAL).

Return values

array<string|int, mixed> —

[0] => the (escaped) value, [1] => the binding type.

getDatabasePlatformVersion()

Returns the version of the related platform if applicable.


    private
                getDatabasePlatformVersion() : string|null

Returns null if either the driver is not capable to create version specific platform instances, no explicit server version was specified or the underlying driver connection cannot determine the platform version without having to query it (performance reasons).

Return values

string|null —