Manual:Hooks/LoadExtensionSchemaUpdates

LoadExtensionSchemaUpdates
Available from version 1.10.1 Fired when MediaWiki is updated to allow extensions to update the database
Define function:	public static function onLoadExtensionSchemaUpdates( DatabaseUpdater $updater ) { ... }
Attach hook:	$wgHooks['LoadExtensionSchemaUpdates'][] = 'MyExtensionHooks::onLoadExtensionSchemaUpdates';
Called from:	updaters.inc

For more information about attaching hooks, see Manual:Hooks.
For examples of extensions using this hook, see Category:LoadExtensionSchemaUpdates extensions.

Usage

If your extension requires changes to the database when MediaWiki is updated, do it with this hook. Users can then update their wiki by running update.php

>= 1.17

To add a new table

To add a new table, in the main file for your extension:

# Schema updates for update.php
$wgHooks['LoadExtensionSchemaUpdates'][] = 'fnMyHook';
function fnMyHook( DatabaseUpdater $updater ) {
        $updater->addExtensionUpdate( array( 'addTable', 'tablename',
                dirname( __FILE__ ) . '/table.sql', true ) );
        return true;
}

The table.sql file should contain the necessary CREATE TABLE table definition.

To add a table and/or modify a field

If your extension has already added a table, but you need to modify a field in it for a new version, make the change in the sql file for the table (for people installing the extension after the change), then make a "patch" sql file to modify the field in the table (for people updating from an older version).

# Schema updates for update.php
$wgHooks['LoadExtensionSchemaUpdates'][] = 'fnMyHook';
function fnMyHook( DatabaseUpdater $updater ) {
        $updater->addExtensionUpdate( array( 'addTable', 'tablename',
                dirname( __FILE__ ) . '/table.sql', true ) );
        $updater->addExtensionUpdate( array( 'addField', 'tablename', 'field_name'
                dirname( __FILE__ ) . '/table.patch.field_name.sql', true ) );
        $updater->addExtensionUpdate( array( 'modifyField', 'tablename', 'field_name'
                dirname( __FILE__ ) . '/table.patch.field_name.sql', true ) );
        return true;
}

The table.patch.field_name.sql file should contain the necessary ALTER TABLE statement to update old versions of the schema.

<= 1.16 and >= 1.17 dual support

It is possible to provide support for both older versions of MediaWiki, and the current versions without much extra effort required

# Schema updates for update.php
$wgHooks['LoadExtensionSchemaUpdates'][] = 'fnMyHook';
function fnMyHook( $updater = null ) {
        if ( $updater === null ) {
                // <= 1.16 support
                global $wgExtNewTables, $wgExtModifiedFields;
                $wgExtNewTables[] = array(
                        'tablename',
                        dirname( __FILE__ ) . '/table.sql'
                );
                $wgExtModifiedFields[] = array(
                        'table',
                        'field_name',
                        dirname( __FILE__ ) . '/table.patch.field_name.sql'
                );
        } else {
                // >= 1.17 support
                $updater->addExtensionUpdate( array( 'addTable', 'tablename',
                        dirname( __FILE__ ) . '/table.sql', true ) );
                $updater->addExtensionUpdate( array( 'modifyField', 'tablename', 'field_name',
                        dirname( __FILE__ ) . '/table.patch.field_name.sql', true ) );
        }
        return true;
}

<= 1.16

To add a new table

To add a new table, in the main file for your extension:

# Schema updates for update.php
$wgHooks['LoadExtensionSchemaUpdates'][] = 'fnMyHook';
function fnMyHook() {
    global $wgExtNewTables;
    $wgExtNewTables[] = array(
        'tablename',
        dirname( __FILE__ ) . '/table.sql' );
    return true;
}

The table.sql file should contain the necessary CREATE TABLE table definition. For an example, see the FlaggedRevs extension.

To add a table and/or modify a field

If your extension has already added a table, but you need to modify a field in it for a new version, make the change in the sql file for the table (for people installing the extension after the change), then make a "patch" sql file to modify the field in the table (for people updating from an older version).

# Schema updates for update.php
$wgHooks['LoadExtensionSchemaUpdates'][] = 'fnMyHook';
function fnMyHook() {
    global $wgExtNewTables, $wgExtModifiedFields;
    $wgExtNewTables[] = array(
        'tablename',
        dirname( __FILE__ ) . '/table.sql' 
    );
    $wgExtNewFields[] = array(
        'table',
        'field_name',
        dirname( __FILE__ ) . '/table.patch.field_name.sql'
    );
    $wgExtModifiedFields[] = array(
        'table',
        'field_name',
        dirname( __FILE__ ) . '/table.patch.field_name.sql'
    );
    return true;
}

The table.patch.field_name.sql file should contain the necessary ALTER TABLE statement to update old versions of the schema.

All available options

$wgExtNewTables = array(); // table, dir
$wgExtNewFields = array(); // table, column, dir
$wgExtPGNewFields = array(); // table, column, column attributes; for PostgreSQL
$wgExtPGAlteredFields = array(); // table, column, new type, conversion method; for PostgreSQL
$wgExtNewIndexes = array(); // table, index, dir
$wgExtModifiedFields = array(); //table, index, dir

See also

• Manual:Hooks/ParserTestTables - This hook may also be necessary if your extension changes the behavior of the parser (parser functions, tag hooks, etc.)