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

DDL changes

You are really lucky! If you've performed all the changes above, then all your DDL code has been upgraded successfully! Congrats!

DML changes

Some comments

• This is, with difference, the complexer part to migrate to have the code working under Moodle 2.0, not because of the complexity of the changes themselves (90% of them will be really easy), but because you'll need to triple-check everything works as expected after changes.

• Along the changes below, you'll find links to some examples that will try to make things easier. Anyway, if you are blocked at any point, please ask in forums or tracker (see links at the beginning of the page). Sure it has a good enough solution.

• Once more it's highly recommended to take a look to Moodle core code, searching for similar examples. Of course, new meaningful examples are welcome, and also any clarification in the list of changes below. Feel free to do it, this is a wiki!

• Finally, one more explanation: The changes below have been split into two sections. First one, (called "The golden changes") are modifications that must be applied to ALL the transformations defined in the second section ("The iron changes"). Sure you'll understand that after reading them (it's basically a matter of not repeating the golden ones within each iron one, just imagine they are everywhere).