Database Schema Support (Plugins)

To support plugins that require database changes for their operation, InsightCloudSec has extended the system migration process to include those types of plugins. If your InsightCloudSec deployment does not have plugins or does not have plugins that require custom database changes, you can skip over this section.

Plugin Changes

To support this new capability, any plugin that is to be included in this system database migration will need to include a subdirectory (folder) called db_migrations. That folder needs to include a file, migrations.txt, that contains a list of SQL files\ names, one file per line. Each of the files, containing SQL statements relative to the plugins in question, needs to exist in the same db_migrations folder. If a plugin does not require any schema changes, simply don't create the db_migrations folder, and the system database upgrade will skip that plugin.

If an existing plugin has a directory called db_migrations but does not have the migrations.txt file, the database upgrade process may raise an error (see Troubleshooting for Plugin Developers below).

New Database Upgrade Behavior

During the database upgrade process, after the internal database schemas have been successfully upgraded, the system will now inspect each plugin in the plugins folder, to look for the new database migration directory. The database upgrade process will run before any plugin code is loaded/run. This means that any database schema a plugin needs will already have been applied to the system as it is run.

Troubleshooting For Plugin Developers

Below are the three most common error conditions.

1. A Plugin has a db_migrations folder, but no migrations.txt file:
   • If your InsightCloudSec is running in a standard supported environment, the upgrade process will be automatically handled by the Scheduler. In this environment, there will be an error logged by the scheduler, but the InsightCloudSec application’s database schema will complete and the InsightCloudSec Application will function normally w/o error.
   • If you are running in a Development environment and chose not to let the scheduler perform the schema change, but utilize the divvycloud.py upgrade-database command. The InsightCloudSec core application schema will be upgraded, but as the process attempts to perform the plugin-specific upgrade, it will display an error indicating that for the specific plugin, the migrations.txt file was not found. At that point the upgrade process will stop and any additional plugin migrations will not be attempted.
2. A file specified in the Plugin's migrations.txt is missing:
   • The upgrade process will log and print an error indicating that for the plugin, the file name referenced in the migrations.txt is missing. The migration process stops.
   • Attempts to start any of the InsightCloudSec Applications will result in a message that a db schema upgrade is required.
3. A file specified in the Plugin's migrations.txt has a SQL error:
   • The upgrade process will log and print the SQL error, the plugin, and the file where the error occurred. The migration process stops.
   • Attempts to start any of the InsightCloudSec Applications will result in a message that a db schema upgrade is required.