What is this article for
This article shows you how to make DB structure or data manipulations for new CB releases, customization project releases and sharing code via VCS.
Concept
For any code you commit that needs DB changes, you make an upgrade script (in certain directory). CB checks for new upgrade scripts and processes them on app init. So whenever a page involving CB code gets loaded, upgrades are processed automatically. So you commit or deploy code and on the involved remote installations, your scripts will handle all DB changes.
There is a directory containing PHP files that handle any necessary upgrade steps.
That directory is in appDir/helpers/updates for core code and customizationDir/updates for customization code
Each of these files use version numbers as file names (not necessarily CB release version numbers)
The application keeps track of the highest version number that got processed successfully.
During app initialisation, the app lists the files and loads new files in the right order
On Exceptions, the upgrade procedure halts, a notice appears on the CB dashboard and upgrade scripts won't run again until the situation is rectified
Behaviour on upgrade failures
Each script throws Exceptions in case anything does not go as intended
The Exception messages are logged in the app's log directory in the log file configbox_upgrade_errors
The failure will be remembered in the table #__configbox_system_vars: key failed_update_detected, value 1.
On subsequent page loads with CB code, the failed script (and any subsequent scripts) will NOT be tried again (until the failed_update_detected flag gets removed).
In the system vars table you will see the last successfully processed upgrade file (key latest_update_version, value is the name of the file)
In the CB dashboard you will see an entry at 'Critical Issues' notifying you that there was a failure in the upgrade procedure.
Update Scripts for customizations
There is an upgrade script system analogue to the system's upgrade script.
The location for customization upgrade scripts is in customizationDir/updates.
In table #__configbox_system_vars you find the last processed file in latest_customization_update_version.
On failures, the app logs errors in configbox_upgrade_errors and flags the failure in system vars key failed_update_detected (same as for core issues)
On failures, the app will not try upgrade scripts again on subsequent page loads until the situation is rectified.
Best Practices
Test upgrade scripts very thoroughly before committing to VCS or deployment - be aware of how much effort goes into rectifying a messy situation with upgrades
Before committing to VCS, see if colleagues already committed an upgrade script of the same name. DO NOT MERGE, but pick the next version number and check how both scripts will interplay
Make use of the method in ConfigboxUpdateHelpers. There are methods that check if tables, columns, keys and constraints exist already.