1	<?php
2	/**
3	* This program is free software; you can redistribute it and/or modify
4	* it under the terms of the GNU General Public License as published by
5	* the Free Software Foundation; either version 2 of the License, or
6	* (at your option) any later version.
7	*
8	* This program is distributed in the hope that it will be useful,
9	* but WITHOUT ANY WARRANTY; without even the implied warranty of
10	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11	* GNU General Public License for more details.
12	*
13	* You should have received a copy of the GNU General Public License along
14	* with this program; if not, write to the Free Software Foundation, Inc.,
15	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16	* http://www.gnu.org/copyleft/gpl.html
17	*
18	* @file
19	*/
20	namespace Wikimedia\Rdbms;
21
22	use Exception;
23
24	/**
25	* Internal interface for LoadBalancer methods used by LBFactory
26	*
27	* Used by untracked objects returned from newMainLB().
28	*
29	* @internal
30	* @since 1.39
31	* @ingroup Database
32	*/
33	interface ILoadBalancerForOwner extends ILoadBalancer {
34	/** Manager of ILoadBalancer instances is running post-commit callbacks */
35	public const STAGE_POSTCOMMIT_CALLBACKS = 'stage-postcommit-callbacks';
36	/** Manager of ILoadBalancer instances is running post-rollback callbacks */
37	public const STAGE_POSTROLLBACK_CALLBACKS = 'stage-postrollback-callbacks';
38
39	/**
40	* @param array $params Parameter map with keys:
41	*  - servers : List of server configuration maps, starting with either the global master
42	*     or local datacenter multi-master, and optionally followed by local datacenter replicas.
43	*     Each server configuration map has the same format as the Database::factory() $params
44	*     argument, with the following additional optional fields:
45	*      - type: the DB type (sqlite, mysql, postgres,...)
46	*      - groupLoads: map of (group => weight for this server) [optional]
47	*      - max lag: per-server override of the "max lag" [optional]
48	*      - is static: whether the dataset is static *and* this server has a copy [optional]
49	*  - localDomain: A DatabaseDomain or domain ID string
50	*  - loadMonitor : LoadMonitor::__construct() parameters with "class" field [optional]
51	*  - readOnlyReason : Reason the primary server is read-only (false if not) [optional]
52	*  - srvCache : BagOStuff object for server cache [optional]
53	*  - wanCache : WANObjectCache object [optional]
54	*  - databaseFactory: DatabaseFactory object [optional]
55	*  - chronologyProtector: ChronologyProtector object [optional]
56	*  - defaultGroup: Default query group; the generic group if not specified [optional]
57	*  - hostname : The name of the current server [optional]
58	*  - cliMode: Whether the execution context is a CLI script [optional]
59	*  - profiler : Callback that takes a section name argument and returns
60	*      a ScopedCallback instance that ends the profile section in its destructor [optional]
61	*  - trxProfiler: TransactionProfiler instance [optional]
62	*  - logger: PSR-3 logger instance [optional]
63	*  - errorLogger : Callback that takes an Exception and logs it [optional]
64	*  - deprecationLogger: Callback to log a deprecation warning [optional]
65	*  - roundStage: STAGE_POSTCOMMIT_* class constant; for internal use [optional]
66	*  - clusterName: The name of the overall (single/multi-datacenter) cluster of servers
67	*     managing the dataset, regardless of 'servers' excluding replicas and
68	*     multi-masters from remote datacenter [optional]
69	*  - criticalSectionProvider: CriticalSectionProvider instance [optional]
70	*/
71	public function __construct( array $params );
72
73	/**
74	* Close all connections and disable this load balancer
75	*
76	* Any attempt to open a new connection will result in a DBAccessError.
77	*
78	* @param string $fname Caller name
79	*/
80	public function disable( $fname = __METHOD__ );
81
82	/**
83	* Close all open connections
84	*
85	* @param string $fname Caller name
86	*
87	*/
88	public function closeAll( $fname = __METHOD__ );
89
90	/**
91	* Run pre-commit callbacks and defer execution of post-commit callbacks
92	*
93	* Use this only for multi-database commits
94	*
95	* @param string $fname Caller name
96	* @return int Number of pre-commit callbacks run (since 1.32)
97	* @since 1.37
98	*/
99	public function finalizePrimaryChanges( $fname = __METHOD__ );
100
101	/**
102	* Perform all pre-commit checks for things like replication safety
103	*
104	* Use this only for multi-database commits
105	*
106	* @param int $maxWriteDuration : max write query duration time in seconds
107	* @param string $fname Caller name
108	* @throws DBTransactionError
109	* @since 1.37
110	*/
111	public function approvePrimaryChanges( int $maxWriteDuration, $fname = __METHOD__ );
112
113	/**
114	* Flush any primary transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set)
115	*
116	* The DBO_TRX setting will be reverted to the default in each of these methods:
117	*   - commitPrimaryChanges()
118	*   - rollbackPrimaryChanges()
119	* This allows for custom transaction rounds from any outer transaction scope.
120	*
121	* @param string $fname Caller name
122	* @throws DBExpectedError
123	* @since 1.37
124	*/
125	public function beginPrimaryChanges( $fname = __METHOD__ );
126
127	/**
128	* Issue COMMIT on all open primary connections to flush changes and view snapshots
129	* @param string $fname Caller name
130	* @throws DBExpectedError
131	* @since 1.37
132	*/
133	public function commitPrimaryChanges( $fname = __METHOD__ );
134
135	/**
136	* Consume and run all pending post-COMMIT/ROLLBACK callbacks and commit dangling transactions
137	*
138	* @param string $fname Caller name
139	* @return Exception|null The first exception or null if there were none
140	* @since 1.37
141	*/
142	public function runPrimaryTransactionIdleCallbacks( $fname = __METHOD__ );
143
144	/**
145	* Run all recurring post-COMMIT/ROLLBACK listener callbacks
146	*
147	* @param string $fname Caller name
148	* @return Exception|null The first exception or null if there were none
149	* @since 1.37
150	*/
151	public function runPrimaryTransactionListenerCallbacks( $fname = __METHOD__ );
152
153	/**
154	* Issue ROLLBACK only on primary, only if queries were done on connection
155	*
156	* @param string $fname Caller name
157	* @throws DBExpectedError
158	* @since 1.37
159	*/
160	public function rollbackPrimaryChanges( $fname = __METHOD__ );
161
162	/**
163	* Release/destroy session-level named locks, table locks, and temp tables
164	*
165	* Only call this function right after calling rollbackPrimaryChanges()
166	*
167	* @param string $fname Caller name
168	* @throws DBExpectedError
169	* @since 1.38
170	*/
171	public function flushPrimarySessions( $fname = __METHOD__ );
172
173	/**
174	* Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshots
175	*
176	* @param string $fname Caller name
177	*/
178	public function flushReplicaSnapshots( $fname = __METHOD__ );
179
180	/**
181	* Commit all primary DB transactions so as to flush any REPEATABLE-READ or SSI snapshots
182	*
183	* An error will be thrown if a connection has pending writes or callbacks
184	*
185	* @param string $fname Caller name
186	* @since 1.37
187	*/
188	public function flushPrimarySnapshots( $fname = __METHOD__ );
189
190	/**
191	* Get the list of callers that have pending primary changes
192	*
193	* @return string[] List of method names
194	* @since 1.37
195	*/
196	public function pendingPrimaryChangeCallers();
197
198	/**
199	* Set a new table prefix for the existing local domain ID for testing
200	*
201	* @param string $prefix
202	* @since 1.33
203	*/
204	public function setLocalDomainPrefix( $prefix );
205
206	/**
207	* Reconfigure using the given config array.
208	* If the config changed, this invalidates all existing connections.
209	*
210	* @warning This must only be called in top level code, typically via
211	* LBFactory::reconfigure.
212	*
213	* @since 1.39
214	*
215	* @param array $conf A configuration array, using the same structure as
216	*        the one passed to the LoadBalancer's constructor.
217	*/
218	public function reconfigure( array $conf );
219
220	/**
221	* Close all connection and redefine the local domain for testing or schema creation
222	*
223	* @param DatabaseDomain|string $domain
224	* @since 1.33
225	*/
226	public function redefineLocalDomain( $domain );
227
228	/**
229	* @return bool Whether a primary connection is already open
230	* @since 1.37
231	*/
232	public function hasPrimaryConnection();
233
234	/**
235	* Convert certain index names to alternative names before querying the DB
236	*
237	* Note that this applies to indexes regardless of the table they belong to.
238	*
239	* This can be employed when an index was renamed X => Y in code, but the new Y-named
240	* indexes were not yet built on all DBs. After all the Y-named ones are added by the DBA,
241	* the aliases can be removed, and then the old X-named indexes dropped.
242	*
243	* @param string[] $aliases
244	* @since 1.31
245	*/
246	public function setIndexAliases( array $aliases );
247
248	/**
249	* Get the timestamp of the latest write query done by this thread
250	* @return float|false UNIX timestamp or false
251	* @since 1.37
252	*/
253	public function lastPrimaryChangeTimestamp();
254
255	/**
256	* Set the primary wait position and wait for ALL replica DBs to catch up to it
257	*
258	* This method is only intended for use a throttling mechanism for high-volume updates.
259	* Unlike waitFor(), failure does not effect laggedReplicaUsed().
260	*
261	* @param DBPrimaryPos $pos Primary position
262	* @param int|null $timeout Max seconds to wait; default is mWaitTimeout
263	* @return bool Success (able to connect and no timeouts reached)
264	*/
265	public function waitForAll( DBPrimaryPos $pos, $timeout = null );
266
267	/**
268	* Whether a highly "lagged" replica database connection was queried.
269	*
270	* @note This method will never cause a new DB connection
271	* @return bool
272	*/
273	public function laggedReplicaUsed();
274	}