Import databases

Limitations

• For unlaunched environments the database must be smaller than 100GB in size.
• For launched environments the database must be smaller than 5GB in size.
• Non-production environments will go into maintenance mode during a SQL import. This will block users from making database updates (e.g., creating or editing posts, changing site settings) for the duration of the import process.

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:

1. Install a third-party plugin designed to export WordPress database content.
2. Run a  mysqldump command 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

Database imports for multisite environments

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 site is a WordPress single site, the database will need to be converted to a multisite database prior to import. A working version of a VIP application on a VIP Local Development Environment set up as multisite is a helpful tool for migrating WordPress single sites into a multisite.

Requirements

• The database must have been exported from a WordPress multisite.
• If importing the database for an entire multisite network, ensure that the export has all tables listed in network-level tables shared by all sites.
• If importing tables for a specific site, ensure the table prefixes match the intended destination site ID (e.g., tables prefixed wp_3_ will be imported to site ID 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 sites, the database export should include only the tables for those sites.
• If the SQL file being imported includes tables for the main site (ID 1), and the domain value in the file for site ID 1 does not match a domain that has been mapped to the environment for import, the import will fail. To prevent this issue, use --search-replace either before or during the import to update the domain value for site ID 1 with a domain that is mapped to that environment.

Use --search-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 must be done before or during import.

• The domain name value for an unlaunched VIP Platform environment is typically a convenience domain (e.g., example.go-vip.net).
• 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 @mytestsite.production import sql file.sql --search-replace="http://localhost,https://example.go-vip.net"

Example command for a database import to a WordPress multisite, also demonstrating multiple --search-replace operations:

vip @mytestsite.production import sql file.sql --search-replace="http://localhost,https://example.go-vip.net" --search-replace="example2.com,example.go-vip.net/subdir"

Import database files with VIP-CLI

Prior to running any import commands, confirm all items in this checklist:

• Validate that the SQL database file is correctly formatted for import with the vip import validate-sql VIP-CLI command.
• Before importing the database file to a VIP environment, it is recommended to perform a test import to 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 SQL

Import a SQL database to an environment with the vip import sql VIP-CLI command.

Refer to the help menu for a full list of commands, options, and examples.

vip import sql --help

Example command for importing a SQL database named “file.sql“, where the command is run from within the same local directory as the file:

vip @mytestsite.production import sql file.sql

Check the status of an import

If an import is currently running, the output from the vip import sql status command will be for the currently running import. If an import is not currently running, the output will be for the import that ran most recently. The Audit Log panel, located in the Organization view of the VIP Dashboard, can provide insight into when an import was requested.

Output from the status command lists the series of steps executed during an import, and displays a progress indicator for each step:

• Pending: ○

• Success: ✓
• Failed: ✕

An overall status report on the import process appears below the listed import steps. The Status: field will display either Running, Success or Failed.

$ vip @mytestsite.production import sql status
=============================================================
Checking the SQL import status for your environment...
✓ Performing Search and Replace
✓ Uploading file
✓ Queueing Import
✓ Import preflights
✓ Downloading file from s3
✓ Uncompressing gzip
✓ Checking md5 hashes
✓ Backup db
✓ Importing db
✓ Validating db
✓ Update wp blogs table
✓ Update primary domain

=============================================================
Status: Success ✓ imported data should be visible on your site mytestsite.go-vip.net.
Site: mytestsite (PRODUCTION)
SQL Import Started: 07/01/2022, 1:14:54 pm (2022-01-07T02:14:54.000Z)
SQL Import Completed: 07/01/2022, 1:19:31 pm (2022-01-07T02:19:31.000Z)
=============================================================

**If an import fails at the Importing db step:

• An unlaunched environment’s database automatically rolls back to the backup taken prior to the import job.
• A launched environment will be locked against any additional import attempts and needs to be reset by VIP Support in order for a new import to be attempted.

Failures can occur due to an invalid SQL file, or if there is an error present in the file. If the import fails, the Restore db step is returned in the status output.

Considerations

• 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.

Protected options

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.