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