This article covers how to define versions for your application and use the upgrader to run queries to upgrade between versions.
Coming from an IP.Board 3 app?
If you have an application which was originally developed for IP.Board 3.x, you will need to do the following steps. It doesn't matter if you installed a fresh 4.0 install or upgraded from 3.x.
- Create a new application as normal in the AdminCP
- If you installed a fresh 4.x rather than upgraded, manually create the database tables in your SQL database.
- Under the Database Schema tab in the Developer Center for your application, import the database tables. It is important that you use the "Import From Database" tab as the other options will assume these are new tables.
- Under the Versions tab, add all of your previous versions and the queries/code needed to upgrade between those steps - this is discussed in detail below. There is an option to upload your old versions.xml file to import them quickly, but you will need to specify the upgrade for each version queries/code manually.
How to define versions
In the Developer Center for your application, there is a Versions tab which shows all the versions there has been for your application. You do NOT need to add your current (unreleased) version in here, as the application system automatically works with an "upg_working" version which you will convert to a new version when you build your application for release. When you build and release your application (version 1.0.0), you will specify the version information when building, and the upg_working special version will be cleared and ready for your next version. This is because while you're working on your application, the system will automatically add any changes you make to the database schema to the upgrade routine for the latest version you have defined.
Database schema
The Database Schema tab is where you define all of the tables that your application uses. When your application is installed for the first time, all of the tables you have defined are created. As you make changes to the database schema, the system will automatically add the appropriate queries to make those changes to the upgrade routine for the latest version.
For example: say the current latest version of your application under the Versions tab is 1.0.0 and you have a table under the Database Schema tab. You release that version, and then start working on 1.0.1. Later, you add a column to the table under the Database Schema tab. When you release version 1.0.1, the system will automatically:
- For new installs: Just create the table as it is defined, including the added column
- For upgrades: Add the column
You do not need to manually add a statement to add the column to your upgrade routine.
Custom version queries and code
Though the Database Schema system is good at automatically handling tables owned by your application, you may find you need to run other queries (for example UPDATE queries or queries to add columns to tables not owned by your application). This is done under the Versions tab. Simply click the "+" icon for the version that the query need to be ran for (for example, if the query needs to be ran when upgrading to 1.0.1, you would click the "+" button for version 1.0.1 - typically, however, you will simply add this to the current version you are working on which will be denoted as "upg_working" in the Versions list).
You will notice there is a special "install" version which can be used to specify queries which should be ran on install. Since on a fresh install, those are the only queries that are ran, it may be necessary to add a query both to the "install" special version, and to the version you're working with. For example, if you're working on version 1.0.1 and decide you want to add a column to the core_groups table that you didn't add in version 1.0.1, you would need to specify the query in both the 1.0.1 version (for people upgrading from 1.0.0) and the special "install" version (for new installs).
If you need to run code which cannot be expressed as a single query, you can also define custom code. To do this, click the "</>" button for the version that needs custom code. This will write a file to the applications/<your_app>/setup/<version>/ directory with a skeleton to get you started. Simply open that file and follow the instructions within it to add your code. You can also do this for the special "install" version.
If you are coming from an IP.Board 3 app, you can manually create a queries.php file in the applications/<your_app>/setup/<version>/ directory with the contents of the old mysql_updates.php file (setting an $SQL variable). Because this functionality is only to accommodate legacy upgrades, the file must be created manually and cannot be done from the developer center. If there is only a small number of queries, it may be easier to rewrite them as a call to an \IPS\Db::i() method and add them using the normal method (clicking "+" for the version in the developer center).
Uninstall code
The system will automatically delete any tables defined by your application's Database Schema when uninstalling. If you need to run code in addition to this, you can do this with the Uninstall extension. In the Developer Center for your application, under the Extensions tab, click the "+" button for core > Uninstall and create an extension (the name of it isn't important). This will write a file to the applications/<your_app>/extensions/core/Uninstall/ directory with a skeleton to get you started. Simply open that file and follow the instructions within it to add your code.
Report Document