MediaWiki

Příručka:Přístup k databázi

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

Tento článek poskytuje přehled přístupu k databázi a obecných problémů s databází na MediaWiki.

Při kódování v MediaWiki budete obvykle přistupovat k databázi pouze prostřednictvím funkcí MediaWiki určených k tomuto účelu.

Schéma databáze

Pro aktuální informace o tom, jak vypadá databáze MediaWiki, jako například popis tabulek a jejich obsah, prostudujte Příručka:Schéma databáze . Historicky bylo dokumentováno v MediaWiki, též na maintenance/tables.sql, ale od verze 1.35 se postupně přešlo na maintenance/tables.json, což je součást iniciativy Abstract Schema. To znamená, že schéma ze maintenance/tables.json zapíše do souboru maintenance/tables-generated.sql maintenance script , což umožňuje na základě jedné konfigurace generovat databázová schémata, pro různé typy databází.

Přihlášení do MySQL

Použití sql.php

MediaWiki má pro práci s databází údržbářský skript, který může přistupovat k databázi. Ten se spouští z adresáře maintenance: 

php run.php sql

Po jeho spuštění můžete zadávat dotazy na databázi. Další možnost je předat název souboru, který si bude spouštět MediaWiki, přičemž si MW podle potřeby nahradí všechny použité speciální proměnné. Pro další informace se podívejte na Manual:Sql.php .

To bude fungovat pro všechny databázové backendy. Výzva však není tak plnohodnotná jako klienti příkazového řádku dodávaní s vaší databází.

Použití klienta příkazového řádku mysql

## Nastavení databáze
$wgDBtype           = "mysql";
$wgDBserver         = "localhost";
$wgDBname           = "your-database-name";
$wgDBuser           = "your-database-username";  // Default: root
$wgDBpassword       = "your-password";

V LocalSettings.php najdete heslo a uživatelské jméno vaší wiki pro MySQL, například:

Do SSH se přihlaste zadáním následujícího: 

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

Nahraďte $wgDBuser a $wgDBname jejich hodnotami LocalSettings.php. Poté budete vyzváni k zadání hesla $wgDBpassword a poté se zobrazí výzva mysql>.

Vrstva abstrakce databáze

MediaWiki používá knihovnu Rdbms jako svou abstrakční vrstvu databáze. Vývojáři nesmí přímo volat nízkoúrovňové databázové funkce, jako je mysql_query.

Každé připojení je reprezentováno Wikimedia\Rdbms\IDatabase, ze kterého lze provádět dotazy. Připojení lze získat voláním getPrimaryDatabase() nebo getReplicaDatabase() (v závislosti na případu použití) na instanci IConnectionProvider, nejlépe závislost-injected, nebo získat od MediaWikiServices prostřednictvím služby DBLoadBalancerFactory. Funkce wfGetDB() se postupně vyřazuje a neměla by se používat v novém kódu.

Chcete-li získat připojení k databázi, můžete zavolat buď getReplicaDatabase() pro čtecí dotazy nebo getPrimaryDatabase() pro zapisovací dotazy a čtecí dotazy informující o zápisu. Rozdíl mezi primární a replikou je důležitý v prostředí s více databázemi, jako je Wikimedie. Informace o tom, jak pracovat s objekty IDatabase, naleznete níže v části Funkce obálky.

Přečtěte si příklad dotazu:

Verze MediaWiki:
≥ 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;
}

Napište příklad dotazu:

Verze MediaWiki:
≥ 1.40
 
$dbw = $dbProvider->getPrimaryDatabase();
$dbw->insert( /* ... */ ); // see docs

Používáme konvenci $dbr pro čitelná připojení (replika) a $dbw pro zapisovatelná připojení (primární). Také $dbProvider se používá pro instanci IConnectionProvider

SelectQueryBuilder

Verze MediaWiki:
≥ 1.35

Třída SelectQueryBuilder je preferovaný způsob, jak formulovat čtené dotazy v novém kódu. Ve starším kódu můžete najít select() a související metody třídy Database používané přímo. Tvůrce dotazů poskytuje moderní "plynulé" rozhraní, kde jsou metody zřetězené, dokud není vyvolána metoda načtení, bez nutnosti přiřazování zprostředkujících proměnných. Například: 

$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();

Tento příklad odpovídá následujícímu SQL: 

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

JOINs jsou také možné. Například: 

$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();

Tento příklad odpovídá dotazu: 

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'

K jednotlivým řádkům výsledku můžete přistupovat pomocí smyčky foreach. Každý řádek je reprezentován jako objekt. Například: 

$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";
}

Existují také praktické funkce pro načtení jednoho řádku, jednoho pole z několika řádků nebo jednoho pole z jednoho řádku: 

// 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();

V těchto příkladech je $pageRow objekt řádku jako ve výše uvedeném příkladu foreach, $pageIds je pole ID stránek a $pageId je jedno ID stránky.

Funkce obálky

Poskytujeme funkci query() pro nezpracovaný SQL, ale místo toho je třeba použít funkce wrapper jako select() a insert(). Mohou se za určitých okolností postarat například o předvolby tabulek a escaping. Pokud opravdu potřebujete vytvořit svůj vlastní SQL, přečtěte si dokumentaci k tableName() a addQuotes(). Ob̟ě budete potřebovat. Nezapomeňte, že pokud nebudete správně používat addQuotes(), můžete do své wiki vložit závažné bezpečnostní díry.

Dalším důležitým důvodem pro použití metod na vysoké úrovni, namísto vytváření vlastních dotazů, je zajištění správného fungování kódu bez ohledu na typ databáze. V současné době je nejlepší podpora pro MySQL/MariaDB. Existuje také dobrá podpora pro SQLite, je však mnohem pomalejší než MySQL nebo MariaDB. Existuje podpora pro PostgreSQL, ale není tak stabilní jako MySQL.

V následující části jsou uvedeny dostupné funkce obálky. Podrobný popis parametrů funkcí obálky (wrapper) najdete v dokumentech třídy Database's. Zejména viz Database::select pro vysvětlení $table, $vars, $conds, $fname, $options, $join_conds parametrů, které používá mnoho dalších funkcí wrapperu.

Parametry $table, $vars, $conds, $fname, $options a $join_conds NESMÍ být null nebo false (to fungovalo do REL 1.35), ale prázdný řetězec '' nebo prázdné pole [].
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, .. );

Pohodlné funkce

Verze MediaWiki:
≤ 1.30

Pro kompatibilitu s PostgreSQL jsou idy vložení získány pomocí nextSequenceValue() a insertId(). Parametr pro nextSequenceValue() lze získat z příkazu CREATE SEQUENCE v maintenance/postgres/tables.sql a vždy odpovídá formátu x_y_seq, kde x je název tabulky (např. page) a y je primární klíč (např. page_id), např. page_page_id_seq. Například: 

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

Pro některé další užitečné funkce, např. affectedRows(), numRows() atd., viz Příručka:Database.php#Functions.

Základní optimalizace dotazu

Viz též: Database optimization

Vývojáři MediaWiki, kteří potřebují psát dotazy na DB, by měli mít určité znalosti o databázích a s nimi spojenými problémy s výkonem. Opravy obsahující nepřijatelně pomalé funkce nebudou přijaty. Neindexované dotazy nejsou na MediaWiki obecně vítány, s výjimkou zvláštních stránek odvozených z QueryPage. Pro nové vývojáře je obvyklé předkládat kód obsahující dotazy SQL, které zkoumají obrovské množství řádků. Pamatujte, že COUNT(*) je O(N), počítání řádků v tabulce je jako počítání fazolí v kbelíku.

Zpětná kompatibilita

Kvůli změnám návrhu DB jsou často nutné různé přístupy k DB pro zajištění zpětné kompatibility. To lze zpracovat například globální konstantou MW_VERSION (nebo globální proměnnou $wgVersion před 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' => [ …
			]
		];
	}
}
Verze MediaWiki:
≥ 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'] );
	}

Replikace

Velké instalace MediaWiki, jako je Wikipedie, používají velkou sadu replik MySQL serverů replikujících zápisy provedené na primární MySQL server. Pokud chcete psát kód určený pro Wikipedii, je důležité porozumět složitosti spojené s velkými distribuovanými systémy.

Často se stává, že nejlepší algoritmus pro daný úkol závisí na tom, zda se používá replikace. Kvůli našemu neustálému centrování na Wikipedii často používáme pouze verzi vhodnou pro replikaci. Ale pokud chcete, můžete použít wfGetLB()->getServerCount() > 1 a zkontrolovat, zda se replikace používá.

Prodleva

K nadměrnému zpoždění (lag) dochází především při odesílání velkých dotazů na zápis na primární server. Zápisy na primárním serveru jsou prováděny paralelně, ale jsou prováděny sériově, když jsou replikovány do replik. Primární server zapíše dotaz do binlogu, když je transakce potvrzena. Repliky se dotazují na binlog a začnou provádět dotaz, jakmile se objeví. Mohou číst služby, zatímco provádějí dotaz na zápis, ale nebudou číst nic víc z binlogu a nebudou tedy provádět žádné další zápisy. To znamená, že pokud dotaz na zápis běží dlouhou dobu, repliky budou za primárním serverem zaostávat po dobu, kterou trvá dokončení dotazu na zápis.

Zpoždění může být umocněno vysokou zátěží čtením. Nástroj pro vyrovnávání zátěže MediaWiki přestane odesílat čtení do repliky, když se zpozdí o více než 5 sekund. Pokud jsou poměry zatížení nastaveny nesprávně nebo pokud je zatížení obecně příliš velké, může to vést k tomu, že se replika trvale pohybuje se zpožděním 5 sekund.

V produkci Wikimedie mají databáze povolenou semi-synchronizaci, což znamená, že změna nebude potvrzena primárně, pokud nebude potvrzena alespoň v polovině replik. To znamená, že velké zatížení může vést k odmítnutí všech úprav a dalších operací zápisu s chybou vrácenou uživateli. To dává replikám šanci vše dohnat.

Než jsme měli tento mechanismus, repliky se pravidelně zpožďovaly o několik minut, což ztěžovalo kontrolu posledních úprav.

Kromě toho se MediaWiki snaží zajistit, aby uživatel viděl události na wiki v chronologickém pořadí. Několik sekund zpoždění může být tolerováno, pokud uživatel uvidí konzistentní obrázek z následných požadavků. To se provádí uložením pozice primárního binlogu v relaci a poté na začátku každého požadavku čekáním, až replika dožene tuto pozici, než z ní provedete jakékoli čtení. Pokud toto čekání vyprší, čtení je přesto povoleno, ale požadavek je považován, že je v "režimu zpožděné repliky". Režim opožděné repliky lze zkontrolovat voláním LoadBalancer::getLaggedReplicaMode(). Jediným praktickým důsledkem v současné době je varování zobrazené v zápatí stránky.

Uživatelé prostředí Shell mohou zkontrolovat zpoždění replikace pomocí getLagTimes.php . Ostatní uživatelé mohou zkontrolovat pomocí siteinfo API.

Databáze mají často také své vlastní monitorovací systémy, viz například wikitech:MariaDB#Replication lag (Wikimedie) a wikitech:Help:Toolforge/Database#Identification lag (Wikimedie Cloud VPS).

Vyhýbání se zpoždění

Chcete-li se vyhnout nadměrnému zpoždění, měly by se dotazy, které píší velké množství řádků, rozdělit. Obvykle psát vždy jeden řádek najednou. Víceřádkové VLOŽIT (INSERT) ... VYBRAT (SELECT) dotazy jsou nejhorší pachatelé a je třeba se jim úplně vyhnout. Místo toho proveďte nejprve výběr a poté vložení.

I malé zápisy mohou způsobit zpoždění, pokud jsou prováděny velmi vysokou rychlostí a replikace není schopna držet krok. Nejčastěji se to stává ve skriptech údržby. Abyste tomu zabránili, měli byste po každých několika stovkách zápisů volat Maintenance::waitForReplication(). Většina skriptů umožňuje konfigurovat přesné číslo: 

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

    public function execute() {
        $limit = $this->getBatchSize();
        while ( true ) {
             // ...vyberte až $limit řádků k zápisu, přerušte smyčku, pokud nejsou žádné další řádky...
             // ...dělat zápisy...
             $this->waitForReplication();
        }
    }
}

Práce se zpožděním

I přes naše nejlepší úsilí není praktické zaručit prostředí s malým zpožděním. Zpoždění replikace bude obvykle kratší než jedna sekunda, ale někdy může být až 5 sekund. Pro škálovatelnost je velmi důležité udržovat nízké zatížení primárního serveru, takže pouhé odesílání všech vašich dotazů na primární server není řešením. Pokud tedy skutečně potřebujete aktuální data, doporučuje se následující postup:

  1. Proveďte rychlý dotaz na primární server na pořadové číslo nebo časové razítko
  2. Spusťte celý dotaz na repliku a zkontrolujte, zda odpovídá datům, které jste získali z primárního serveru
  3. Pokud ne, spusťte celý dotaz na primárním serveru

Aby nedošlo k zaplavení primárního serveru pokaždé, když se repliky zpozdí, použití tohoto přístupu by mělo být omezeno na minimum. Ve většině případů byste měli pouze číst z repliky a nechat uživatele, aby se se zpožděním vypořádal.

Uzamčení sporu

Vzhledem k vysoké míře zápisu na Wikipedii (a některých dalších wikinách) musí být vývojáři MediaWiki velmi opatrní při strukturování svých zápisů, aby se vyhnuli dlouhodobým uzamčením. Ve výchozím nastavení MediaWiki otevře transakci při prvním dotazu a potvrdí ji před odesláním výstupu. Zámky se budou držet od doby, kdy je dotaz proveden, až po potvrzení. Takže můžete zkrátit dobu uzamčení provedením co nejvíce zpracování, než začnete psát dotazy. Operace aktualizace, které nevyžadují přístup k databázi, mohou být zpožděny až po odevzdání přidáním objektu do $wgPostCommitUpdateList nebo do Database::onTransactionPreCommitOrIdle.

Tento přístup často není dost dobrý a je nutné uzavřít malé skupiny dotazů do jejich vlastní transakce. Použijte následující syntaxi: 

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

Použití blokovacích čtení (např. klauzule FOR UPDATE) se nedoporučuje. Jsou špatně implementovány v InnoDB a způsobí pravidelné chyby zablokování. Je také překvapivě snadné ochromit wiki s tvrzením o uzamčení.

Namísto zamykání čtení zkombinujte své existenční kontroly do svých písemných dotazů pomocí vhodné podmínky v klauzuli WHERE UPDATE nebo pomocí jedinečných indexů v kombinaci s INSERT IGNORE. Potom pomocí ovlivněného počtu řádků zjistěte, zda byl dotaz úspěšný.

Schéma databáze

Při vytváření databází nezapomeňte na indexy, na zkušební wiki s desítkami stránek může vše hladce fungovat, ale skutečná wiki se zastaví. Podrobnosti najdete výše.

Konvence pojmenování najdete na stránce Příručka:Konvence pro psaní kódu/Database .

SQLite kompatibilita

Základní kontroly kompatibility můžete spustit pomocí:

Nebo, pokud potřebujete testovat aktualizaci, postupujte takto:

  • php SqliteMaintenance.php --check-syntax tables.sql - MediaWiki 1.36+
  • php sqlite.php --check-syntax tables.sql - MediaWiki 1.35 a starší
    • Protože záplaty DB aktualizují také soubor tables.sql, pro tento by jste měli předat předběžnou verzi tables.sql (soubor s úplnou definicí DB). Jinak můžete získat chybu, pokud přetáhnete index (protože již neexistuje v tables.sql, protože jste jej právě odstranili).

Výše uvedené předpokládá, že jste v $IP/maintenance/, jinak zadejte úplnou cestu k souboru. Pro opravy rozšíření použijte ekvivalent těchto přípon.

Související odkazy

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