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

SelectQueryBuilder

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

Jak je popsáno níže, MW 1.42 zavádí pomocnou metodu expr(), která umožňuje zabalit pole, operátor a hodnotu jako výraz. Pomocí toho lze klauzuli where ve výše uvedeném příkladu přepsat jako:

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

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

I když můžete použít tables() k přidání více tabulek, důrazně se doporučuje místo toho použít join() nebo leftJoin(). Jakékoli aliasy pro další tabulky musí být přidány k join() nebo leftJoin(), nikoli k tables().

UpdateQueryBuilder

Příkazy SQL UPDATE by měly být provedeny pomocí příkazu 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

Příkazy SQL INSERT by měly být provedeny pomocí nástroje 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

Příkazy SQL DELETE by měly být provedeny pomocí nástroje DeleteQueryBuilder.

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

ReplaceQueryBuilder

Příkazy SQL REPLACE by měly být provedeny pomocí 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

Příkazy SQL UNION by měly být provedeny pomocí nástroje 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();

Jeden dotaz ovlivňující více řádků

Pokud potřebujete vložit nebo aktualizovat více řádků, zkuste je seskupit do dávkového dotazu pro zvýšení efektivity. Je důležité ponechat deklaraci tabulky (např. update(), insertInto() atd.), caller(), execute() mimo smyčku.

Cokoli související s vytvářením nebo aktualizací řádků může jít do smyčky (např. 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();

Iterace přes velkou sadu výsledků

Pokud zadáte dotaz SELECT s velkým množstvím výsledků a potřebujete výsledek opakovat v dávkách, použijte třídu 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();
}

Pomocníci

Následující pomocné metody by měly být použity tam, kde je to vhodné, protože vytvářejí dotazy SQL, které jsou kompatibilní se všemi podporovanými typy databází, a pomáhají s automatickým escapováním.

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

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

Kompatibilita s více databázovými stroji

Správné použití nástroje pro tvorbu dotazů zajistí kompatibilitu se všemi podporovanými databázovými stroji (MariaDB, MySQL, SQLite, PostgreSQL). Aby se předešlo problémům s databázovým strojem, vývojářům se doporučuje napsat integrační testy PHPUnit, které provádějí databázový kód, a zajistit, aby nepřetržitá integrace kontrolovala všechny podporované stroje. Kromě toho, že musíte být opatrní při používání $db->expr() a $db->timestamp(), jak je uvedeno ve výše uvedených částech, je zde několik dalších věcí, na které byste si měli dát pozor při psaní kódu kompatibilního s více motory pomocí nástroje pro tvorbu dotazů:

• Někdy možná budete muset zadat přetypovaná celá čísla a booleany do řetězců, když přecházejí do objektů BLOB^[1]
• Některé zdroje striktně vynucují NOT NULL, takže bude nutné zadat výchozí hodnoty^[2]
• Někdy možná budete muset přidat ->order_by(), protože výchozí řazení pro každý zdroj může být jiné^[3][4]

Záplaty jádra MediaWiki probíhají během kroku odeslání testy se všemi zdroji. Rozšíření a vzhledy neprovádějí testy proti všem zdrojům. Vývojáři mohou zadávat komentáře Gerritu , jako jsou check php nebo check experimental, aby spustili průběžné kontroly integrace se všemi databázovými stroji dříve, než je krok odeslání, nebo aby spustili kontroly rozšíření a vzhledů.

Funkce obálky (wraper) a nezpracované dotazy

Starší kód MediaWiki může používat funkce wrapper jako $dbr->select(), $dbw->insert(). Velmi starý kód MediaWiki může používat $dbw->query(). Existují také některé funkce, které generují nezpracovaný SQL, například addQuotes(), buildLike(), makeList(). Žádný z nich se nyní nepovažuje za osvědčený postup a měl by být aktualizován na výše uvedené tvůrce dotazů.

Funkce wrapper (obalu) jsou lepší než $dbw->query(), protože se za vás za určitých okolností mohou postarat o věci, jako jsou předpony tabulek a escapování. Pokud opravdu potřebujete vytvořit vlastní SQL, přečtěte si prosím dokumentaci k tableName(), addQuotes(). Budete je potřebovat oba. Mějte prosím na paměti, že nesprávné použití addQuotes() může do vaší wiki vnést váž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časnosti je nejlepší podpora pro MySQL/MariaDB. V jádře MediaWiki je dobrá podpora pro SQLite, ale je mnohem pomalejší než MySQL nebo MariaDB a není dobře podporována v rozšířeních. 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.

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, .. );

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

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é INSERT (vložit) ... SELECT (vybrat) 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.