/** @var string Domain specifier when no specific database needs to be selected */
const DOMAIN_ANY = '';
- /** @var bool The generic query group (bool gives b/c with 1.33 method signatures) */
- const GROUP_GENERIC = false;
+ /** @var string The generic query group */
+ const GROUP_GENERIC = '';
/** @var int DB handle should have DBO_TRX disabled and the caller will leave it as such */
const CONN_TRX_AUTOCOMMIT = 1;
/** @var int Return null on connection failure instead of throwing an exception */
const CONN_SILENCE_ERRORS = 2;
+ /** @var int Caller is requesting the master DB server for possibly writes */
+ const CONN_INTENT_WRITABLE = 4;
/** @var string Manager of ILoadBalancer instances is running post-commit callbacks */
const STAGE_POSTCOMMIT_CALLBACKS = 'stage-postcommit-callbacks';
* @see ILoadBalancer::getServerAttributes()
*
* @param int $i Server index (overrides $groups) or DB_MASTER/DB_REPLICA
- * @param string[]|string $groups Query group(s) or [] to use the default group
+ * @param string[]|string $groups Query group(s) in preference order; [] for the default group
* @param string|bool $domain DB domain ID or false for the local domain
* @param int $flags Bitfield of CONN_* class constants
- * @return IDatabase|bool Live connection handle or false on failure
+ *
+ * @note This method throws DBAccessError if ILoadBalancer::disable() was called
+ *
+ * @return IDatabase|bool This returns false on failure if CONN_SILENCE_ERRORS is set
* @throws DBError If no live handle can be obtained and CONN_SILENCE_ERRORS is not set
* @throws DBAccessError If disable() was previously called
+ * @throws InvalidArgumentException
*/
public function getConnection( $i, $groups = [], $domain = false, $flags = 0 );
+ /**
+ * Get a live handle for a server index
+ *
+ * This is a simpler version of getConnection() that does not accept virtual server
+ * indexes (e.g. DB_MASTER/DB_REPLICA), does not assure that master DB handles have
+ * read-only mode when there is high replication lag, and can only trigger attempts
+ * to connect to a single server (the one with the specified server index).
+ *
+ * @see ILoadBalancer::getConnection()
+ *
+ * @param int $i Specific server index
+ * @param string $domain Resolved DB domain
+ * @param int $flags Bitfield of class CONN_* constants
+ * @return IDatabase|bool
+ */
+ public function getServerConnection( $i, $domain, $flags = 0 );
+
/**
* Mark a live handle as being available for reuse under a different database domain
*
* @see ILoadBalancer::getConnection() for parameter information
*
* @param int $i Server index or DB_MASTER/DB_REPLICA
- * @param string[]|string $groups Query group(s) or [] to use the default group
+ * @param string[]|string $groups Query group(s) in preference order; [] for the default group
* @param string|bool $domain DB domain ID or false for the local domain
* @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT)
* @return DBConnRef
* @see ILoadBalancer::getConnection() for parameter information
*
* @param int $i Server index or DB_MASTER/DB_REPLICA
- * @param string[]|string $groups Query group(s) or [] to use the default group
+ * @param string[]|string $groups Query group(s) in preference order; [] for the default group
* @param string|bool $domain DB domain ID or false for the local domain
* @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT)
* @return DBConnRef
* @see ILoadBalancer::getConnection() for parameter information
*
* @param int $i Server index or DB_MASTER/DB_REPLICA
- * @param string[]|string $groups Query group(s) or [] to use the default group
+ * @param string[]|string $groups Query group(s) in preference order; [] for the default group
* @param string|bool $domain DB domain ID or false for the local domain
* @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT)
* @return MaintainableDBConnRef
public function getServerAttributes( $i );
/**
- * Get the current master position for chronology control purposes
+ * Get the current master replication position
+ *
* @return DBMasterPos|bool Returns false if not applicable
+ * @throws DBError
*/
public function getMasterPos();
+ /**
+ * Get the highest DB replication position for chronology control purposes
+ *
+ * If there is only a master server then this returns false. If replication is present
+ * and correctly configured, then this returns the highest replication position of any
+ * server with an open connection. That position can later be passed to waitFor() on a
+ * new load balancer instance to make sure that queries on the new connections see data
+ * at least as up-to-date as queries (prior to this method call) on the old connections.
+ *
+ * This can be useful for implementing session consistency, where the session
+ * will be resumed accross multiple HTTP requests or CLI script instances.
+ *
+ * @return DBMasterPos|bool Replication position or false if not applicable
+ * @since 1.34
+ */
+ public function getReplicaResumePos();
+
/**
* Disable this load balancer. All connections are closed, and any attempt to
* open a new connection will result in a DBAccessError.
dépôts / lhc / web / wiklou.git / blobdiff