Creating Migrations
After you have initially released a package that others have downloaded, you will need to create a separate migration every time you want to modify the database structure within an upgrade. You may do this via the command line with the command:
apex migration create <PACKAGE> [<ALIAS>]
This will create a directory at /etc/PACKAGE/Migrations/MIGRATION_NAME/ which contains three files:
| Filename | Description |
|---|---|
| migrate.php | The PHP class for the migration, explained in more detail below. |
| install.sql | Contains the SQL code that is executed upon the upgrade being installed. |
| remove.sql | Contains the SQL code that is executed upon the upgrade being rolled back |
Once you have done a commit and created a new release, when someone with the package installed on their system upgrades, the install() method within the migrate.php file will be automatically executed. By default, this method contains one line that executes all SQL code within the install.sql file against the database, but can contain any PHP code necessary.
In the same fashion, if and when the upgrade is rolled back, the remove() method within the migrate.php file will be executed. By default, this method contains one line that execute all SQL code within the remove.sql file, and should undo any changes to the database structure.
include_with_initial_install Property
You will notice the migrate.php file contains a $include_with_initial_install property, which by default is set to false. If set to true, this migration will be executed during initial installation of the package, and should only be done if you never modify the initial package migration install.sql file at /etc/PACKAGE/install.sql.
It's recommended to always leave this property at false, and instead upon creating a migration, also keep the initial package migration at /etc/PACKAGE/install.sql up to date with the latest database schema as well. This way, during package installation only one migration needs to be executed instead of many, lessening the chance of unforseen errors.