Latest revision as of 14:01, 5 October 2023

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.
Create a new update patch file in /application/helpers/update/updates with the format Update_###.php where "###" is the next number in the sequence of existing patch files. This file should contain a class of the same name (Update_###) which extends DatabaseUpdateBase and has a public function "up()" which contains the DB patch code. See existing patch files for examples.
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'.

@@ Line 10: / Line 10: @@
 {{Alert| 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 /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.
+* Create a new update patch file in /application/helpers/update/updates with the format Update_###.php where "###" is the next number in the sequence of existing patch files. This file should contain a class of the same name (Update_###) which extends DatabaseUpdateBase and has a public function "up()" which contains the DB patch code. See existing patch files for examples.
 *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 <code>phpunit --group db</code> in the root folder, to make sure you didn't introduce any syntactic errors.

Database versioning: Difference between revisions

From LimeSurvey Manual