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:	File(s):updaters.inc

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

Usage

Summary

1. Create your hook as indicated below. Each examples shows how to setup the hook function. However, if you have more than one schema update, you can put them in the same function.
2. Make sure the hook has access to any necessary sql files
3. Format the sql files correctly. See the ArticleFeedbackv5 SQL, and the corresponding hooks file, for some examples.
4. From the command line run the /maintenance/php update.php script to update your wiki’s database with your extension’s LoadExtensionSchemaUpdates hook
5. See the update.php manual for more information

>= 1.21

To modify an existing field

To modify an existing field, put:

$wgHooks['LoadExtensionSchemaUpdates'][] = 'fnMyHook';
function fnMyHook( DatabaseUpdater $updater ) {
	$updater->modifyExtensionField( 'tablename',
		'name_of_field',
		dirname( __FILE__ ) . '/patch_file_changing_field.sql' );
	return true;
}

SQLite does not support some features of ALTER TABLE, such as renaming columns. Thus, work-arounds are necessary. See handling of event_agent in Hooks.php and the accompanying files in the Echo extension.

>= 1.19

To add a new index

To add a new index, put:

$wgHooks['LoadExtensionSchemaUpdates'][] = 'fnMyHook';
function fnMyHook( DatabaseUpdater $updater ) {
	$updater->addExtensionIndex( 'tablename',
		'name_of_index',
		dirname( __FILE__ ) . '/index_name_of_index.sql' );
	return true;
}

>= 1.18

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->addExtensionTable( '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->addExtensionTable( 'tablename', dirname( __FILE__ ) . '/table.sql', true );
	$updater->addExtensionField( '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.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.

Note: Be very careful about the last member of the array being true. If you pass it an absolute path and nothing else, it will treat the path as relative to maintenance/archives and you will get all manner of errors.

<= 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.)
• DatabaseUpdater API documentation

Databases

Engines: MySQL – Oracle – PostgreSQL – SQLite Technical documentation: Schema (tables) – API property associations – Field prefixes – Primary key storage in other fields – Wikimedia extension tables Configuration: Settings – Sharing Development: Access – Optimization – Policy – Updater – Extension schema updates – Patch file Core tables: archive – category – categorylinks – change_tag – config – externallinks – filearchive – hitcounter – image – imagelinks – interwiki – iwlinks – ipblocks – job – l10n_cache – langlinks – logging – log_search – msg_resource – msg_resource_links – module_deps – objectcache – oldimage – page – pagelinks – page_props – page_restrictions – protected_titles – querycache – querycachetwo – querycache_info – recentchanges – redirect – revision – searchindex – sites – site_stats – tag_summary – templatelinks – text – transcache – updatelog – uploadstash – user – user_former_groups – user_groups – user_newtalk – user_properties – valid_tag – watchlist