Database versioning

General

This page is a stump and tries to explain 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: Do not introduce database changes on a stable version.

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.
• Open each file in \installer\sql and add the necessary changes. Make sure the changes are consistent across all three files. Pay attention to the database specific field types (check out other tables for comparison/examples). For example: If you need to use field type 'text' then make it 'varchar(max)' in MSSQL. All SQL files have been removed in favour of one PHP file in installer/php/create-database.php. This needs to be updated.
• 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'.