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