* Helper class to handle automatically marking connections as reusable (via RAII pattern)
* as well handling deferring the actual network connection until the handle is used
*
- * @note: proxy methods are defined explicitly to avoid interface errors
* @ingroup Database
* @since 1.22
*/
private $conn;
/** @var array|null N-tuple of (server index, group, DatabaseDomain|string) */
private $params;
+ /** @var int One of DB_MASTER/DB_REPLICA */
+ private $role;
const FLD_INDEX = 0;
const FLD_GROUP = 1;
/**
* @param ILoadBalancer $lb Connection manager for $conn
- * @param Database|array $conn Database handle or (server index, query groups, domain, flags)
+ * @param Database|array $conn Database or (server index, query groups, domain, flags)
+ * @param int $role The type of connection asked for; one of DB_MASTER/DB_REPLICA
+ * @internal This method should not be called outside of LoadBalancer
*/
- public function __construct( ILoadBalancer $lb, $conn ) {
+ public function __construct( ILoadBalancer $lb, $conn, $role ) {
$this->lb = $lb;
+ $this->role = $role;
if ( $conn instanceof Database ) {
$this->conn = $conn; // live handle
} elseif ( is_array( $conn ) && count( $conn ) >= 4 && $conn[self::FLD_DOMAIN] !== false ) {
function __call( $name, array $arguments ) {
if ( $this->conn === null ) {
- list( $db, $groups, $wiki, $flags ) = $this->params;
- $this->conn = $this->lb->getConnection( $db, $groups, $wiki, $flags );
+ list( $index, $groups, $wiki, $flags ) = $this->params;
+ $this->conn = $this->lb->getConnection( $index, $groups, $wiki, $flags );
}
return $this->conn->$name( ...$arguments );
}
+ /**
+ * @return int DB_MASTER when this *requires* the master DB, otherwise DB_REPLICA
+ * @since 1.33
+ */
+ public function getReferenceRole() {
+ return $this->role;
+ }
+
public function getServerInfo() {
return $this->__call( __FUNCTION__, func_get_args() );
}
}
public function getType() {
+ if ( $this->conn === null ) {
+ // Avoid triggering a database connection
+ if ( $this->params[self::FLD_INDEX] === ILoadBalancer::DB_MASTER ) {
+ $index = $this->lb->getWriterIndex();
+ } else {
+ $index = $this->params[self::FLD_INDEX];
+ }
+ if ( $index >= 0 ) {
+ // In theory, if $index is DB_REPLICA, the type could vary
+ return $this->lb->getServerType( $index );
+ }
+ }
+
return $this->__call( __FUNCTION__, func_get_args() );
}
throw new DBUnexpectedError( $this->conn, 'Cannot close shared connection.' );
}
- public function query( $sql, $fname = __METHOD__, $tempIgnore = false ) {
- return $this->__call( __FUNCTION__, func_get_args() );
+ public function query( $sql, $fname = __METHOD__, $flags = 0 ) {
+ if ( $this->role !== ILoadBalancer::DB_MASTER ) {
+ $flags |= IDatabase::QUERY_REPLICA_ROLE;
+ }
+
+ return $this->__call( __FUNCTION__, [ $sql, $fname, $flags ] );
}
public function freeResult( $res ) {
return $this->__call( __FUNCTION__, func_get_args() );
}
+ public function limitResult( $sql, $limit, $offset = false ) {
+ return $this->__call( __FUNCTION__, func_get_args() );
+ }
+
public function selectRow(
$table, $vars, $conds, $fname = __METHOD__,
$options = [], $join_conds = []
public function lockForUpdate(
$table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
}
public function insert( $table, $a, $fname = __METHOD__, $options = [] ) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] ) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
}
public function nextSequenceValue( $seqName ) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
public function replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__ ) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
public function upsert(
$table, array $rows, $uniqueIndexes, array $set, $fname = __METHOD__
) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
public function deleteJoin(
$delTable, $joinTable, $delVar, $joinVar, $conds, $fname = __METHOD__
) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
public function delete( $table, $conds, $fname = __METHOD__ ) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
$destTable, $srcTable, $varMap, $conds,
$fname = __METHOD__, $insertOptions = [], $selectOptions = [], $selectJoinConds = []
) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
}
public function onTransactionResolution( callable $callback, $fname = __METHOD__ ) {
+ // DB_REPLICA role: caller might want to refresh cache after a REPEATABLE-READ snapshot
return $this->__call( __FUNCTION__, func_get_args() );
}
public function onTransactionCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
+ // DB_REPLICA role: caller might want to refresh cache after a REPEATABLE-READ snapshot
return $this->__call( __FUNCTION__, func_get_args() );
}
public function onTransactionIdle( callable $callback, $fname = __METHOD__ ) {
- return $this->__call( __FUNCTION__, func_get_args() );
+ return $this->onTransactionCommitOrIdle( $callback, $fname );
}
public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
+ // DB_REPLICA role: caller might want to refresh cache after a cache mutex is released
return $this->__call( __FUNCTION__, func_get_args() );
}
public function startAtomic(
$fname = __METHOD__, $cancelable = IDatabase::ATOMIC_NOT_CANCELABLE
) {
+ // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot
return $this->__call( __FUNCTION__, func_get_args() );
}
public function endAtomic( $fname = __METHOD__ ) {
+ // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot
return $this->__call( __FUNCTION__, func_get_args() );
}
public function cancelAtomic( $fname = __METHOD__, AtomicSectionIdentifier $sectionId = null ) {
+ // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot
return $this->__call( __FUNCTION__, func_get_args() );
}
public function doAtomicSection(
$fname, callable $callback, $cancelable = self::ATOMIC_NOT_CANCELABLE
) {
+ // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot
return $this->__call( __FUNCTION__, func_get_args() );
}
}
public function lockIsFree( $lockName, $method ) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
public function lock( $lockName, $method, $timeout = 5 ) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
public function unlock( $lockName, $method ) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
public function getScopedLockAndFlush( $lockKey, $fname, $timeout ) {
+ $this->assertRoleAllowsWrites();
+
return $this->__call( __FUNCTION__, func_get_args() );
}
return $this->__call( __FUNCTION__, func_get_args() );
}
+ /**
+ * Error out if the role is not DB_MASTER
+ *
+ * Note that the underlying connection may or may not itself be read-only.
+ * It could even be to a writable master (both server-side and to the application).
+ * This error is meant for the case when a DB_REPLICA handle was requested but a
+ * a write was attempted on that handle regardless.
+ *
+ * In configurations where the master DB has some generic read load or is the only server,
+ * DB_MASTER/DB_REPLICA will sometimes (or always) use the same connection to the master DB.
+ * This does not effect the role of DBConnRef instances.
+ * @throws DBReadOnlyRoleError
+ */
+ protected function assertRoleAllowsWrites() {
+ // DB_MASTER is "prima facie" writable
+ if ( $this->role !== ILoadBalancer::DB_MASTER ) {
+ throw new DBReadOnlyRoleError( $this->conn, "Cannot write with role DB_REPLICA" );
+ }
+ }
+
/**
* Clean up the connection when out of scope
*/