Manual:Hooks/LoadExtensionSchemaUpdates

From MediaWiki.org
Jump to: navigation, search
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[edit]

Summary[edit]

  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 php maintenance/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.25[edit]

Possibly the Hooks section of extensions.json should be used instead of $wgHooks as described below.

>= 1.21[edit]

To modify an existing field[edit]

To modify an existing field, put:

$wgHooks['LoadExtensionSchemaUpdates'][] = 'fnMyHook';
function fnMyHook( DatabaseUpdater $updater ) {
	$updater->modifyExtensionField( 'tablename',
		'name_of_field',
		__DIR__ . '/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[edit]

To add a new index[edit]

To add a new index, put:

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

>= 1.18[edit]

To add a new table[edit]

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',
		__DIR__ . '/table.sql' );
	return true;
}

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

To add a table and/or modify a field[edit]

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', __DIR__ . '/table.sql', true );
	$updater->addExtensionField( 'tablename', 'field_name', __DIR__ . '/table.patch.field_name.sql', true );
	$updater->addExtensionUpdate( array( 'modifyField', 'tablename', 'field_name',
		__DIR__ . '/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[edit]

To add a new table[edit]

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',
		__DIR__ . '/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[edit]

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',
		__DIR__ . '/table.sql', true ) );
	$updater->addExtensionUpdate( array( 'addField', 'tablename', 'field_name',
		__DIR__ . '/table.patch.field_name.sql', true ) );
	$updater->addExtensionUpdate( array( 'modifyField', 'tablename', 'field_name',
		__DIR__ . '/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[edit]

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',
			__DIR__ . '/table.sql'
		);
		$wgExtModifiedFields[] = array(
			'table',
			'field_name',
			__DIR__ . '/table.patch.field_name.sql'
		);
	} else {
		// >= 1.17 support
		$updater->addExtensionUpdate( array( 'addTable', 'tablename',
			__DIR__ . '/table.sql', true ) );
		$updater->addExtensionUpdate( array( 'modifyField', 'tablename', 'field_name',
			__DIR__ . '/table.patch.field_name.sql', true ) );
	}
	return true;
}

<= 1.16[edit]

To add a new table[edit]

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',
        __DIR__ . '/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[edit]

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',
        __DIR__ . '/table.sql' 
    );
    $wgExtNewFields[] = array(
        'table',
        'field_name',
        __DIR__ . '/table.patch.field_name.sql'
    );
    $wgExtModifiedFields[] = array(
        'table',
        'field_name',
        __DIR__ . '/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[edit]

$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[edit]

DatabasesManual:Database layout Engines: MySQL/MariaDBManual:MySQLOracleManual:OraclePostgreSQLManual:PostgreSQLSQLiteManual:SQLite
Technical documentation: SchemaManual:Database layout (tablesCategory:MediaWiki database tables) – API property associationsAPI:Database field and API property associationsField prefixesDatabase field prefixesPrimary key storage in other fieldsManual:Primary key storage in other fieldsWikimedia extension tablesCategory:Wikimedia extension database tables
Configuration: SettingsManual:Configuration_settings#Database_settingsSharingManual:Shared database
Development: AccessManual:Database accessOptimizationDatabase optimizationPolicyDevelopment policy#Database_patchesUpdaterManual:DatabaseUpdater.phpExtension schema updatesManual:Hooks/LoadExtensionSchemaUpdatesPatch fileManual:SQL patch file
Core tables: archivecategorycategorylinkschange_tagconfigexternallinksfilearchivehitcounterimageimagelinksinterwikiiwlinksipblocksjobl10n_cachelanglinkslogginglog_searchmsg_resourcemsg_resource_linksmodule_depsobjectcacheoldimagepagepagelinkspage_propspage_restrictionsprotected_titlesquerycachequerycachetwoquerycache_inforecentchangesredirectrevisionsearchindexsitessite_identifiers - site_statstag_summarytemplatelinkstexttranscacheupdateloguploadstashuseruser_former_groupsuser_groupsuser_newtalkuser_propertiestag_summaryvalid_tagwatchlist