Database versioning

General

This page explains how to raise the DBVersion number and where to make changes in the source code. These instructions apply to v 2.0 or later.

You will typically need this if you are a LimeSurvey developer and want to introduce changes to the database. Please note: Avoid to introduce database changes on a stable version. This should only be done if it is necessary to fix a bug.

Steps to add a new DB version\changes to the existing database

  Never use models in the update function.

• Open \application\config\version.php and raise the $dbversion variable by one. For example if the current DBversion is 180 make it 181.
• Apply your change to installer/php/create-database.php and possibly ls default datasets.
• Open \application\helpers\update\updatedb_helper and in the end of the function db_upgrade_all() add a new conditional code block that does the necessary updates to the database scheme of the previous version. If you are using the proper functions the changes will be cross-DB compatible - check out how it is done in previous conditional blocks.
• If your update is a critical update then you need it to mark it as such. In the beginning of the function you will find a variable named $aCriticalDBVersions - add your version number to it if it is a critical database version update.
• Run the unit tests by typing phpunit --group db in the root folder, to make sure you didn't introduce any syntactic errors.

What is a critical database version update?

A critical DB version update is anything that

• transforms/modifies existing database data/tables in a way that it is not backward compatible to the previous database version

OR

• causes the survey taking not to work anymore if the dbversion is not applied yet.

OR

• the update would take an unusually long time to execute

Silent update

If there is no critical database version in the queue the database version update is run automatically once the administration page is visited (This feature will be availabe with DB version 259 and later.).

Notes

The current database version of the system is stored in table settings_global with stg_name 'DBVersion'.