Migrating and importing content

VIP Go platform specific

This document is for sites running on VIP Go.

Learn more

Overview #

To migrate content onto VIP Go, we need two assets:

  1. The database file as a SQL dump, and
  2. The media as a compressed archive.
Files to import can be attached to a Zendesk ticket — or files larger than 20 MB can be transferred via sending us a web-accessible link to the files (eg https://www.mysite.com/uploads.tar.gz). You may also use Amazon S3, Dropbox, Box, WeTransfer, or another similarly secure service.
Please also be sure to include the domain name of the VIP Go environment the import is for.

↑ Top ↑

SQL dump #

This is the database dump of the WordPress migration source, typically from a development or staging environment where the site is being built and QA’d. (If exporting from a local environment, we recommend that the site is staged in a tool such as VVV instead of localhost.)

Please note the following guidelines to ensure a successful SQL import:

  • The table prefix should be wp_.
  • The SQL file should include DROP TABLE IF EXISTS commands prior to each CREATE TABLE.
  • CREATE DATABASE statements should not be used – they must be removed if present.
  • Unnecessary tables (eg, for plugins that aren’t in use) should be removed.
  • Default character set of utf8mb4 should be used to ensure that characters such as emoji are imported correctly.
  • If possible, perform the URL transformations from your local development URL(s) to the VIP Go URL(s) prior to submitting the import.
  • If the above isn’t possible, let us know what the search-replace “from” and “to” arguments should be. For example, if your local environment uses mysite.local and your VIP Go environment is mysite.go-vip.net, please provide that information.
  • If your local environment is a single site, and you have a multisite environment on VIP Go, please convert your local installation to multisite prior to creating and submitting the SQL dump.
  • See further considerations for multisite below.

We recommend compressing the database file with gzip before it is provided to VIP.

Some examples of exporting (or creating backups) of the database are outlined on WordPress.org. Two such methods are from the command line using mysqldump, or via a third-party WordPress plugin such as WP Migrate DB Pro. Here is an example mysqldump command:

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

↑ Top ↑

Media #

Also frequently referred to as uploads, media should be provided as a compressed archive of the uploads directory (typically /path/to/wordpress/wp-content/uploads/ or the directory in the UPLOADS constant). If possible, it is best to exclude intermediate images, as they are unnecessary (see Notes on media export). This folder can be submitted as a ZIP or compressed tarball archive.

We can start importing the media at any time. It’s best to supply the initial archive as soon as possible, to give ample time for troubleshooting. We can follow up with delta imports closer to launch if needed.

If you are submitting any SVG files to be imported into the media library, these files need to be reviewed by our engineers, as SVGs can contain more than just images. In this case, please submit a ZIP of the SVGs via Zendesk to be reviewed and imported separately. If these files are part of your theme, they should instead be committed to GitHub as part of your code review.

↑ Top ↑

Notes on media export #

WordPress will rename files containing these special characters upon upload to the media library: ~?,[]/\=<>:;'\&$#*()|~`!{}%+ and whitespace ( ). If your media export contains files named with these characters, `Example+(1).jpg` for example, we will not be able to import those files. We advise renaming the files and replacing any references to them in your database before submitting your files.

If possible, we advise excluding intermediate images, as they are unnecessary on VIP Go. This can make the export much smaller (up to 95% of the size can be saved), and the import proportionally quicker.

Intermediate images are the different image sizes WordPress creates when uploading an image. For example, when uploading example.jpg, which is the full-size original version of the image, intermediate images filenames could be example-150x150.jpg, example-500x300.jpg, etc.

The only real action needed when migrating to VIP Go is to set the WPCOM_VIP_USE_JETPACK_PHOTON constant to true. The best way to achieve this is to add the following line in your vip-config/vip-config.php file:


This code will ensure old image filenames are handled correctly. Image tags such as

<img src="https://automattic.com/wp-content/uploads/2018/06/image-660x344.jpg" width="660" height="344" />

will be seamlessly rewritten to

<img src="https://automattic.com/wp-content/uploads/2018/06/image.jpg?resize=660,344" width="660" height="344" />

↑ Top ↑

Multisite #

Multisite migrations have a few additional considerations:

  • It’s best if the export includes only the sites to be migrated to VIP Go.
  • If your local environment is a single site, and you have a multisite environment on VIP Go, please convert your local installation to multisite prior to submitting the SQL dump.
  • The VIP Go production environment does not need any special preparation for the import.
  • The subsites and their corresponding IDs will be created according to the IDs in the SQL dump that is provided for the import.
  • Remember that subsite #1’s media is found in the /wp-content/uploads folder — but all subsequent sites in the network will be in the /wp-content/uploads/sites/ folder, in their own subfolder based on the site number, designated by the database. For example: /wp-content/uploads/sites/{SITE ID}/{YEAR}/{MONTH}/{FILE NAME}, where the site ID would not have any leading 0’s e.g. use 2, not 02. This structure is a change from older versions of WordPress prior to 2013.

↑ Top ↑

Frequently asked questions #

Q: Are user accounts imported from SQL, or manually created?
They are created from SQL. Any users already in the VIP Go production environment will be dropped and replaced by the users in the imported database.

Q: Are there typically any data-cleaning scripts or processes that need to be run on the final SQL import?
Typically, the only cleanup we run is wp search-replace on the domain if necessary. The SQL provided for import should be ready to go as-is to make the switch over as fast as possible.

Q: How do delta imports work?
Delta imports are only supported for media. You can also provide an updated media archive, and by default, we will add new files only without updating or deleting previously imported files.

For SQL, we’ll replace the VIP Go environment’s current database with an updated SQL export that you provide. This will update any older posts that have been modified and add all new posts.

After a delta import, the object cache is flushed, but we may not need to flush the page cache, as it will automatically expire in 30 minutes.

Q: Does the theme need to be complete before the migration is run?
No, we can process imports at any time during the launch process.

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.