Sync Modes

php-sync-tool selects a synchronization mode automatically based on the origin and target configuration — specifically whether each endpoint is remote (has a host), whether both point at the same host, and whether an import file is given. You never set the mode explicitly.

Overview

Mode	Origin	Target	Description
Receiver	Remote	Local	Pull a database from a remote system
Sender	Local	Remote	Push a database to a remote system
Proxy	Remote	Remote	Transfer between two remotes via local
Dump Local	Local	Local (same)	Create a local backup
Dump Remote	Remote	Remote (same)	Create a remote backup
Import Local	—	Local	Import a dump file locally
Import Remote	—	Remote	Import a dump file remotely
Sync Local	Local	Local (diff path)	Copy between two local databases
Sync Remote	Remote	Remote (same host, diff path)	Copy within one remote system

The --import-file (-i) option selects the import modes. The dump modes are selected when origin and target resolve to the same host/database with no transfer needed.

Receiver

Pull a database dump from a remote system (origin) to your local system (target). This is the default and most common mode.

Origin has a host, target does not:

origin:
  host: prod.example.com
  user: deploy
  path: /var/www/html/LocalConfiguration.php
target:
  path: /var/www/local/LocalConfiguration.php

Use cases: pulling production data to local development, local backups of remote databases.

Sender

Send a database dump from your local system (origin) to a remote system (target).

Target has a host, origin does not:

origin:
  path: /var/www/local/LocalConfiguration.php
target:
  host: staging.example.com
  user: deploy
  path: /var/www/html/LocalConfiguration.php

Use cases: pushing local data to staging, deploying database changes to test environments.

WARNING

Be careful when sending to remote systems. Consider protect: true on production hosts.

Proxy

Transfer a database between two remote systems using your local machine as a relay (two hops). Useful when origin and target cannot connect directly.

Both origin and target have a host (different hosts):

origin:
  host: prod.example.com
  user: deploy
  path: /var/www/html/LocalConfiguration.php
target:
  host: staging.example.com
  user: deploy
  path: /var/www/html/LocalConfiguration.php

Flow: dump on origin → transfer to local → transfer to target → import on target.

Use cases: syncing isolated environments, cross-datacenter transfers.

Dump Local

Create a database dump on your local system, without transfer or import.

Origin and target are both local and resolve to the same system:

origin:
  path: /var/www/local/LocalConfiguration.php
  dump_dir: /var/backups/
target:
  path: /var/www/local/LocalConfiguration.php

Use cases: local backups, snapshots before risky operations.

Dump Remote

Create a database dump on a remote system, without transfer or import.

The same host in both origin and target:

origin:
  host: prod.example.com
  user: deploy
  path: /var/www/html/LocalConfiguration.php
  dump_dir: /var/backups/
target:
  host: prod.example.com
  user: deploy
  path: /var/www/html/LocalConfiguration.php

Use cases: remote backup creation, scheduled backups.

Import Local

Import an existing dump file into a local database. Selected by -i:

bin/sync-tool -f config.yaml -i /path/to/dump.sql.gz

target:
  path: /var/www/local/LocalConfiguration.php

Use cases: restoring from backup, importing a shared dump.

Import Remote

Import an existing dump file into a remote database. Selected by -i with a remote target:

bin/sync-tool -f config.yaml -i /path/to/dump.sql.gz

target:
  host: staging.example.com
  user: deploy
  path: /var/www/html/LocalConfiguration.php

Use cases: restoring remote systems, deploying database snapshots.

Sync Local

Copy a database between two different local paths/databases.

No host entries, but different path (or database):

origin:
  path: /var/www/project-a/LocalConfiguration.php
target:
  path: /var/www/project-b/LocalConfiguration.php

Use cases: syncing between local projects, testing migrations locally.

Sync Remote

Copy a database between two paths on the same remote system.

Same host, different path (or database):

origin:
  host: server.example.com
  user: deploy
  path: /var/www/live/LocalConfiguration.php
target:
  host: server.example.com
  user: deploy
  path: /var/www/staging/LocalConfiguration.php

Use cases: copying production to staging on the same server, refreshing a test environment.