Handboek:Database toegang

This page is a translated version of the page Manual:Database access and the translation is 100% complete.

Dit artikel biedt een overzicht van toegang tot databases en algemene database kwesties in MediaWiki.

Wanneer u programmeert in MediaWiki, zult u normaal gesproken alleen de database gebruiken met behulp van MediaWiki-functies.

Database lay-out

Informatie over de MediaWiki database lay-out, bijvoorbeeld over tabellen en hun inhoud, lees Manual:Database layout . Dit was eerder gedocumenteerd in MediaWiki en in maintenance/tables.sql, maar vanaf MediaWiki 1.35 wordt dit in gedeelten verplaatst naar sql/tables.json, als onderdeel van het initiatief Abstract Schema. Dat betekent dat sql/tables.json is omgezet naar sql/mysql/tables-generated.sql door een maintenance script , dit maakt het gemakkelijker om schema-bestanden aan te maken om verschillende database engines te ondersteunen.

Inloggen in MySQL

Gebruik van sql.php

MediaWiki heeft een onderhoudsscript om de database te benaderen. Voer in de map maintenance uit:

php run.php sql

U kunt dan een database query doen. U kunt ook een bestandsnaam opgeven, dat bestand wordt dan door MediaWiki uitgevoerd, waarbij elke MediaWiki speciale variabele wordt vervangen. Voor meer informatie, zie Manual:Sql.php .

Dit werkt voor alle database backends. De prompt voor de commando-regel gebruikers bevat echter niet alle functies zoals die met uw database wordt meegeleverd.

De mysql commando-regel gebruiken

## Database instellingen
$wgDBtype           = "mysql";
$wgDBserver         = "localhost";
$wgDBname           = "your-database-name";
$wgDBuser           = "your-database-username";  // Default: root
$wgDBpassword       = "your-password";

In LocalSettings.php staat uw MySQL wachtwoord en gebruikersnaam, bijvoorbeeld:

Met SSH, log in met deze gegevens:

mysql -u $wgDBuser -p --database=$wgDBname

Vervang $wgDBuser en $wgDBname met hun LocalSettings.php waarden. Er wordt dan om uw wachtwoord $wgDBpassword gevraagd en vervolgens ziet u de prompt mysql>.

Database abstractie laag

MediaWiki gebruikt de bibliotheek Rdbms als de database abstractie laag. Het is niet de bedoeling dat ontwikkelaars direct de low-level database-functies aanroepen, zoals mysql_query.

Elke connectie wordt weergegeven met Wikimedia\Rdbms\IDatabase waar queries kunnen worden uitgevoerd. Er kan een connectie worden gemaakt door het aanroepen van getPrimaryDatabase() of getReplicaDatabase() (afhankelijk van gebruikswijze) op een instantie van IConnectionProvider met voorkeur met inbegrip van afhankelijkheden, of verkregen worden met MediaWikiServices via service DBLoadBalancerFactory. De functie wfGetDB() wordt afgebouwd en dient niet in nieuwe code te worden gebruikt.

Voor het ophalen van de databaseconnecties wordt meestal met één parameter aangeroepen, of getReplicaDatabase() bij queries om te lezen of getPrimaryDatabase() bij queries voor het schrijven (en voor write-informing read queries). Het verschil tussen primary en replica is belangrijk in een omgeving met meerdere databases, zoals Wikimedia. Lees de onderstaande sectie Wrapper functies om de interactie met de IDatabase objecten te zien.

Voorbeeld lezen:

MediaWiki-versie:

≥ 1.42

use MediaWiki\MediaWikiServices;

$dbProvider = MediaWikiServices::getInstance()->getConnectionProvider();
$dbr = $dbProvider->getReplicaDatabase();

$res = $dbr->newSelectQueryBuilder()
  ->select( /* ... */ ) // see docs
  ->fetchResultSet();

foreach ( $res as $row ) {
	print $row->foo;
}

Voorbeeld schrijven:

MediaWiki-versie:

≥ 1.41

$dbw = $dbProvider->getPrimaryDatabase();
$dbw->newInsertQueryBuilder()
    ->insertInto( /* ... */ ) // see docs
    ->caller( __METHOD__ )->execute();

We gebruiken de conventie $dbr voor connecties om te lezen (replica) en $dbw voor connecties om te schrijven (primary). Ook $dbProvider wordt gebruikt voor de IConnectionProvider-instantie

SelectQueryBuilder

MediaWiki-versie:

≥ 1.35

De class SelectQueryBuilder is de aanbevolen manier om leesquery's in nieuwe code te formuleren. In oudere code vindt u mogelijk select() en gerelateerde methoden van de class Database die rechtstreeks worden gebruikt. De querybouwer biedt een moderne "vloeiende" interface, waarbij methoden worden geketend totdat de methode fetch wordt aangeroepen, zonder dat tussenliggende variabele toewijzingen nodig zijn. Bijvoorbeeld:

$dbr = $dbProvider->getReplicaDatabase(); /** For MW < 1.40, use older method to get db connection **/
$res = $dbr->newSelectQueryBuilder()
	->select( [ 'cat_title', 'cat_pages' ] )
	->from( 'category' )
	->where( 'cat_pages > 0' )
	->orderBy( 'cat_title', SelectQueryBuilder::SORT_ASC )
	->caller( __METHOD__ )->fetchResultSet();

Zoals hieronder beschreven, introduceert MediaWiki 1.42 een hulpmethode, expr(), waarmee u het veld, de operator en de waarde als een expressie kunt inpakken. Met behulp hiervan kan de where-clausule in het bovenstaande voorbeeld worden geschreven als:

->where( $dbr->expr( 'cat_pages', '>', 0 ) )

Dit voorbeeld komt overeen met de volgende SQL:

SELECT cat_title, cat_pages FROM category WHERE cat_pages > 0 ORDER BY cat_title ASC

Een JOIN is natuurlijk ook mogelijk:

$dbr = $dbProvider->getReplicaDatabase();
$res = $dbr->newSelectQueryBuilder()
	->select( 'wl_user' )
	->from( 'watchlist' )
	->join( 'user_properties', /* alias: */ null, 'wl_user=up_user' )
	->where( [
		'wl_user != 1',
		'wl_namespace' => '0',
		'wl_title' => 'Main_page',
		'up_property' => 'enotifwatchlistpages',
	] )
	->caller( __METHOD__ )->fetchResultSet();

Dit voorbeeld komt overeen met de query:

SELECT wl_user
FROM `watchlist`
INNER JOIN `user_properties` ON ((wl_user=up_user))
WHERE (wl_user != 1)
AND wl_namespace = '0'
AND wl_title = 'Main_page'
AND up_property = 'enotifwatchlistpages'

U kunt telkens een rij van het resultaat lezen met een foreach loop. Elke rij is een object. Bijvoorbeeld:

$dbr = $dbProvider->getReplicaDatabase();
$res = $dbr->newSelectQueryBuilder()
	->select( [ 'cat_title', 'cat_pages' ] )
	->from( 'category' )
	->where( 'cat_pages > 0' )
	->orderBy( 'cat_title', SelectQueryBuilder::SORT_ASC )
	->caller( __METHOD__ )->fetchResultSet();      

foreach ( $res as $row ) {
	print 'Category ' . $row->cat_title . ' contains ' . $row->cat_pages . " entries.\n";
}

Er zijn ook functies om een rij te lezen, een enkel veld uit meerdere rijen of een enkel veld uit een rij:

// Equivalent of:
//     $rows = fetchResultSet();
//     $row = $rows[0];
$pageRow = $dbr->newSelectQueryBuilder()
	->select( [ 'page_id', 'page_namespace', 'page_title' ] )
	->from( 'page' )
	->orderBy( 'page_touched', SelectQueryBuilder::SORT_DESC )
	->caller( __METHOD__ )->fetchRow();

// Equivalent of:
//     $rows = fetchResultSet();
//     $ids = array_map( fn( $row ) => $row->page_id, $rows );
$pageIds = $dbr->newSelectQueryBuilder()
	->select( 'page_id' )
	->from( 'page' )
	->where( [
		'page_namespace' => 1,
	] )
	->caller( __METHOD__ )->fetchFieldValues();

// Equivalent of:
//     $rows = fetchResultSet();
//     $id = $row[0]->page_id;
$pageId = $dbr->newSelectQueryBuilder()
	->select( 'page_id' )
	->from( 'page' )
	->where( [
		'page_namespace' => 1,
		'page_title' => 'Main_page',
	] )
	->caller( __METHOD__ )->fetchField();

In deze voorbeelden is $pageRow een object rij zoals in het bovenstaande voorbeeld van foreach, $pageIds is een array met pagina-ID's en $pageId is een enkele page-id.

Hoewel u tables() kunt gebruiken om meerdere tabellen toe te voegen, wordt het sterk aanbevolen om in plaats daarvan join() of leftJoin() te gebruiken. Alle aliassen voor extra tabellen moeten worden toegevoegd aan join() of leftJoin(), niet in tables().

UpdateQueryBuilder

MediaWiki-versie:

≥ 1.41

SQL-statements als UPDATE moeten worden gedaan met de UpdateQueryBuilder .

$dbw = $this->dbProvider->getPrimaryDatabase();
$dbw->newUpdateQueryBuilder()
	->update( 'user' )
	->set( [ 'user_password' => $newHash->toString() ] )
	->where( [
		'user_id' => $oldRow->user_id,
		'user_password' => $oldRow->user_password,
	] )
	->caller( $fname )->execute();

InsertQueryBuilder

MediaWiki-versie:

≥ 1.41

SQL statements als INSERT moeten worden gedaan met de InsertQueryBuilder.

$dbw = $this->dbProvider->getPrimaryDatabase();
$targetRow = [
	'bt_address' => $targetAddress,
	'bt_user' => $targetUserId,
	/* etc */
];
$dbw->newInsertQueryBuilder()
	->insertInto( 'block_target' )
	->row( $targetRow )
	->caller( __METHOD__ )->execute();
$id = $dbw->insertId();

DeleteQueryBuilder

MediaWiki-versie:

≥ 1.41

SQL statements als DELETE moeten worden gedaan met de DeleteQueryBuilder.

$dbw = $this->dbProvider->getPrimaryDatabase();
$dbw->newDeleteQueryBuilder()
	->deleteFrom( 'block' )
	->where( [ 'bl_id' => $ids ] )
	->caller( __METHOD__ )->execute();
$numDeleted = $dbw->affectedRows();

ReplaceQueryBuilder

MediaWiki-versie:

≥ 1.41

SQL statements als REPLACE moeten worden gedaan met de ReplaceQueryBuilder.

$dbw = $this->dbProvider->getPrimaryDatabase();
$dbw->newReplaceQueryBuilder()
	->replaceInto( 'querycache_info' )
	->row( [
		'qci_type' => 'activeusers',
		'qci_timestamp' => $dbw->timestamp( $asOfTimestamp ),
	] )
	->uniqueIndexFields( [ 'qci_type' ] )
	->caller( __METHOD__ )->execute();

UnionQueryBuilder

MediaWiki-versie:

≥ 1.41

SQL statements als UNION moeten worden gedaan met de UnionQueryBuilder.

$dbr = $this->dbProvider->getReplicaDatabase();
$ids = $dbr->newUnionQueryBuilder()
	->add( $db->newSelectQueryBuilder()
		->select( 'bt_id' )
		->from( 'block_target' )
		->where( [ 'bt_address' => $addresses ] )
	)
	->add( $db->newSelectQueryBuilder()
		->select( 'bt_id' )
		->from( 'block_target' )
		->join( 'user', null, 'user_id=bt_user' )
		->where( [ 'user_name' => $userNames ] )
	)
	->caller( __METHOD__ )
	->fetchFieldValues();

Een query die voor meerdere rijen gevolgen heeft

Als u meerdere rijen moet invoeren of bijwerken, probeer ze samen te groeperen in een batchquery voor de efficiëntie. Het is belangrijk om de tabeldeclaratie (bijv. update(), insertInto(), enz.), caller(), execute() buiten de lus te houden.

Alles wat verband houdt met het maken of bijwerken van rijen kan in de lus worden gedaan (bijv. row()).

$queryBuilder = $this->getDb()->newInsertQueryBuilder()
	->insertInto( 'ores_classification' )
	->caller( __METHOD__ );
foreach ( [ 0, 1, 2, 3 ] as $id ) {
	$predicted = $classId === $id;
	$queryBuilder->row( [
		'oresc_model' => $this->ensureOresModel( 'draftquality' ),
		'oresc_class' => $id,
    	'oresc_probability' => $predicted ? 0.7 : 0.1,
		'oresc_is_predicted' => $predicted ? 1 : 0,
		'oresc_rev' => $revId,
	] );
}
$queryBuilder->execute();

Iteratie over veel resultaten

Als u een query SELECT met veel resultaten doet en het resultaat in batches moet herhalen, gebruik dan de class BatchRowIterator.

$queryBuilder = $dbw->newSelectQueryBuilder()
	->select( $key )
	->from( $table )
	->where( $where )
	->caller( __METHOD__ );

$iterator = new BatchRowIterator( $dbw, $queryBuilder, $key, $batchSize );
foreach ( $iterator as $n => $batch ) {
	$firstRow = reset( $batch );
	$lastRow = end( $batch );
	$dbw->newUpdateQueryBuilder()
		->table( $table )
		->set( $set )
		->where( $where )
		->andWhere( $dbw->expr( $key, '>=', $firstRow->$key ) )
		->andWhere( $dbw->expr( $key, '<=', $lastRow->$key ) )
		->caller( __METHOD__ )
		->execute();
	$this->waitForReplication();
}

Helpers

De volgende hulpmethoden moeten worden gebruikt wanneer dit van toepassing is, omdat ze SQL-query's maken die compatibel zijn met alle ondersteunde databasetypen en ze helpen bij automatisch escappen.

`$dbr->expr()`

MediaWiki-versie:

≥ 1.42

Het moet worden gebruikt in WHERE-statements wanneer er iets wordt vergeleken dat niet een eenvoudige vergelijking is. Bijvoorbeeld, $dbr->expr( 'ptrp_page_id', '>', $start ).

Deze methode kan worden gekoppeld met ->and() en ->or(). Bijvoorbeeld, $db->expr( 'ptrp_page_id', '=', null )->or( 'ptrpt_page_id', '=', null )

`$dbr->andExpr()` / `$dbr->orExpr()`

MediaWiki-versie:

≥ 1.43

Introduced in Manual:IReadableDatabase.php to supersede makeList() with LIST_AND / LIST_OR. Example:

Before MW 1.43

$dbr->makeList([
	'foo1' => 'bar1',
	'foo2' => 'bar2',
], LIST_OR );

MW1.43+

$dbr->orExpr([
	'foo1' => 'bar1',
	'foo2' => 'bar2',
]);

`$dbr->timestamp()`

Verschillende database-engines formateren MediaWiki-tijdstempels anders. Gebruik dit om compatibiliteit te garanderen. Voorbeeld: $dbr->expr( 'ptrp_reviewed_updated', '>', $dbr->timestamp( $time ) )

RawSQLExpression

MediaWiki-versie:

≥ 1.42

Moet worden gebruikt in WHERE-statements wanneer u niet iets in SQL wil escapen. Als u een veld vergelijkt met een gebruikerswaarde (komt veel vaker voor), gebruikt u in plaats daarvan $dbr->expr(). RawSQLExpression doet geen escape, het mag dus nooit worden gebruikt met gebruikersinvoer. Spaarzaam gebruiken! Voorbeeld: $dbr->expr( new RawSQLExpression( 'rc_timestamp < fp_pending_since' ) )

RawSQLValue

MediaWiki-versie:

≥ 1.43

Moet worden gebruikt in WHERE-statements wanneer u niet iets in SQL wil escapen. Als u een veld vergelijkt met een gebruikerswaarde (komt veel vaker voor), gebruikt u in plaats daarvan $dbr->expr(). RawSQLValue doet geen escape, het mag dus nooit worden gebruikt met gebruikersinvoer. Spaarzaam gebruiken! Voorbeeld: $dbr->expr( 'fp_pending_since', '>', new RawSQLValue( $fieldName ) )

Compatibiliteit met meerdere database-engines

Het juiste gebruik van de querybuilder zorgt voor compatibiliteit met alle ondersteunde database-engines (MariaDB, MySQL, SQLite, PostgreSQL). Om problemen met de database-engine te voorkomen, worden ontwikkelaars aangemoedigd om PHPUnit-integratie-tests te schrijven die databasecode uitvoeren en ervoor te zorgen dat continue integratie alle ondersteunde engines controleert. Naast het voorzichtig zijn met het gebruik van $db->expr() en $db->timestamp(), zoals vermeld in de bovenstaande secties, zijn hier enkele aanvullende dingen waar u op moet letten bij het schrijven van multi-engine compatibele code met de query-builder:

Soms moet u misschien integers en booleans casten naar stringtypes als ze in BLOB's gaan^[1]
Sommige engines handhaven NOT NULL strikt, dus standaardwaarden moeten worden aangegeven^[2]
Soms moet u misschien ->order_by() toevoegen, omdat de standaard sortering voor elke engine anders kan zijn^[3]^[4]

Patches op MediaWiki core laten testen uitvoeren voor alle engines tijdens de verzendfase. Extensies en skins laten niet alle engines testen. Ontwikkelaars kunnen commentaar geven in gerrit zoals check php of check experimental gebruiken om continue integratiecontroles uit te voeren op alle database-engines eerder dan de transmit stap, of om controles uit te voeren voor extensies en skins.

Wrapper functies en ruwe queries

Oudere MediaWiki-code kan wrapperfuncties gebruiken zoals $dbr->select(), $dbw->insert(). Zeer oude MediaWiki-code kan $dbw->query() gebruiken. Er zijn ook enkele functies die pure SQL genereren zoals addQuotes(), buildLike(), makeList(). Geen van beide wordt nu als een goede aanpak beschouwd en dient te worden veranderd in de hierboven genoemde query builders.

Wrapper-functies zijn superieur aan $dbw->query(), omdat deze zorgen voor het gebruik van prefixen en voor de foutafhandeling. Indien u echt uw eigen SQL wil maken, lees dan de documentatie over tableName(), addQuotes(). U heeft ze beide nodig. Als u niet goed addQuotes() gebruikt dan kunnen er ernstige veiligheidsproblemen ontstaan op uw wiki.

Een andere reden om de high level methoden te gebruiken dan om zelf uw query te maken is de zekerheid dat uw code ook op andere database-types werkt. Op dit moment wordt MySQL/MariaDB het beste ondersteund. Er is ook goede ondersteuning voor SQLite in de core van MediaWiki, dat werkt wel trager dan MySQL en MariaDB. Het wordt ook minder goed ondersteund in extensies. Er is ook ondersteuning voor PostgreSQL, maar dat is wat minder stabiel dan voor MySQL.

In deze paragraaf worden de beschikbare wrapper functies opgesomd. Een meer gedetailleerde beschrijving met ook de parameters van de wrapper functies staat in de class Database documenten. Bekijk vooral Database::select voor een uitleg over de parameters $table, $vars, $conds, $fname, $options, $join_conds, deze worden door veel andere wrapper functies gebruikt.

De parameters $table, $vars, $conds, $fname, $options en $join_conds moeten NIET null of false zijn (dat werkte tot release 1.35) maar een lege string '' of een leeg array [].

function select( $table, $vars, $conds, .. );
function selectField( $table, $var, $cond, .. );
function selectRow( $table, $vars, $conds, .. );
function insert( $table, $a, .. );
function insertSelect( $destTable, $srcTable, $varMap, $conds, .. );
function update( $table, $values, $conds, .. );
function delete( $table, $conds, .. );
function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds, .. );

Comfort functies

MediaWiki-versie:

≤ 1.30

Om compatibel te zijn met PostgreSQL worden id's bepaald met gebruik van nextSequenceValue() en insertId(). De parameter voor nextSequenceValue() kan opgehaald worden met CREATE SEQUENCE statement in maintenance/postgres/tables.sql en heeft het formaat x_y_seq, waar x staat voor de tabelnaam (bijv. page) en y voor de primary key (bijv. page_id), bijv. page_page_id_seq. Bijvoorbeeld:

$id = $dbw->nextSequenceValue( 'page_page_id_seq' );
$dbw->insert( 'page', [ 'page_id' => $id ] );
$id = $dbw->insertId();

Er zijn andere mogelijk nuttige functies zoals affectedRows(), numRows() beschreven in Handboek Database functies.

Basis query optimalisatie

MediaWiki ontwikkelaars die DB query's moeten schrijven, moeten verstand hebben van databases en de prestatie kwesties die deze met zich meebrengen. Patches die onacceptabele langzame functies bevatten worden niet geaccepteerd. Queries zonder index zijn in het algemeen niet welkom in MediaWiki, met uitzondering in Speciale Pagina's die afgeleid zijn van QueryPage . Het is voor nieuwe ontwikkelaars een bekende valkuil om code te maken die SQL-queries doen over een groot aantal records. Iets als COUNT(*) is O(N), het tellen van rijen in een tabel is als het tellen van zandkorrels op het strand.

Backwards compatibiliteit

Vaak zijn er door het wijzigen van het ontwerp van een database, verschillende toegangen nodig om zeker te zijn van compatibiliteit met oudere versies. Dit kan worden aangeven met bijvoorbeeld de globale variabele MW_VERSION (of globale variabele $wgVersion voor MediaWiki 1.39):

/**
* backward compatibility
* @since 1.31.15
* @since 1.35.3
* define( 'DB_PRIMARY', ILoadBalancer::DB_PRIMARY )
* DB_PRIMARY remains undefined in MediaWiki before v1.31.15/v1.35.3
* @since 1.28.0
* define( 'DB_REPLICA', ILoadBalancer::DB_REPLICA )
* DB_REPLICA remains undefined in MediaWiki before v1.28
*/
defined('DB_PRIMARY') or define('DB_PRIMARY', DB_MASTER);
defined('DB_REPLICA') or define('DB_REPLICA', DB_SLAVE);

$res = WrapperClass::getQueryFoo();

class WrapperClass {

	public static function getReadingConnect() {
		return wfGetDB( DB_REPLICA );
	}

	public static function getWritingConnect() {
		return wfGetDB( DB_PRIMARY );
	}

	public static function getQueryFoo() {
		global $wgVersion;

		$param = '';
		if ( version_compare( $wgVersion, '1.33', '<' ) ) {
			$param = self::getQueryInfoFooBefore_v1_33();
		} else {
			$param = self::getQueryInfoFoo();
		}

		return = $dbw->select(
			$param['tables'],
			$param['fields'],
			$param['conds'],
			__METHOD__,
			$param['options'],
			$param['join_conds'] );
	}

	private static function getQueryInfoFoo() {
		return [
			'tables' => [
				't1' => 'table1',
				't2' => 'table2',
				't3' => 'table3'
			],
			'fields' => [
				'field_name1' => 't1.field1',
				'field_name2' => 't2.field2',
				…
			],
			'conds' => [ …
			],
			'join_conds' => [
				't2' => [
					'INNER JOIN',
					'field_name1 = field_name2'
				],
				't3' => [
					'LEFT JOIN',
					…
				]
			],
			'options' => [ …
			]
		];
	}

	private static function getQueryInfoFooBefore_v1_33() {
		return [
			'tables' => [
				't1' => 'table1',
				't2' => 'table2',
				't3' => 'table3_before'
			],
			'fields' => [
				'field_name1' => 't1.field1',
				'field_name2' => 't2.field2_before',
				…
			],
			'conds' => [ …
			],
			'join_conds' => [
				't2' => [
					'INNER JOIN',
					…
				],
				't3' => [
					'LEFT JOIN',
					…
				]
			],
			'options' => [ …
			]
		];
	}
}

MediaWiki-versie:

≥ 1.35

	public static function getQueryFoo() {

		$param = '';
		if ( version_compare( MW_VERSION, '1.39', '<' ) ) {
			$param = self::getQueryInfoFooBefore_v1_39();
		} else {
			$param = self::getQueryInfoFoo();
		}

		return = $dbw->select(
			$param['tables'],
			$param['fields'],
			$param['conds'],
			__METHOD__,
			$param['options'],
			$param['join_conds'] );
	}

Replicatie

Grote installaties van MediaWiki zoals Wikipedia, gebruiken een groot aantal replica MySQL servers die writes op de primary MySQL-server ook doen. Het is van belang dat u begrijpt welke complexiteit deze keuze heeft voor grote gedistribueerde systemen, als u code voor Wikipedia wilt schrijven.

Het is vaak zo dat het beste algoritme voor een bepaalde taak afhangt of er wel of geen 'replication' wordt gebruikt. Vanwege onze gerichtheid op Wikipedia gebruiken we meestal gewoon de replication vriendelijke versie, maar als u het wilt dan kunt u wfGetLB()->getServerCount() > 1 gebruiken om te zien of er replication wordt gebruikt.

Achterlopen

Achterlopen (lag) komt voornamelijk voor als er grote write queries naar de primary server worden gestuurd. Op de primary server worden writes parallel uitgevoerd, maar op een replica server is dat serieel. De primary server schrijft de query naar de binlog bij de commit van de transactie. De replica's zien de actie op de binlog en voeren dan direct de query uit. Zij kunnen leesopdrachten afhandelen terwijl ze de schrijfactie doen, maar lezen dit niet meer van de binlog. Als de schrijfopdracht wat langer duurt dan lopen de replica's dus tijdens die opdracht wat achter.

Het achterlopen is afhankelijk van het aantal leesopdrachten. De load-balancer van MediaWiki zal geen leesopdrachten meer sturen naar een replica als er meer dan 5 seconden vertraging is. Als de load-ratio verkeerd wordt ingesteld of als er teveel load is, dan de vertraging van een replica blijvend rond de 5 seconden blijven schommelen.

In Wikimedia-productie hebben databases semi-synchronisatie ingeschakeld, wat betekent dat een wijziging niet in de primaire wordt doorgevoerd, tenzij deze in ten minste de helft van de replica's wordt uitgevoerd. Dit betekent dat veel belasting ertoe kan leiden dat alle bewerkingen en andere schrijfbewerkingen worden geweigerd, waarbij een fout wordt geretourneerd aan de gebruiker. Hierdoor kunnen de replica's hun achterstand inlopen.

Voor de invoering van deze mechanismes, hadden de replica's regelmatig een vertraging van een paar minuten, dat maakte het beoordelen van recente bewerkingen moeilijk.

In aanvulling hierop probeert MediaWiki te waarborgen dat de gebruiker gebeurtenissen op de wiki in chronologische volgorde ziet. Een paar seconden vertraging is toelaatbaar, als de gebruiker maar een logische voortgang ziet van het verwerken van wijzigingen. Dit wordt gedaan door de primaire binlog positie in de sessie te bewaren en dan bij de start van elke request te wachten op de replica zodat die bij is op die positie voordat er van gelezen wordt van de replica. Als het wachten te lang duurt, dan wordt het lezen toegestaan, maar het verzoek wordt beschouwd als in de "lagged replica mode". Deze vertraagde replica mode kan worden gecontroleerd met de aanroep van LoadBalancer::getLaggedReplicaMode(). Het enige praktische gevolg op dit moment is het tonen van een waarschuwing in de voettekst van de pagina.

In de shell kan een gebruiker de replicatie achterstand controleren met getLagTimes.php ; andere gebruiker hebben hiervoor de siteinfo API.

Databases hebben vaak ook een eigen monitoring systeem, zie bijvoorbeeld wikitech:MariaDB#Replication lag (Wikimedia) en wikitech:Help:Toolforge/Database#Identifying lag (Wikimedia Cloud VPS).

Voorkomen van het achterlopen

Om het achterlopen te beperken zouden queries die veel records tegelijk schrijven opgesplitst kunnen worden, in het algemeen om er een per keer te doen. Multi-row INSERT ... SELECT queries leggen het grootste beslag en dienen helemaal voorkomen te worden. Het is beter om eerst de select te doen en dan de insert.

Ook kleine schrijfopdrachten kunnen het achterlopen veroorzaken als ze snel gedaan worden en de replication het niet kan bijhouden. Dit gebeurt meestal in een onderhoudsscript. Om dat te voorkomen zou u om de paar honderd schrijfopdrachten een aanroep van Maintenance::waitForReplication() moeten doen. Bij de meeste scripts is dat aantal iets dat in te stellen is:

class MyMaintenanceScript extends Maintenance {
    public function __construct() {
        // ...
        $this->setBatchSize( 100 );
    }

    public function execute() {
        $limit = $this->getBatchSize();
        while ( true ) {
             // ...selecteer tot $limit rijen om te schrijven, stop eerder met de lus als alle rijen geschreven zijn....
             // ...schrijven...
             $this->waitForReplication();
        }
    }
}

Werken met achterlopen

Ondanks onze inzet is het niet praktisch om een omgeving met een lager achterloop te garanderen. Bij replicatie is de achterstand meestal minder dan een seconde, maar het kan soms oplopen tot 5 seconden. Voor de schaalbaarheid is het belangrijk om de load op de primaire server laag te houden, dus het sturen van alle queries naar de primaire server is niet de oplossing. Als het belangrijk is om de actuele gegevens te hebben, dan wordt de volgende aanpak geadviseerd:

Doe een snelle query op de primaire server voor het volgnummer of tijdstempel
Voer de volledige query uit op de replica en controleer of het overeenkomt met de gegevens van de primaire server
Als het verschilt, doe dan de volledige query op de primaire server

Om het overstromen van de primaire server elke keer met het achterlopen van de replica's te voorkomen, moet deze aanpak maar beperkt gebruikt worden. In de meeste gevallen moet u lezen van de replica en de gebruiker maar laten omgaan met de vertraging.

Locken inhoud

Vanwege de hoge schrijfsnelheid op Wikipedia (en enkele andere wiki's), dienen MediaWiki ontwikkelaars erg voorzichtig te zijn met de structuur van hun schrijven om te voorkomen dat er langdurige locks optreden. Standaard start MediaWiki een transactie bij de eerste query, de commit komt dan voordat de uitvoer wordt verzonden. De lock duurt dan vanaf het uitvoeren van de query tot de commit. De lock-tijd kan dus verkort worden door zoveel mogelijk verwerking te doen voordat de updates gedaan worden. Update operaties waar geen database toegang voor nodig is kunnen uitgesteld worden tot na de commit door het toevoegen van een object aan $wgPostCommitUpdateList of aan Database::onTransactionPreCommitOrIdle.

Vaak is deze aanpak niet goed genoeg, dan wordt het nodig om om kleine groepen queries elk een eigen transactie te geven. De te gebruiken syntaxis is:

$factory = \MediaWiki\MediaWikiServices::getInstance()->getDBLoadBalancerFactory();
$factory->beginMasterChanges(__METHOD__);
/* Doe de queries */
$factory->commitMasterChanges(__METHOD__);

Gebruik van 'locking reads' (bijv. met de clause FOR UPDATE) wordt niet aangeraden. De implementatie daarvan in InnoDB is erg matig, het veroorzaakt regelmatig deadlocks. Het is ook verbazend gemakkelijk om de wiki met dit locken van de inhoud kreupel te maken.

Combineer, in plaats van 'locking reads', uw controle op het bestaan van iets in uw write queries, door het gebruiken van de geschikte conditie in uw WHERE clause of een UPDATE, of door het gebruiken van unieke indexen in combinatie met INSERT IGNORE. Gebruik dan de 'affected row count' om te zien of de query goed gelukt is.

Database schema

Vergeet de indexen niet bij het maken van een database, zaken werken op een test wiki met een beperkt aantal pagina's altijd goed maar kunnen in een productie-omgeving erg traag werken. Details hierboven.

Naamconventies: Manual:Coding conventions/Database .

Zie ook

Manual:Hooks/LoadExtensionSchemaUpdates – Als een extensie aangeeft dat de database gewijzigd moet worden bij een update van MediaWiki, dan kan dat gedaan worden met deze hook. Gebruikers kunnen dan hun wiki updaten door het uitvoeren van update.php .
Database transactions

[1] rrit:c/mediawiki/extensions/PageTriage/+/982906

[2] rrit:c/mediawiki/extensions/PageTriage/+/982900

[3] rrit:c/mediawiki/core/+/1134704

[4] rrit:c/mediawiki/extensions/ORES/+/815366

[1]

[2]

[3]

[4]

Handboek:Database toegang

Database lay-out

Inloggen in MySQL

Gebruik van sql.php

De mysql commando-regel gebruiken

Database abstractie laag

SelectQueryBuilder

UpdateQueryBuilder

InsertQueryBuilder

DeleteQueryBuilder

ReplaceQueryBuilder

UnionQueryBuilder

Een query die voor meerdere rijen gevolgen heeft

Iteratie over veel resultaten

Helpers

$dbr->expr()

$dbr->andExpr() / $dbr->orExpr()

$dbr->timestamp()

RawSQLExpression

RawSQLValue

Compatibiliteit met meerdere database-engines

Wrapper functies en ruwe queries

Comfort functies

Basis query optimalisatie

Backwards compatibiliteit

Replicatie

Achterlopen

Voorkomen van het achterlopen

Werken met achterlopen

Locken inhoud

Database schema

Zie ook

`$dbr->expr()`

`$dbr->andExpr()` / `$dbr->orExpr()`

`$dbr->timestamp()`