Full or partial SQL database files can be imported to a running VIP Local Development Environment. It is recommended to import database files after a VIP Local Development Environment is confirmed to be up and running and has been configured to run with locally cloned application code.
Full SQL database backups for VIP Platform environments can be downloaded from the VIP Dashboard or exported with VIP-CLI. Backup files include custom tables, and are compatible with the VIP Local Development Environment.
- The SQL file can include all tables from the database of a WordPress single site or multisite install, or only a specific table—or set of tables—from that database.
- The database table structure of WordPress multisites differs from the structure of single sites. To work as expected, a SQL file that originated from a multisite install should be imported to a VIP Local Development Environment that was created as a multisite.
On the user’s local machine:
- VIP-CLI is installed and is updated to the most current version.
- A VIP Local Development Environment has been successfully created and is in a running state.
- To sync a database of a VIP Platform environment to a VIP Local Development Environment, a user must have at minimum an Org admin role or an App admin role for that application.
Sync a database
As an alternative to importing a SQL database file, a VIP Platform environment’s database can be synced to a VIP Local Development Environment with the VIP-CLI command:
vip dev-env sync sql.
For example, to sync the database of the “mytestsite” application’s develop environment to a local environment with the
vip @mytestsite.develop dev-env sync sql --slug=example-site
When importing a SQL database file from a WordPress multisite, each network site on the local environment will automatically be assigned a site URL that follows the pattern:
For example, a network site with ID 14 that is synced to a local environment with the
example will have the site URL:
Import a database
To import, a SQL database file (e.g. downloaded from Database Backups) must already be located on the local machine under the home directory of the current user. The SQL database file can either be archived or unarchived when imported.
1. Identify the absolute local path of the SQL file
Example local paths for a SQL file named
file.sql for a current user named “example-user”:
2. Validate the SQL file
Verify that the SQL database file is correctly formatted for import with the
vip import validate-sql VIP-CLI command.
The SQL database file must be unarchived (decompressed) in order to run the
vip import validate-sql command against it.
This example command is using the absolute local path from the macOS example in the previous step:
vip import validate-sql /Users/example-user/file.sql
Any errors reported by the
validate-sql command must be resolved before importing the SQL file to the local environment.
3. Import the SQL file
vip dev-env import sql command to import a SQL database file to a running local environment.
As part of the import process, the
vip dev-env import sql command will automatically:
- Clear the object cache.
- Add a WordPress user with an Admin role and default login credentials to all local environment sites.
In this example, the command is importing a SQL database named
file.sql to a local environment with an assigned
vip dev-env import sql /Users/example-user/file.sql --slug=example-site
During the import process, a
--search-replace operation should be run to replace domain values in the SQL file with the domain of the local development environment.
In this example, the value
example-site.com is replaced with
example-site.vipdev.lndo.site during the import of
file.sql to the local environment:
vip dev-env import sql /Users/example-user/file.sql --slug=example-site --search-replace="example-site.com,example-site.vipdev.lndo.site"
Database imports for multisites
When importing a SQL database file exported from a WordPress multisite, the import command should include a
--search-replace operation for every network site that is included in the database.
Subdomains and subdirectories
It is possible for the Site Address URL of a network site in the database to be either a subdomain or a subdirectory format.
- By default, the database of a newly created local multisite environment has a subdomain structure. When importing a database file to a local environment with a subdomain structure, use the
--search-replaceoperation to replace the domain values of every network site with a subdomain value of
- To import network sites to the local environment with a subdirectory structure, the local environment must be created as a multisite with a subdirectory structure by including
vip dev-env createcommand. When importing a database file to a local environment with a subdirectory structure, the
--search-replaceoperation can be used to replace the domain values of every network site with either a subdirectory or a subdomain value of
Order of operations
The order in which the search and replace operations matters. In the example command below, three
--search-replace operations are included in a single
- Occurrences of a network site’s subdirectory domain
admin.example-site.com/site-threewill be replaced with a sub-subdomain structure
admin.example-site.com, an example domain value for site ID 1, will be replaced with
- Occurrences of another network site’s domain
example-site.comwill be replaced with
vip dev-env import sql /Users/example-user/file.sql --slug=example-site --search-replace="admin.example-site.com/site-three,site-three.example-site.vipdev.lndo.site" --search-replace="admin.example-site.com,admin.example-site.vipdev.lndo.site" --search-replace="example-site.com,example-site.vipdev.lndo.site"
Using WP-CLI commands to run additional
search-replace operations may be necessary after the import is complete. To accurately run a
search-replace operation, the command structure will depend on whether the
search-replace is targeting an entire single site, multisite, or specific tables.
Last updated: December 04, 2023