Update Sync Streams (Sync Config)

How to update Sync Streams (or legacy Sync Rules) in a self-hosted PowerSync deployment

There are three ways to update your sync config in a self-hosted deployment:

1. CLI — Edit your config and apply with powersync docker reset
2. Config file — Update your config and restart the service
3. API endpoint — Deploy at runtime without restarting

During deployment, existing Sync Streams/Sync Rules continue serving clients while new sync config processes. Clients seamlessly transition once initial replication completes.

Run powersync validate in the CLI before deploying to catch errors in your sync config without applying changes.

Option 1: CLI

If you set up PowerSync using the CLI (powersync docker), update your sync config and apply it without a full service restart:

1. Edit Sync Config

   Update powersync/sync-config.yaml in your project directory.

2. Validate

   powersync validate
   
3. Apply

   powersync docker reset
   

   This restarts the PowerSync Service and applies your updated sync config.

Option 2: Config File

Define your sync config in powersync.yaml either inline or via a separate file. See Self-Hosted Instance Configuration for the full config reference.

1. Edit Config

   Update the sync_config: section in your powersync.yaml. The sync_config: key is used for both Sync Streams and Sync Rules:

   Sync Streams — Separate File (Recommended)

   sync_config:
     path: sync-config.yaml
   
2. Restart Service

   Restart your service to apply changes:

   docker compose restart powersync
   

   Once the service starts up, it will load the updated sync config and begin processing it while continuing to serve the existing config until initial replication completes.

Option 3: Deploy via API

Deploy sync config at runtime without restarting. Useful for quick iterations during development.

The API is disabled when Sync Streams (or legacy Sync Rules) are defined in powersync.yaml. Sync Streams (or legacy Sync Rules) defined in powersync.yaml always take precedence.

1. Configure API Token

   Add an API token to your powersync.yaml and restart:

   powersync.yaml

   api:
     tokens:
       - !env PS_API_TOKEN
   
2. Deploy Sync Streams

   curl -X POST http://<host>:<port>/api/sync-rules/v1/deploy \
        -H "Content-Type: application/yaml" \
        -H "Authorization: Bearer ${PS_API_TOKEN}" \
        -d @sync-rules.yaml
   

   Use /api/sync-rules/v1/validate first to check for errors without deploying.

Additional Endpoints

Endpoint	Method	Description
/api/sync-rules/v1/current	GET	Get active and pending Sync Streams / Sync Rules
/api/sync-rules/v1/reprocess	POST	Restart replication from scratch

Troubleshooting

Common errors when using the API:

Error Code	Meaning
PSYNC_S4105	Sync Streams / Sync Rules defined in config file - API is disabled
PSYNC_S4104	No Sync Streams / Sync Rules deployed yet
PSYNC_R0001	Invalid Sync Streams / Sync Rules YAML - check details field

See Error Codes Reference for the complete list.