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	/**
23	* Internal interface for relational database handles exposed to their owner
24	*
25	* Instances are either owned by a LoadBalancer object or owned by the caller that created
26	* the instance using a constructor/factory function such as DatabaseFactory::create().
27	*
28	* @ingroup Database
29	* @internal Only for use within the rdbms library
30	*/
31	interface IDatabaseForOwner extends IDatabase {
32
33	/**
34	* Run a callback after each time any transaction commits or rolls back
35	*
36	* The callback takes two arguments:
37	*   - IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_ROLLBACK
38	*   - This IDatabase object
39	* Callbacks must commit any transactions that they begin.
40	*
41	* Registering a callback here will not affect writesOrCallbacks() pending.
42	*
43	* Since callbacks from this or onTransactionCommitOrIdle() can start and end transactions,
44	* a single call to IDatabase::commit might trigger multiple runs of the listener callbacks.
45	*
46	* @param string $name Callback name
47	* @param callable|null $callback Use null to unset a listener
48	* @since 1.28
49	*/
50	public function setTransactionListener( $name, ?callable $callback = null );
51
52	/**
53	* @return bool Whether this DB server is running in server-side read-only mode
54	* @throws DBError If an error occurs, {@see query}
55	* @since 1.28
56	*/
57	public function serverIsReadOnly();
58
59	/**
60	* Get the replication position of this primary DB server
61	*
62	* @return DBPrimaryPos|false Position; false if this is not a primary DB
63	* @throws DBError If an error occurs, {@see query}
64	* @since 1.37
65	*/
66	public function getPrimaryPos();
67
68	/**
69	* Get the time spend running write queries for this transaction
70	*
71	* High values could be due to scanning, updates, locking, and such.
72	*
73	* @param string $type IDatabase::ESTIMATE_* constant [default: ESTIMATE_ALL]
74	* @return float|false Returns false if not transaction is active
75	* @since 1.26
76	*/
77	public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL );
78
79	/**
80	* Whether there is a transaction open with either possible write queries
81	* or unresolved pre-commit/commit/resolution callbacks pending
82	*
83	* This does *not* count recurring callbacks, e.g. from setTransactionListener().
84	*
85	* @return bool
86	*/
87	public function writesOrCallbacksPending();
88
89	/**
90	* @return bool Whether there is a transaction open with possible write queries
91	* @since 1.27
92	*/
93	public function writesPending();
94
95	/**
96	* Get the list of method names that did write queries for this transaction
97	*
98	* @return array
99	* @since 1.27
100	*/
101	public function pendingWriteCallers();
102
103	/**
104	* Release important session-level state (named lock, table locks) as post-rollback cleanup
105	*
106	* This should only be called by a load balancer or if the handle is not attached to one.
107	* Also, there must be no chance that a future caller will still be expecting some of the
108	* lost session state.
109	*
110	* Connection and query errors will be suppressed and logged
111	*
112	* @param string $fname Calling function name @phan-mandatory-param
113	* @param string $flush Flush flag, set to a situationally valid IDatabase::FLUSHING_*
114	*   constant to disable warnings about explicitly rolling back implicit transactions.
115	*   This will silently break any ongoing explicit transaction. Only set the flush flag
116	*   if you are sure that it is safe to ignore these warnings in your context.
117	* @throws DBError If an error occurs, {@see query}
118	* @since 1.38
119	*/
120	public function flushSession( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
121
122	/**
123	* Get the last time that the connection was used to commit a write
124	*
125	* @internal Should only be called from the rdbms library.
126	*
127	* @return float|null UNIX timestamp; null if no writes were committed
128	* @since 1.24
129	*/
130	public function lastDoneWrites();
131
132	/**
133	* Set the entire array or a particular key of the managing load balancer info array
134	*
135	* Keys matching the IDatabase::LB_* constants are also used internally by subclasses
136	*
137	* @internal should not be called outside of rdbms library.
138	*
139	* @param array|string $nameOrArray The new array or the name of a key to set
140	* @param array|mixed|null $value If $nameOrArray is a string, the new key value (null to unset)
141	*/
142	public function setLBInfo( $nameOrArray, $value = null );
143
144	/**
145	* Wait for the replica server to catch up to a given primary server position
146	*
147	* Note that this does not start any new transactions.
148	*
149	* Callers might want to flush any existing transaction before invoking this method.
150	* Upon success, this assures that replica server queries will reflect all changes up
151	* to the given position, without interference from prior REPEATABLE-READ snapshots.
152	*
153	* @param DBPrimaryPos $pos
154	* @param int $timeout The maximum number of seconds to wait for synchronisation
155	* @return int|null Zero if the replica DB server was past that position already,
156	*   greater than zero if we waited for some period of time, less than
157	*   zero if it timed out, and null on error
158	* @throws DBError If an error occurs, {@see query}
159	* @since 1.37
160	*/
161	public function primaryPosWait( DBPrimaryPos $pos, $timeout );
162	}