Introduction
This is the first time Gravity Forms has ever made such a major change to the database schema so we want to ensure that the upgrade process goes smoothly and successfully for all sites.
For the vast majority of sites, the upgrade process will pass largely unnoticed. However, there’s a lot going on in this upgrade so this document explains how it works and a few troubleshooting tips in case you get stuck.
What Do I Have to Do Before I Upgrade?
Backup your database
Really. Double check that your site backups actually restore correctly. If something goes wrong with the upgrade this is your best option for rolling back.
Update all your add-ons
Make sure that all your Gravity Forms Add-Ons are up to date. You should update all add-ons – including third-party add-ons – but the following official Add-Ons must be updated to these versions before updating to Gravity Forms 2.3.
- PayPal Add-On v2.9+
- Authorize.Net Add-On v2.4+
- Partial Entries Add-On v1.1+
- PayPal Payments Pro Add-On v2.3+
- Signature Add-On v3.4+
- User Registration Add-On v3.9+
- PayPal Pro Add-On v1.8+
If you have any of these add-ons and if any of them are older versions then update them. If you don’t see the automatic update in the plugins list then you can download the latest version from your downloads page.
If you don’t update all your add-ons then you risk either corrupting or losing data.
Update custom code
Check all your custom code for direct access to the database. If you see any references to the following legacy tables then you’ll need to update your code to use the new database tables. Here is a list of the legacy tables which should no longer be used:
- wp_rg_form
- wp_rg_form_meta
- wp_rg_form_view
- wp_rg_form_incomplete_submissions
- wp_rg_lead
- wp_rg_lead_detail
- wp_rg_lead_detail_long
- wp_rg_lead_meta
- wp_rg_lead_notes
See the guide to upgrading your code for further details.
Custom code which uses the API functions like GFAPI will not be affected. We don’t recommend accessing the database directly unless API functions do not fulfil the requirements.
Test the upgrade on a staging server
If you have access to a staging server then do the upgrade there first and test your site thoroughly in debug mode.
What Happens During the Upgrade?
- The new database schema is created with new tables for all the data. You can find out more about the new schema in this doc.
- The upgrade is queued. On multisite installations, upgrades are processed one by one, not simultaneously to avoid overloading the database server, so if you have a lot of sites please be patient. Form Submissions can still be received at this point.
- Once the migration starts, form submissions are blocked for the duration of the upgrade process. Attempts to submit forms will fail validation with the following message: “Your form was not submitted. Please try again in a few minutes.”
- The data is copied over to the new tables in batches of 2000 database rows.
- If the process is interrupted for example, due to a server restart during the migration, then a cron task will kick in to continue the process within 5 minutes.
- The database version is updated in the system report, the form submission block is released and Gravity Forms will now use the new tables.
Troubleshooting
The system status page still says that the upgrade is queued
Check in the system status report that background tasks are enabled on your installation. If they aren’t, follow the troubleshooting steps for background tasks.
The migration is going very slowly
It’s possible to speed up the process by increasing the batch size. However, beware, you may need to increase the PHP maximum execution time as well. For instance, a batch size of 100k would probably require a maximum execution time of around 5 minutes depending on your server resources. You can change the batch size by adding the following constant to your wp-config.php file:
define( 'GFORM_DB_MIGRATION_BATCH_SIZE', 50000 );
I’m seeing a PHP warning about accessing a table that is not valid
If an outdated add-on or some outdated custom code tries to access one of the legacy tables then the following PHP warning will be triggered and displayed and/or logged while in WP_DEBUG mode: “An outdated add-on or custom code is attempting to access the **** table which is not valid in this version of Gravity Forms. Update your add-ons and custom code to prevent loss of form data.”. See the guide to upgrading your code for further details.
Can I delete the deprecated tables once the upgrade is complete?
The upgrade process will not delete the deprecated tables. We recommend leaving them in place for a period of time to ensure they are no longer in use (such as by forgotten custom code or an old third party plugin). Once you are satisfied that is the case, you may delete these tables as needed to satisfy storage or data security concerns. As always, we recommend backing up (and testing your backup) before modifying or deleting large portions of data, and ensure that the security of your backups and the orphaned tables is in line with your established data security protocols as they may include personal customer data.
How can I prevent Gravity Forms from checking for outdated code?
Gravity Forms currently checks all database queries for outdated code. This is not optimal for performance so the check will be phased out and removed in a future version. However, if you’re confident that none of your code is using the old tables then you can use the following snippet to reduce the number of checks made.
add_action( 'plugins_loaded', function(){
remove_filter( 'query', array( 'GFForms', 'filter_query' ) );
} );
I’m panicking and I want to roll back
If the upgrade was successful and you’ve started to receive entries then it’s best not to roll back or you will lose the new entries. If you want to roll back then make sure you delete all the new database tables or restore your database from a backup so the migration process can begin cleanly again when you try the upgrade again. Open a support ticket if you have any doubts.