Generic O/R mapper - database update

Please note, that this documentation is only valid up to release 1.16. As of 1.17 please refer to chapter database update.

As of release 1.11, an update tool for the Generic OR mapper is available. The tool can apply changes to the configuration files to an existing database.

In case, no automated update is desired, the GenericORMapperUpdate provides a mode, that displays the update statements rather to execute them directly. For huge databases, manual update should be preferred. This is especially true, if index or row updates are included!

The update tool includes some limitations. For some MySQL versions, columns with DEFAULT values are updated by the GORM update tool even if it is not necessary. This will be fixed in one of the next releases if possible at all. But this fact does not limit the functionality of the tool it self!

The following script shows, how the automated database update can be done with aim of the GenericORMapperUpdate tool. If you are searching for an example script, have a look at the /apps/modules/genericormapper/data/tools folder in the apf-codepack-* release. The file is named update.php and must be adapted to your application case:

PHP code
// include page controller require('../../apps/core/pagecontroller/pagecontroller.php'); // configure the registry if desired Registry::register('apf::core','Environment','{ENVIRONMENT}'); // include SetupMapper import('modules::genericormapper::data::tools','GenericORMapperUpdate'); // create update tool $update = new GenericORMapperUpdate(); // set Context (important for the configuration files!) $update->setContext('{CONTEXT}'); // adapt storage engine (default is MyISAM) //$update->setStorageEngine('MyISAM|INNODB'); // adapt data type of the indexed columns, that are used for object and relation ids //$update->setIndexColumnDataType('INT(5) UNSIGNED'); // update database layout $update->updateDatabase('{CONFIG_NAMESPACE}','{CONFIG_NAME_AFFIX}','{CONNECTION_NAME}'); // display statements only $update->updateDatabase('{CONFIG_NAMESPACE}','{CONFIG_NAME_AFFIX}','{CONNECTION_NAME}',false);

The place holders within the script have the following meaning:

  • {ENVIRONMENT}: This is the environment indicator of the application. It is used for addressing configuration files and must be adopted, if your environment is set to a value different than the default one. For details have a look at the Configuration chapter.
  • {CONTEXT}: This is the context of the application. It is used for addressing configuration files and must be adopted, if your environment is set to a value different than the default one. For details have a look at the Configuration chapter.
  • {CONFIG_NAMESPACE}: The namespace, that contains the mapper configuration files (see chapter 2.2).
  • {CONFIG_NAME_AFFIX}: The name affix for the configuration files (see chapter 2.1).
  • {CONNECTION_NAME}: The name of the database connection, that is used for the setup and for production use.

Further, it is important that the database, that should be initialized, must exist before setup is started. Additionally, the user connecting to the database must have CREATE TABLE, ALTER TABLE- and, if desired, ALTER INDEX-rights.Otherwise, the update could not be done. If no error is displayed during setup, the setup has finished successfully. The result can be checked by using phpMyAdmin or a MySQLAdmin tool.

Please note some basic rules:
  • Huge databases should not be updated automatically!
  • Applying column changes, custom indices are not attended and can thus be deleted during update!

Comments

Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.
There are no comments belonging to this article.