Handboek:Database toegang

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

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 maintenance/tables.sql, maar vanaf MediaWiki 1.35 wordt dit beetje bij beetje verplaatst naar maintenance/tables.json, als onderdeel van het initiatief 'Abstract Schema'. Dat betekent dat maintenance/tables.json is omgezet naar maintenance/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 <script>LocalSettings.php</script> 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 Rdbms bibliotheek 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.40
 
$dbw = $dbProvider->getPrimaryDatabase();
$dbw->insert( /* ... */ ); // see docs

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();
$res = $dbr->newSelectQueryBuilder()
	->select( [ 'cat_title', 'cat_pages' ] )
	->from( 'category' )
	->where( $dbr->expr( 'cat_pages', '>', 0 ) )
	->orderBy( 'cat_title', SelectQueryBuilder::SORT_ASC )
	->caller( __METHOD__ )->fetchResultSet();

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( [
		$dbr->expr( '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( $dbr->expr( '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.

Wrapper functies

We bieden aan een query() functie an voor pure SQL, maar de wrapper functies moeten worden gebruikt voor zaken als select() en insert(). 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() en 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, dat werkt wel trager dan MySQL en MariaDB. 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 opgehaald 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

Zie ook: Database optimization

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',
					…
				],
				'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:

  1. Doe een snelle query op de primaire server voor het volgnummer of tijdstempel
  2. Voer de volledige query uit op de replica en controleer of het overeenkomt met de gegevens van de primaire server
  3. 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 .

SQLite compatibiliteit

U kunt de basis compatibiliteit controleren met:

Of, als u een patch wil testen, beide:

  • php SqliteMaintenance.php --check-syntax tables.sql - MediaWiki 1.36+
  • php sqlite.php --check-syntax tables.sql - MediaWiki 1.35 en ouder
    • Omdat database patches ook het bestand tables.sql updaten, zou u voor deze ook de versie van tables.sql vooraf de wijziging moeten controleren (het bestand met de volledige database definitie). Anders kunt u een fout krijgen als u een index verwijderd (drop), omdat die al niet meer bestaat in tables.sql, u had die net verwijderd.

Hierboven wordt aangenomen dat u in het $IP/maintenance/ staat, anders moet u bij het bestand ook het pad aangeven. Voor een patch van een extensie, gebruik de tegenhanger voor die extensie van deze bestanden.

Zie ook

Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:Database_access/nl&oldid=6460963"