Skip to content

Backgrounds

How-to Guides

Technical References

Import databases

Note

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.

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

Caution

Exports from phpMyAdmin are not compatible with VIP’s import tooling.

Check that the database is a valid SQL file

The VIP-CLI command vip import validate-sql should be used to verify the format of the SQL database file.

Multisite network database imports

Database structure for WordPress single sites differ from the database structure of a WordPress multisite. The origin for a database imported to a VIP WordPress multisite network must be exported from a multisite as well. If the origin WordPress site is a single site, the database will need to be transformed 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 multisite.
  • The database SQL file must be less than 350MB in size
  • If importing the database for an entire multisite network, ensure that the export has the wp_site and wp_blogs tables.
  • 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.

Use search and replace

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: 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://example.dev 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:

--search-replace="http://example.dev,https://example.go-vip.net" 

Import database files with VIP-CLI

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

  • A current version of VIP-CLI is installed.
  • The database for import is a valid SQL file
  • For un-launched sites, the database must be smaller than 10GB 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 these requirements, create a request for VIP Support to perform the SQL database import. 

Note

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:
@<app-alias or app ID>.<env>.

The @mysite.production values in the command examples below are for demonstration only.

Import a SQL database to a VIP app using the vip import sql command in the VIP CLI.

  • Search and replace values are separated by a comma only. There are no spaces between the values.

Example command for a database import to a WordPress single site:

vip import sql @wpvip.production file.sql --search-replace="http://example.dev,https://example.go-vip.net"

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

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

Refer to the help menu for additional options, commands, and examples:

vip import sql --help

Check the status of an import that is currently running:

vip import sql status @wpvip.production

If an import 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 other conflicting errors might prevent the site from loading properly (e.g.- PHP errors in the theme). If after an import completes the results are not as expected, the process can be re-tried.

Once the database import into a VIP environment is completed, site testing is recommended to ensure that the results match your expectations.

Last updated: May 27, 2021

Related Topics