VIP-CLI is installed and has been updated to the most current version.
Export a SQL file from a non-VIP WordPress install
In order to migrate existing database content to VIP, an SQL file must be exported from a current WordPress site. Recommended methods for exporting a WordPress SQL database:
- Install a third-party plugin designed to export WordPress database content.
- Run a
mysqldumpcommand in a command line interface. For example:
mysqldump --add-drop-table --hex-blob --no-create-db --quote-names -h dbhost -u user -p dbname --default-character-set=utf8mb4 --result-file=dbname-full.sql
Exports from phpMyAdmin are not compatible with VIP’s import tooling.
Check that the database is a valid SQL file
Verify that the SQL database file is correctly formatted for import with the VIP-CLI command
vip import validate-sql <path/to/file.sql>.
Multisite network database imports
Database structure for a WordPress multisite differs from the database structure of WordPress single site. In order to import a database to a VIP WordPress multisite network, the database must be exported from a WordPress multisite.
If the origin WordPress site is a single site, the database will need to be converted to a multisite database prior to import. A working version of a VIP app on a local development environment set up as multisite is a helpful tool for migrating WordPress single sites into a multisite.
Requirements for importing a database to a VIP multisite network:
- The database must have been exported from a WordPress multisite.
- If importing the database for an entire multisite network, ensure that the export has the
- If importing tables for a specific subsite, ensure the table prefixes match the intended destination site ID (e.g., tables prefixed
wp_3_will be imported to subsite 3). Table prefix values will be visible in the confirmation output of the import command.
- If importing a selection of tables for one or more subsites, the database export should include only the tables for those subsites.
Import database files with VIP-CLI
Importing a SQL database to a VIP site will replace data on the site for any SQL tables included in the import file. Pre-existing data that is overwritten by an imported table will be gone.
Prior to running any import commands, confirm all items in this checklist:
- The database for import is a valid SQL file.
- For unlaunched sites the database must be smaller than 100GB in size.
- For launched sites the database must be smaller than 350MB in size.
- Before importing the database file to a VIP environment, perform a test import into an empty local WordPress development environment to ensure that the prepared database provides expected import results.
If the database for import does not meet the above requirements, create a VIP Support ticket requesting assistance with the import and include a downloadable link for the database file.
Import a SQL database to a VIP app with the
vip import sql VIP-CLI command.
Specify the app and its environment that are the destination for the import by providing the app alias, a dot separator, and the environment name, in the form of:
For demonstration purposes, the
wpvip and the
production are used in the command examples below.
Example command for importing a SQL databased named “file.sql”, where the command is run from within the same local directory as the file:
vip import sql @wpvip.production file.sql
Use search and replace to update domain name values
If the database for import contains domain name values that do not match the VIP destination site’s domain name, a search and replace operation will be needed during import.
- The domain name value for an unlaunched VIP site is typically a convenience domain (Example:
- Search and replace values are separated by a comma only. There are no spaces between the values.
The following example shows the values as they would need to appear in order to search for the domain
http://localhost in a database that was exported from a local machine, and replacing it on import with the convenience domain
https://example.go-vip.net for an unlaunched VIP environment:
vip import sql @wpvip.production file.sql --search-replace="http://localhost,https://example.go-vip.net"
Example command for a database import to a WordPress multisite, also demonstrating multiple
vip import sql @wpvip.production file.sql --search-replace="http://localhost,https://example.go-vip.net" --search-replace="example2.com,example.go-vip.net/subdir"
Status of import
Check the status of an import that is currently running:
vip import sql status @wpvip.production
Refer to the help menu for additional options, commands, and examples:
vip import sql --help
- If an import for unlaunched site fails due to an invalid SQL file, or there is an error present in the file, the process will revert the site’s database back to the previous, most-current backup.
- It is possible for the import process to complete successfully, but for other conflicting errors to prevent the site from loading properly (e.g.- PHP errors in the theme). If the results of an import are not as expected after the process has completed, the process can be re-tried.
- Once a database import into a VIP environment has completed, site testing is recommended to ensure that the results match the expectations of the import.
The following options are protected during SQL imports, meaning they are backed up beforehand and restored afterward. This is to help prevent overwriting or accidentally sharing environment-specific configs. It is not possible to extend or modify this list.
"WP Options" = [ 'jetpack_options', 'jetpack_private_options', 'vaultpress', 'vip_jetpack_connection_pilot_heartbeat', 'wordpress_api_key', 'vip_search_index_versions', 'vip_search_global_index_versions', ]; // On multisites "Site Meta" = [ 'vip_search_global_index_versions', ];
Custom cleanup operations
The vip_sqlimport_cleanup hook can be used for custom cleanup or changes of application data after an import. Some examples of cleanup operations include switching out production API keys, or performing brief data manipulation. It is not ideal to do any longer-running operations here as it keeps the site under maintenance mode until it import is completed. Instead, consider registering a one-time cron event on this hook, to do something immediately afterwards via cron.