Sync a platform database to Codespaces

The vip-sync-db command can sync the database of a WordPress VIP Platform environment to a codespace environment that was created with the .devcontainer/devcontainer.json file provided by WPVIP.

Targeting a VIP Platform environment with the vip-sync-db command will:

• Retrieve the most recent database backup for that platform environment.
• Import the database backup file to the running codespace environment.
• Perform a wp search-replace operation to update all URL values in the database from the platform environment’s domain to the codespace environment’s domain.
• Complete wp cache flush to clear the object cache of the codespace environment.

The vip-sync-db command be run more than once in order to update the database of the codespace environment with the most recent database backup of the targeted platform environment.

Limitations

• The same limitations for the number and frequency of database exports apply to database syncing for Codespaces.
• The total available disk space on a Codespace virtual machine is 32 GB. The total combined size of an application’s codebase, VIP MU plugins, the machine’s Linux image, runtimes, and any imports or additions to the database must be less than 32 GB. For this reason, the allowed size of a database file to be imported will vary depending on the amount of disk space that remains available within the 32 GB limit.
• GitHub Codespaces does not support syncing databases for a WordPress multisite application that has network sites with subdomain structures for their Site Address URL values. If syncing a database with a subdomain structure, a manual search and replace operation will be necessary to update the platform domain values to the codespace domain values with a unique subdirectory (e.g. searching for site-4.example.com and replacing it with https://example-80.app.github.dev/site-4). Syncing the database of a multisite that has network sites with a subdirectory structure will in most cases complete without issue.

Sync a platform database

A Visual Studio Code (VS Code) interface will be available in a successfully running codespaces environment. To sync the database of a platform environment to the codespaces environment, in VS Code’s “Terminal” panel run the command:

• vip-sync-db if the value of VIP_APP_ID has already been set as a Codespaces secret or in a config file.
• VIP_APP_ID=<value> vip-sync-db if setting the value of VIP_APP_ID at the time the command is run.

After running the command, if the user is not yet logged in to VIP-CLI in the codespace environment they will be prompted to complete the authentication process:

1. At the Ready to authenticate? (y/N) prompt in the terminal, type y. If a modal titled “Do you want Code to open the external website?” appears, select the button labeled “Open” to be sent to the VIP Dashboard.
2. As a logged in user of the VIP Dashboard, navigate to the user “Settings” panel.
3. Select the button labeled “Generate Token“.
4. Select the button labeled “Copy Token” to add the Personal Access Token to the local machine’s clipboard.
5. Return to the VS Code terminal of the codespace environment.
6. Paste the Personal Access Token at the Access Token: prompt and press Return or Enter on the keyboard.

After completing authentication, the syncing process will proceed and status updates on progress will be output in the terminal.

Environment variables for targeting a platform environment

The vip-sync-db command requires the VIP_APP_ID environment variable to be set in order to target a WPVIP Platform environment for the database sync. Target a platform environment by setting the value of VIP_APP_ID as either an application’s name alias format @<app-name>.<env> (e.g. @example-app.production) or an application’s ID alias format @<app-ID>.<env> (e.g. @8886.production) with one of the following methods:

• Set the environment variable in Codespaces secrets.
• Set the environment variable in the config file.
• Set the environment variable when running the command.

Set the environment variable in Codespaces secrets

The VIP_APP_ID environment variable and its value can be stored as a GitHub Codespaces secret. Follow GitHub’s documentation for adding a Codespaces secret to learn more about how to use this feature.

Secret “Name”: VIP_APP_ID

Secret “Value”: The target environment’s application name alias (@<app-name>.<env>) or ID alias (@<app-ID>.<env>) .

Set environment variable in the config file

In this code example, the environment variable VIP_APP_ID is added to the .devcontainer/devcontainer.json config file and the value is set to an environment’s application name alias @example-app.production:

// *****************************
// *** Environment variables ***
// *****************************
"containerEnv": {
	// Application name alias format 
	"VIP_APP_ID": "@example-app.production"
	// Application ID alias format 
    // "VIP_APP_ID": "@8886.production"
},

Set the environment variable when running the command

If the value of VIP_APP_ID is not already set in a repository’s Codespaces secrets of in a branch’s config file, the value can be set at the time the vip-sync-db command is run in the local machine’s terminal.

In this command example, the value of VIP_APP_ID is set as @example-app.production in the command line:

VIP_APP_ID=@example-app.production vip-sync-db