DB layer 2.0 migration docs

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

This article defines all the changes that need to be performed in Moodle 1.9 code in order to make it run properly under new Moodle 2.0 DB layer. Changes below are grouped into 3 main blocks (xmldb, ddl and dml) to have them organised.

Although the order of changes showed in this page isn't mandatory at all, it can be interesting to follow it in the migration progress to be able to understand and learn a bit more about all them. That way, you'll end knowing not only what to change but how and why those changes are required.

Also, it's recommended to read the whole XMLDB, DDL and DML documentation and APIs before start with the migration. That will allow you to have some initial knowledge about the new architecture.

Each change will be as simple as possible, representing one easy rule to follow to adapt the code. When anything become too much complex to be explained as one simple rule, it will contain one link to the examples page.

For any problem in the migration of code, it's recommended to use the Databases forum at moodle.org. Also if you find any bug in the process, pleas report it in the Moodle Tracker, that way developers will be able to fix it ASAP.

And finally, feel free to complete/fix the list below with the changes you find in the progress of migration, for sure that will help a lot of developers. Thanks!

XMLDB changes

Some comments

• When changing DB structures it's highly recommended to use the XMLDB Editor (Admin->Misc->XMLDB Editor). It uses to be a safe way to edit install.xml files and to get correct PHP code to be used in upgrade.php scripts.
• If you have some doubts about the list of changes below, it's highly recommended to take a look to some code in core modules, blocks... whatever you need. They are a good reference.

The changes

• No changes required in install.xml files at all (that's good news!).
• All upgrade.php scripts, within the main xxxx_upgrade function must have $DB (uppercase) in the globals declaration (along with others if needed). Example (from glossary module):

   function xmldb_glossary_upgrade($oldversion=0) {
   
       global $CFG, $THEME, $DB;

• All upgrade.php scripts, must NOT have $db (lowercase) in the globals declaration. Delete it if present.
• After the global declaration in the points above, this line must be present (we'll need it later):

   $dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes

• All XMLDBTable instances in your upgrade code must be replaced by xmldb_table (parameters are the same, no change with them required)
• All XMLDBField instances in your upgrade code must be replaced by xmldb_field (no change in parameters)
• All XMLDBIndex instances in your upgrade code must be replaced by xmldb_index (no change in parameters)
• All XMLDBKey instances in your upgrade code must be replaced by xmldb_key (no change in parameters)
• All the addFieldInfo() methods must be replaced by add_field() (no change in parameters)
• All the addIndexInfo() methods must be replaced by add_key() (no change in parameters)
• All the addKeyInfo() methods must be replaced by add_key() (no change in parameters)
• All the setAttributes() methods must be replaced by set_attributes() (no change in parameters)
• All the DDL functions used in upgrade code, must be transformed as detailed below (it's only about to add "$dbman->" - without the quotes - before each function call). No changes in parameters are required. :
  • table_exists ==> $dbman->table_exists
  • field_exists ==> $dbman->field_exists
  • index_exists ==> $dbman->index_exists
  • find_index_name ==> $dbman->find_index_name
  • find_check_constraint_name ==> $dbman->find_check_constraint_name
  • check_constraint_exists ==> $dbman->check_constraint_exists
  • find_sequence_name ==> $dbman->find_sequence_name
  • create_table ==> $dbman->create_table
  • drop_table ==> $dbman->drop_table
  • rename_table ==> $dbman->rename_table
  • add_field ==> $dbman->add_field
  • drop_field ==> $dbman->drop field
  • rename_field ==> $dbman->rename_field
  • change_field_type ==> $dbman->change_field_type
  • change_field_precision => $dbman->change_field_precision
  • change_field_unsigned ==> $dbman->change_field_unsigned
  • change_field_notnull ==> $dbman->change_field_notnull
  • change_field_enum ==> $dbman->change_field_enum
  • change_field_default ==> $dbman->change_field_default
  • add_key ==> $dbman->add_key
  • drop_key ==> $dbman->drop_key
  • add_index ==> $dbman->add_index
  • drop_index ==> $dbman->drop_index