Easy Sync Executor

One-command data synchronization across services, databases, and file systems with automatic conflict detection and retry logic.

When to Use This Command

Run this command when...

• You need to synchronize data between two or more services and want a single invocation that handles the entire flow
• Your local database replica has drifted from the remote source and you need a clean, idempotent resync
• You want to push local file changes to a remote storage bucket or vice versa without writing custom scripts

Avoid this command when...

• You need fine-grained control over individual conflict resolution strategies (use Power Sync Conflict Resolver instead)
• You are synchronizing massive datasets that require streaming or chunked processing beyond default thresholds

Quick Start

Copy
# .sync-config.yaml
source: postgres://localhost:5432/app_db
target: postgres://prod-replica:5432/app_db
direction: bidirectional
conflict_strategy: last-write-wins
tables:
  - users
  - orders
  - inventory

Copy
claude -p "Sync my local database to the production replica using the config in .sync-config.yaml"

Expected output:
Sync started: postgres://localhost:5432/app_db -> postgres://prod-replica:5432/app_db
Tables scanned: 3 (users, orders, inventory)
Records compared: 14,207
Updates applied: 38 (12 users, 19 orders, 7 inventory)
Conflicts resolved: 2 (last-write-wins)
Sync completed in 4.2s

Core Concepts

Concept	Description
Sync Direction	Unidirectional pushes from source to target; bidirectional merges both ways
Conflict Strategy	Determines winner when both sides changed the same record (last-write-wins, source-wins, target-wins)
Idempotency	Running the same sync twice produces identical results with zero duplicate writes
Delta Detection	Only changed records transfer over the wire, minimizing bandwidth and execution time
Retry Logic	Transient failures trigger automatic retries with exponential backoff

Source DB          Sync Engine           Target DB
  [S] ----delta----> [Engine] ----apply----> [T]
  [S] <---delta----- [Engine] <---apply----- [T]
                        |
                   Conflict Log
                   (if detected)

Configuration

Parameter	Type	Default	Description	Example
direction	string	unidirectional	Sync flow direction	bidirectional
conflict_strategy	string	last-write-wins	How conflicting records resolve	source-wins
batch_size	number	1000	Records per sync batch	5000
retry_count	number	3	Max retries on transient failure	5
dry_run	boolean	false	Preview changes without applying	true

Best Practices

1. Always run with dry_run first -- Preview the sync diff before applying changes to production targets to avoid unintended overwrites.
2. Keep sync configs in version control -- Store .sync-config.yaml alongside your codebase so sync behavior is reproducible and auditable.
3. Use table allowlists -- Explicitly list tables rather than syncing everything; this prevents accidental exposure of sensitive tables.
4. Schedule off-peak execution -- Run large syncs during low-traffic windows to reduce lock contention and replication lag.
5. Monitor the conflict log -- Even with automatic resolution, review the conflict log periodically to identify systemic data integrity issues.

Common Issues

1. Connection timeout during large syncs -- Increase batch_size to reduce round trips or raise the database connection timeout. For very large tables, consider chunking by date range.
2. Duplicate records after bidirectional sync -- Ensure both databases use the same primary key strategy. UUID-based keys prevent collisions; auto-increment keys on separate databases will conflict.
3. Stale data after sync completes -- Verify that both source and target clocks are NTP-synchronized. Clock drift causes last-write-wins to pick the wrong record.