User Tools

  • Logged in as: anonymous (anonymous)
  • Log Out

Site Tools


mantisbt:db_schema

This is an old revision of the document!


MantisBT Database Schema

This pages documents the MantisBT schema definition script (admin/schema.php), and explains how to modify it.

Introduction

The schema is defined as a numbered list of updates (aka upgrade steps), stored as an array. Each step consists of two elements:

  1. A function to generate SQL statements. Available operations are described in Upgrade Functions section below
  2. An array of parameters to be passed to the function.

The integrity of the schema relies on strict ordering of this array.

  • ONLY ADD NEW CHANGES TO THE END OF THE TABLE!!!
    Always specify the schema step (array key), for documentation purposes
  • NEVER SKIP AN INDEX IN THE SEQUENCE!!!

Release markers are placed right AFTER the last schema step that is included in the corresponding release:

$g_upgrade[173] = array( 'AddColumnSQL', array( db_get_table( 'bug_file' ), "
	user_id					I		UNSIGNED NOTNULL DEFAULT '0' " ) );
 
# Release marker: 1.2.0rc1

$g_upgrade[174] = array( 'DropColumnSQL', array( db_get_table( 'custom_field' ), 'advanced' ) );

In the above example, steps up to 173 are part of 1.2.0rc1, while 174 and onwards are included in 1.2.0rc2.

Upgrade functions

This section documents available upgrade operations:

  • Data dictionary operations from ADOdb library; one of:
    • Tables: CreateTableSQL, ChangeTableSQL, RenameTableSQL, DropTableSQL,
    • Columns: AddColumnSQL, AlterColumnSQL, RenameColumnSQL, DropColumnSQL,
    • Indexes: CreateIndexSQL, DropIndexSQL
  • InsertData
  • UpdateFunction: local function to perform arbitrary changes
  • null: no-op upgrade step

CreateTableSQL

ChangeTableSQL

RenameTableSQL

DropTableSQL

AddColumnSQL

AlterColumnSQL

RenameColumnSQL

DropColumnSQL

CreateIndexSQL

DropIndexSQL

InsertData

Local function to add data to a table.

UpdateFunction

UpdateFunction allows arbitrary PHP code to be executed via a function, which must be defined in install_helper_functions_api.php with an install_ prefix.

Example 1: Simple function without arguments

  • schema.php
    $g_upgrade[186] = array( 'UpdateFunction', 'update_history_long_custom_fields' );
  • install_helper_functions_api.php
    function install_update_history_long_custom_fields() {
    	# [... function code ...]
    }

Example 2: function with arguments

  • schema.php (actual code was reformatted to improve readability)
    $g_upgrade[107] = array( 'UpdateFunction', 'date_migrate', array(
    	db_get_table( 'bug_file' ),
    	'id',
    	'date_added',
    	'date_added_int'
    ) );
  • install_helper_functions_api.php
    /**
     * Migrate the legacy date format.
     * @param array $p_data Array: [0] = tablename, [1] id column, [2] = old column, [3] = new column.
     * @return integer
     */
    function install_date_migrate( array $p_data ) {
    	# [... function code ...]
    }

null

No-op upgrade step.

This is used to skip the step while maintaining the upgrade sequence, e.g. when an operation becomes obsolete or doesn't apply for specific cases.

mantisbt/db_schema.1451929175.txt.gz · Last modified: 2016/01/04 12:39 by dregad