Sync or import database content to a VIP Local Development Environment

Database content can be imported or synced to a running VIP Local Development Environment. Before syncing or importing content, It is recommended to first confirm that the VIP Local Development Environment is up and running as expected. Configuring the environment to load locally cloned application code prior to adding data can also help prevent unexpected errors.

Sync a database

Data from the most recent backup of a VIP Platform environment’s database can be synced to a running VIP Local Development Environment with the VIP-CLI command: vip dev-env sync sql.

For example, to sync data from the database backup of the “example-app” application’s develop environment to a local environment with the --slug value example-site:

vip @example-app.develop dev-env sync sql --slug=example-site

Sync a WordPress multisite database

When the database of a WordPress multisite is synced to a local environment with the VIP-CLI command vip dev-env sync sql, each synced network site will automatically be assigned a site URL that is compatible with the domain of the local environment. The pattern of the updated domain name for each synced network site will differ depending on if the site had been assigned a primary domain or a secondary domain:

• Primary Domain: [ENVIRONMENT_SLUG].vipdev.lndo.site
• Secondary Domain: [SLUGIFIED_DOMAIN].[ENVIRONMENT_SLUG].vipdev.lndo.site

For example, a network site using example.com as a primary domain that is synced to a local environment with the --slug value vip-local will have the site URL: vip-local.vipdev.lndo.site. However, if example.com is a secondary domain, the site URL will be example-com.vip-local.vipdev.lndo.site.

Partial Database Sync

The VIP-CLI command vip dev-env sync sql [options] can also be used to sync a specific set of tables and data from the current state of a VIP Platform environment’s database to a running VIP Local Development Environment.

This example command demonstrates how to perform a sync of the wp_posts table from the database of the “example-app” application’s develop environment to a local environment with the --slug value example-site:

vip @example-app.develop dev-env sync sql --slug=example-site --table=wp_posts

For WordPress multisite environments, the tables related to a specific network site can be synced to the local environment by passing the site’s ID with the --site-id option:

vip @example-app.develop dev-env sync sql --slug=example-site --site-id=7

The --table and --site-id options can be passed more than once in the same command in order to sync more than one table of network site at one time. For example, this command is formatted to sync the wp_posts and the wp_comments tables to a local environment:

vip @example-app.develop dev-env sync sql --slug=example-site --table=wp_posts --table=wp_comments

Alternatively, multiple tables or network sites can be synced in the same command by passing the values in a comma-separated list (no spaces) with the relevant option. In this example command, network site site ID 7 and network site ID 11 will be synced to a local environment:

vip @example-app.develop dev-env sync sql --slug=example-site --site-id=7,11

A custom configuration file or a custom WP-CLI command can also be used to sync a custom set of data from a VIP Platform environment’s database to the local environment.

Import a SQL database file

Full or partial SQL database files can be imported to a running VIP Local Development Environment.

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.

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”:

macOS: /Users/example-user/file.sql
Windows: C:\Users\example-user\file.sql
Ubuntu: /home/example-user/file.sql

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

Use the 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 --slug value example-site:

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 file 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-replace operation to replace the domain values of every network site with a subdomain value of vipdev.lndo.site.
  For example: --search-replace="example-site.com,example-site.vipdev.lndo.site" and --search-replace="example-site.com/subdirectory,example-site-subdirectory.vipdev.lndo.site"
• 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 --multisite=subdirectory in the vip dev-env create command. When importing a database file to a local environment with a subdirectory structure, the --search-replace operation can be used to replace the domain values of every network site with either a subdirectory or a subdomain value of vipdev.lndo.site.
  For example: --search-replace="example-site.com/subdirectory,example-site.vipdev.lndo.site/subdirectory" and --search-replace="example-site.com/subdirectory-two,subdirectory-two.example-site-subdirectory.vipdev.lndo.site"

Order of –search-replace operations

The order in which --search-replace operations are run can make a difference in the outcome. If --search-replace="example-site.com,admin.example-site.vipdev.lndo.site" is run before --search-replace="site-two.example-site.com,site-two.vipdev.lndo.site", the result will be:

• a site with the domain admin.example-site.vipdev.lndo.site
• a site with the domain site-two.admin.example-site.vipdev.lndo.site
• and no site with the domain site-two.vipdev.lndo.site.

Using WP-CLI commands to run additional search-replace operations may be necessary after an 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.

Example with subdomains and subdirectories

In this example:

• Occurrences of a network site’s subdirectory domain admin.example-site.com/site-three will be replaced with a sub-subdomain structure site-three.example-site.vipdev.lndo.site.
• admin.example-site.com, an example domain value for site ID 1, will be replaced with admin.example-site.vipdev.lndo.site.
• Occurrences of another network site’s domain example-site.com will be replaced with example-site.vipdev.lndo.site.

All three --search-replace operations are included within a single import command in a specific order to achieve the expected results:

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"