Title: Data sync between environments
Author: liranadia
Published: October 1, 2026
Last modified: October 20, 2026

---

 1. [Databases](https://docs.wpvip.com/databases/)
 2. Data sync between environments

#  Data sync between environments

A data sync operation copies a WordPress database, including media files, from a
source environment to a destination environment within the same application. On 
the WordPress VIP Platform, data sync operations are multi-directional: a sync can
run in any direction between environments, including from a non-production environment
into production. The source environment supplies the data, and the destination environment
receives it.

A data sync is initiated from the **Sync Data** page in the VIP Dashboard. The destination
is always the environment that is currently selected in the VIP Dashboard. The source
is selected on the page.

## Prerequisites

To initiate a data sync in the VIP Dashboard, a user must have the App write role
or the Org admin role. For more information, review [App roles and permissions](https://docs.wpvip.com/manage-user-access/vip-dashboard/app-role/)
and [Org roles and permissions](https://docs.wpvip.com/manage-user-access/vip-dashboard/org-roles/).

Because a data sync can write to a production environment, opening the **Sync Data**
page requires [step-up authentication](https://docs.wpvip.com/manage-user-access/vip-dashboard/step-up-auth/).

## Limitations

 * Only 1 data sync operation can run to a destination environment at a time. While
   a sync is in progress, the configuration options are unavailable until the sync
   completes or fails.
 * A sync overwrites or updates the destination database with the source database.
   Confirm the correct source and destination before starting a sync, particularly
   when the destination is a production environment.
 * WordPress multisite environments with additional network sites must maintain 
   a config.yml for correct results.
 * Elasticsearch indexes are not included in the data sync process.
 * A data sync is a one-time operation. Syncs cannot be scheduled, and no notification
   is sent when a sync completes.

## What a data sync includes

A data sync copies the full contents of the source environment’s database as it 
exists when the sync runs, along with the environment’s media files. Domain and 
URL references are rewritten from the source environment’s domains to the destination
environment’s domains so that content resolves correctly on the destination. Mapped
domains control which replacements are applied. Review [Mapped domains](https://docs.wpvip.com/databases/data-sync-between-environments/#3-mapped-domains).

Environment-specific settings on the destination are preserved rather than overwritten.
Review [Protected options](https://docs.wpvip.com/databases/data-sync-between-environments/initiate-a-data-sync-operation/#3-protected-options).

After a data sync completes, the destination environment has access to the source
environment’s [shared media files](https://docs.wpvip.com/vip-file-system/shared-media-files/)
in read-only mode.

## Mapped domains

A mapped domain defines which domain to search for in the source database and which
domain to replace it with. Mapped domains are managed on the **Sync Data** page 
for each source and destination pair.

The destination environment’s primary domain is always applied and appears in the
list as **Primary domain**. It cannot be edited or removed, because it is applied
to every sync rather than stored as configuration.

Mappings are ordered from the most specific replacement to the most general. Search
and replace runs in the same order, so the list reads in the order it is applied.

A missing or incorrect mapping can leave links and references in the destination
environment pointing at the source environment.

### Saved and suggested mappings

Mappings appear in 2 lists:

**Saved mappings** are applied when the sync runs. They persist for that source 
and destination pair, so returning to the same configuration later shows the same
mappings, whether or not the earlier sync was started.

**Suggested mappings** are replacements inferred from mappings that already exist.
If mappings exist from environment A to B and from A to C, the mapping for a sync
from B to C can be inferred. Child-to-production mappings can be inferred by reversing
existing production-to-child mappings.

Suggestions are selected by default, but they are not applied to the sync until 
they are saved. Review the suggested mappings and clear the checkbox for any mapping
that should not be applied. Then save the selected mappings. Saved mappings move
to the **Saved mappings** list and are applied during the sync.

Suggestions that are left unselected remain in the **Suggested mappings** list and
are not applied.

Review suggested mappings before each sync. Suggestions are generated dynamically
from the existing configuration, so a mapping that was previously deleted from the**
Saved mappings** list may be suggested again later.

### Add, edit, and remove mappings

Mappings are added and edited directly on the page. Each mapping must include both
a **Search for** value and a **Replace with** value before it can be saved.

If a mapping conflicts with an existing mapping, it cannot be saved. The reason 
for the conflict appears next to the mapping.

Removing a saved mapping requires confirmation. Deleted mappings are not permanently
rejected, so the VIP Dashboard may suggest the same mapping again during a future
sync between those environments. If it reappears, leave it unselected to avoid saving
or applying it.

### Mapped domains and the configuration file

Domain replacements were previously managed in the [data sync configuration file](https://docs.wpvip.com/databases/data-sync/config-file)
in an application’s GitHub repository. That method is deprecated. Once mappings 
are saved in the VIP Dashboard, the VIP Dashboard is the source of truth for domain
replacements for that source and destination pair. Move existing replacements from
the configuration file into the VIP Dashboard.

Last updated: October 20, 2026