Manual:Database access/nl

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. Dit was eerder gedocumenteerd in, maar vanaf MediaWiki 1.35 wordt dit beetje bij beetje verplaatst naar  , als onderdeel van het initiatief 'Abstract Schema'. Dat betekent dat  is omgezet naar   door een, 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:

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.

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
In LocalSettings.php staat uw MySQL wachtwoord en gebruikersnaam, bijvoorbeeld:

Met SSH, log in met deze gegevens:

Vervang en  met hun   waarden. Er wordt dan om uw wachtwoord gevraagd en vervolgens ziet u de prompt.



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.

Elke connectie wordt weergegeven met  waar queries kunnen worden uitgevoerd. Er kan een connectie worden gemaakt door het aanroepen van   op een. instance, preferably dependency-injected, or obtained from MediaWikiServices, De functie  wordt afgebouwd en dient niet in nieuwe code te worden gebruikt.

wordt meestal met één parameter aangeroepen, of  bij queries om te lezen of   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  objecten te zien.

Voorbeeld lezen:

""

Voorbeeld schrijven:

""

We gebruiken de conventie voor connecties om te lezen (replica) en  voor connecties om te schrijven (primary).

SelectQueryBuilder
The class is the preferred way to formulate read queries in new code. In older code, you might find  and related methods of the Database class used directly. The query builder provides a modern "fluent" interface, where methods are chained until the fetch method is invoked, without intermediary variable assignments needed. For example:

Dit voorbeeld komt overeen met de volgende SQL:

Een JOIN is natuurlijk ook mogelijk:

Dit voorbeeld komt overeen met de query:

U kunt telkens een rij van het resultaat lezen met een foreach loop. Each row is represented as an object. Bijvoorbeeld:

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

In these examples, is an row object as in the  example above, is an array of page IDs, and is a single page ID.



Wrapper functies
We bieden aan een query functie an voor pure SQL, maar met wrapper functies als select en insert is het meestal gemakkelijker. 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 documenten. Bekijk vooral  voor een uitleg over de parameters ,  ,  ,  ,   en  , deze worden door veel andere wrapper functies gebruikt.



Wrapper functie: select
De functie select geeft de MediaWiki interface de mogelijkheid voor een SELECT-statement. De componenten van het SELECT-statement zijn de parameters van de functie select. Een voorbeeld

Dit voorbeeld komt overeen met de query

Een JOIN is natuurlijk ook mogelijk:

Dit voorbeeld komt overeen met de query

heeft een voorbeeld hoe een tabel alias in queries te gebruiken is.

Argumenten zijn of enkele waarden (zoals 'category' en 'cat_pages > 0') of arrays, indien meer dan een waarde wordt doorgegeven voor een argument positie (zoals ['cat_pages > 0', $myNextCond]). Als u als derde of vijfde argument een string opgeeft,dan moet u handmatig Database::addQuotes gebruiken op uw waarden als u de string aanmaakt, de wrapper doet dit niet voor u. De tabelnaam waarden (1e argument) of veldnamen (2e argument) moeten niet door de gebruiker kunnen worden opgegeven. De array constructie van $conds is een beetje beperkt, het kan alleen gelijkheid en   aan (bijv. WHERE key = 'value').

U kunt telkens een rij van het resultaat lezen met een foreach loop. Na het lezen van een row-object kunt u  gebruiken om een specifiek veld te lezen. Voorbeeld:

U krijgt nu een alfabetische lijst van categorieën met hoeveel records elke categorie heeft. Dat staat in de variabele $output. Als u de uitvoer als HTML wil doen, escape dan de waarden uit de database met.



Comfort functies
Om compatibel te zijn met PostgreSQL worden id's opgehaald met gebruik van nextSequenceValue en insertId. De parameter voor nextSequenceValue kan opgehaald worden met  statement in   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:

Er zijn andere mogelijk nuttige functies zoals, 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 :

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 om te begrijpen welke gevolgen deze keuze heeft 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 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 30 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 30 seconden blijven schommelen.

Als dat bij alle replica's gebeurt (volgens ), dan zal MediaWiki het schrijven op de database stoppen. Alle bewerkingen en andere aanpassingen in de databse worden geweigerd met een foutmelding naar de gebruiker. Hierdoor kunnen de replica's hun achterstand inlopen. Voor de invoering van dit mechanisme, 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 "lagged replica mode"kan worden gecontroleerd met een aanroep van. 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 ; andere gebruiker hebben hiervoor de API.

Databases hebben vaak ook een eigen monitoring systeem, zie bijvoorbeeld MariaDB (Wikimedia) en wikitech:Help:Toolforge/Database (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 call moeten doen. Bij de meeste scripts is dat aantal iets dat in te stellen is:



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 30 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.

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:

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:.



SQLite compatibiliteit
Bij het maken van de MySQL tabel definities of upgrade patches, is het belangrijk er aan te denken dat ook SQLite het MySQL schema gebruikt, dat betekent dat de definities op een speciale manier moeten worden gedaan:


 * Primaire keys moeten gedeclareerd worden in de table declaratie, maar normale keys dienen afzonderlijk te worden toegevoegd met CREATE INDEX:

Primaire keys die uit meerdere velden bestaan dienen te worden gemaakt in de table definitie:


 * Voeg niet meer dan een column toe per statement:


 * Stel de default in bij gebruik van een NOT NULL column:

U kunt de basis compatibiliteit controleren met:


 * - MediaWiki 1.36+
 * - MediaWiki 1.35 en ouder

Of, als u een patch wil testen, beide:


 * - MediaWiki 1.36+
 * - 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

 * &mdash; 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.