Cleanup operations for data syncing

During the final steps of a data sync from a production environment to a non-production environment the custom CLI command wp vip data-cleanup datasync is run against the target environment.

The wp vip data-cleanup datasync command performs the following actions:

• Flush the site’s object cache.
• Trigger the vip_datasync_cleanup hook.
• Delete unnecessary transients. 
• Flush the site’s object cache again.

Custom cleanup operations

The vip_datasync_cleanup hook can be used for custom cleanup of application data (e.g., removing production API keys, performing brief data manipulation) after a data sync from a production environment to a non-production environment.

Because data syncs move downward from the production environment, the vip_datasync_cleanup code must be present in the branch that deploys to the target environment (e.g. develop or staging). It is recommended to add the custom code using the vip_datasync_cleanup hook to a file in the /client-mu-plugins directory.

In this example the vip_datasync_cleanup hook is used to delete the my_social_api_token option on the non-production environment:

/**
 * Run some custom cleanup after a migration.
 *
 * @uses vip_datasync_cleanup
 */
function my_action_vip_datasync_cleanup() {
    // Safety first: Do not execute this code in 
    // the production environment
    if ( 'production' === VIP_GO_APP_ENVIRONMENT ) {
        return;
    }
 
    delete_option( 'my_social_api_token' );
}
add_action( 'vip_datasync_cleanup', 'my_action_vip_datasync_cleanup' );

Using the vip_datasync_cleanup hook to output logs

The data sync operation, as well as the actions defined in the vip_datasync_cleanup hook, are performed on a transient job container rather than on an environment’s app or batch containers. Because of this, if the hook is configured to output logs they will not appear in the environment’s app or batch logs.

For log output from the vip_datasync_cleanup hook to appear in an environment’s batch logs, configure the hook to create a one-time cron event with post-sync tasks. The cron event will be picked up and run on a batch container. Any logs resulting from those tasks will be output to the environment’s batch logs in Runtime Logs.

Troubleshooting

If the wp vip data-cleanup datasync CLI command fails during a data sync, the vip_datasync_cleanup hook will not be triggered.

The wp vip data-cleanup datasync will fail if a PHP fatal error is occurring on a site. The wp vip data-cleanup datasync command can be manually run against a target environment with VIP-CLI in order to retrieve the command output and identify the error.

In this command example, wp vip data-cleanup datasync is run against the “develop” environment of the “example-app” application:

vip @example-app.develop -- wp vip data-cleanup datasync

The command output should be reviewed carefully for all reported errors. Updates must be made to resolve the errors in the application’s GitHub repository branch that deploys to the target environment. Test the code updates by running the wp vip data-cleanup datasync command against the environment. When errors are no longer reported and the command can complete successfully, the vip_datasync_cleanup hook should no longer be blocked during a data sync.

WordPress multisite

The vip_datasync_cleanup hook runs sequentially on a loop through each individual network site that exists on a WordPress multisite environment. If an error occurs on a network site, the loop will be interrupted and the hook will not run on the remaining network sites.

Application code that is causing PHP fatal errors on a network site must be identified and resolved in order for data cleanup operations to complete on the remaining sites on the network. Identify the theme(s) or plugin(s) causing the errors by running the wp vip data-cleanup datasync against the environment. Review the command output and resolve all reported errors.

To verify if the vip_datasync_cleanup hook was triggered on a specific network site, run the custom WP-CLI command wp option get vip_datasync_cleanup_triggered against that network site. If the vip_datasync_cleanup hook was not triggered, the option will not exist.

For example:

$ vip @example-app.develop -- wp option get vip_datasync_cleanup_triggered --url=site.example.com
Error: Could not get 'vip_datasync_cleanup_triggered' option. Does it exist?