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.
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.
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
21 namespace MediaWiki\Storage
;
24 use Psr\Log\LoggerInterface
;
26 use Wikimedia\Assert\Assert
;
27 use Wikimedia\Rdbms\Database
;
28 use Wikimedia\Rdbms\IDatabase
;
29 use Wikimedia\Rdbms\ILoadBalancer
;
30 use Wikimedia\Rdbms\LoadBalancer
;
36 class NameTableStore
{
38 /** @var LoadBalancer */
39 private $loadBalancer;
41 /** @var WANObjectCache */
44 /** @var LoggerInterface */
48 private $tableCache = null;
50 /** @var bool|string */
51 private $wikiId = false;
62 /** @var null|callable */
63 private $normalizationCallback = null;
64 /** @var null|callable */
65 private $insertCallback = null;
68 * @param ILoadBalancer $dbLoadBalancer A load balancer for acquiring database connections
69 * @param WANObjectCache $cache A cache manager for caching data
70 * @param LoggerInterface $logger
71 * @param string $table
72 * @param string $idField
73 * @param string $nameField
74 * @param callable|null $normalizationCallback Normalization to be applied to names before being
75 * saved or queried. This should be a callback that accepts and returns a single string.
76 * @param bool|string $wikiId The ID of the target wiki database. Use false for the local wiki.
77 * @param callable|null $insertCallback Callback to change insert fields accordingly.
78 * This parameter was introduced in 1.32
80 public function __construct(
81 ILoadBalancer
$dbLoadBalancer,
82 WANObjectCache
$cache,
83 LoggerInterface
$logger,
87 callable
$normalizationCallback = null,
89 callable
$insertCallback = null
91 $this->loadBalancer
= $dbLoadBalancer;
92 $this->cache
= $cache;
93 $this->logger
= $logger;
94 $this->table
= $table;
95 $this->idField
= $idField;
96 $this->nameField
= $nameField;
97 $this->normalizationCallback
= $normalizationCallback;
98 $this->wikiId
= $wikiId;
99 $this->cacheTTL
= IExpiringStore
::TTL_MONTH
;
100 $this->insertCallback
= $insertCallback;
104 * @param int $index A database index, like DB_MASTER or DB_REPLICA
105 * @param int $flags Database connection flags
109 private function getDBConnection( $index, $flags = 0 ) {
110 return $this->loadBalancer
->getConnection( $index, [], $this->wikiId
, $flags );
114 * Gets the cache key for names.
116 * The cache key is constructed based on the wiki ID passed to the constructor, and allows
117 * sharing of name tables cached for a specific database between wikis.
121 private function getCacheKey() {
122 return $this->cache
->makeGlobalKey(
125 $this->loadBalancer
->resolveDomainID( $this->wikiId
)
130 * @param string $name
133 private function normalizeName( $name ) {
134 if ( $this->normalizationCallback
=== null ) {
137 return call_user_func( $this->normalizationCallback
, $name );
141 * Acquire the id of the given name.
142 * This creates a row in the table if it doesn't already exist.
144 * @param string $name
145 * @throws NameTableAccessException
148 public function acquireId( $name ) {
149 Assert
::parameterType( 'string', $name, '$name' );
150 $name = $this->normalizeName( $name );
152 $table = $this->getTableFromCachesOrReplica();
153 $searchResult = array_search( $name, $table, true );
154 if ( $searchResult === false ) {
155 $id = $this->store( $name );
156 if ( $id === null ) {
157 // RACE: $name was already in the db, probably just inserted, so load from master
158 // Use DBO_TRX to avoid missing inserts due to other threads or REPEATABLE-READs
159 $table = $this->loadTable(
160 $this->getDBConnection( DB_MASTER
, LoadBalancer
::CONN_TRX_AUTOCOMMIT
)
162 $searchResult = array_search( $name, $table, true );
163 if ( $searchResult === false ) {
164 // Insert failed due to IGNORE flag, but DB_MASTER didn't give us the data
165 $m = "No insert possible but master didn't give us a record for " .
166 "'{$name}' in '{$this->table}'";
167 $this->logger
->error( $m );
168 throw new NameTableAccessException( $m );
170 $this->purgeWANCache(
172 $this->cache
->reap( $this->getCacheKey(), INF
);
178 // As store returned an ID we know we inserted so delete from WAN cache
179 $this->purgeWANCache(
181 $this->cache
->delete( $this->getCacheKey() );
185 $this->tableCache
= $table;
188 return $searchResult;
192 * Get the id of the given name.
193 * If the name doesn't exist this will throw.
194 * This should be used in cases where we believe the name already exists or want to check for
197 * @param string $name
198 * @throws NameTableAccessException The name does not exist
201 public function getId( $name ) {
202 Assert
::parameterType( 'string', $name, '$name' );
203 $name = $this->normalizeName( $name );
205 $table = $this->getTableFromCachesOrReplica();
206 $searchResult = array_search( $name, $table, true );
208 if ( $searchResult !== false ) {
209 return $searchResult;
212 throw NameTableAccessException
::newFromDetails( $this->table
, 'name', $name );
216 * Get the name of the given id.
217 * If the id doesn't exist this will throw.
218 * This should be used in cases where we believe the id already exists.
220 * Note: Calls to this method will result in a master select for non existing IDs.
223 * @throws NameTableAccessException The id does not exist
224 * @return string name
226 public function getName( $id ) {
227 Assert
::parameterType( 'integer', $id, '$id' );
229 $table = $this->getTableFromCachesOrReplica();
230 if ( array_key_exists( $id, $table ) ) {
234 $table = $this->cache
->getWithSetCallback(
235 $this->getCacheKey(),
237 function ( $oldValue, &$ttl, &$setOpts ) use ( $id ) {
238 // Check if cached value is up-to-date enough to have $id
239 if ( is_array( $oldValue ) && array_key_exists( $id, $oldValue ) ) {
240 // Completely leave the cache key alone
241 $ttl = WANObjectCache
::TTL_UNCACHEABLE
;
245 // Regenerate from replica DB, and master DB if needed
246 foreach ( [ DB_REPLICA
, DB_MASTER
] as $source ) {
247 // Log a fallback to master
248 if ( $source === DB_MASTER
) {
250 __METHOD__
. 'falling back to master select from ' .
251 $this->table
. ' with id ' . $id
254 $db = $this->getDBConnection( $source );
255 $cacheSetOpts = Database
::getCacheSetOptions( $db );
256 $table = $this->loadTable( $db );
257 if ( array_key_exists( $id, $table ) ) {
261 // Use the value from last source checked
262 $setOpts +
= $cacheSetOpts;
266 [ 'minAsOf' => INF
] // force callback run
269 $this->tableCache
= $table;
271 if ( array_key_exists( $id, $table ) ) {
275 throw NameTableAccessException
::newFromDetails( $this->table
, 'id', $id );
279 * Get the whole table, in no particular order as a map of ids to names.
280 * This method could be subject to DB or cache lag.
282 * @return string[] keys are the name ids, values are the names themselves
283 * Example: [ 1 => 'foo', 3 => 'bar' ]
285 public function getMap() {
286 return $this->getTableFromCachesOrReplica();
292 private function getTableFromCachesOrReplica() {
293 if ( $this->tableCache
!== null ) {
294 return $this->tableCache
;
297 $table = $this->cache
->getWithSetCallback(
298 $this->getCacheKey(),
300 function ( $oldValue, &$ttl, &$setOpts ) {
301 $dbr = $this->getDBConnection( DB_REPLICA
);
302 $setOpts +
= Database
::getCacheSetOptions( $dbr );
303 return $this->loadTable( $dbr );
307 $this->tableCache
= $table;
313 * Reap the WANCache entry for this table.
315 * @param callable $purgeCallback callback to 'purge' the WAN cache
317 private function purgeWANCache( $purgeCallback ) {
318 // If the LB has no DB changes don't both with onTransactionPreCommitOrIdle
319 if ( !$this->loadBalancer
->hasOrMadeRecentMasterChanges() ) {
324 $this->getDBConnection( DB_MASTER
)
325 ->onTransactionPreCommitOrIdle( $purgeCallback, __METHOD__
);
329 * Gets the table from the db
331 * @param IDatabase $db
335 private function loadTable( IDatabase
$db ) {
336 $result = $db->select(
339 'id' => $this->idField
,
340 'name' => $this->nameField
344 [ 'ORDER BY' => 'id' ]
348 foreach ( $result as $row ) {
349 $assocArray[$row->id
] = $row->name
;
356 * Stores the given name in the DB, returning the ID when an insert occurs.
358 * @param string $name
359 * @return int|null int if we know the ID, null if we don't
361 private function store( $name ) {
362 Assert
::parameterType( 'string', $name, '$name' );
363 Assert
::parameter( $name !== '', '$name', 'should not be an empty string' );
364 // Note: this is only called internally so normalization of $name has already occurred.
366 $dbw = $this->getDBConnection( DB_MASTER
);
370 $this->getFieldsToStore( $name ),
375 if ( $dbw->affectedRows() === 0 ) {
377 'Tried to insert name into table ' . $this->table
. ', but value already existed.'
382 return $dbw->insertId();
386 * @param string $name
389 private function getFieldsToStore( $name ) {
390 $fields = [ $this->nameField
=> $name ];
391 if ( $this->insertCallback
!== null ) {
392 $fields = call_user_func( $this->insertCallback
, $fields );