Skip to main content
There are two ways to update sync rules in a self-hosted deployment:
  1. Config file - Update your config and restart the service
  2. API endpoint - Deploy at runtime without restarting
During deployment, existing sync rules continue serving clients while new rules process. Clients seamlessly transition once initial replication completes.
Define sync rules in your powersync.yaml either inline or via a separate file. See Self-Hosted Instance Configuration for the full config reference and Sync Rules for syntax.
1

Edit Config

Update the sync_rules section in your powersync.yaml:
sync_rules:
  content: |
    bucket_definitions:
      global:
        data:
          - SELECT * FROM public.users
2

Restart Service

Restart your service to apply changes:
docker compose restart powersync
Once the service starts up, it will load the updated sync rules and begin processing them while continuing to serve existing rules until initial replication completes.

​
Option 2: Deploy via API

Deploy sync rules at runtime without restarting. Useful for quick iterations during development.
The API is disabled when sync rules are defined in powersync.yaml. Config file rules 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 Rules

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

EndpointMethodDescription
/api/sync-rules/v1/currentGETGet active and pending sync rules
/api/sync-rules/v1/reprocessPOSTRestart replication from scratch

​
Troubleshooting

Common errors when using the API:
Error CodeMeaning
PSYNC_S4105Sync rules defined in config file - API is disabled
PSYNC_S4104No sync rules deployed yet
PSYNC_R0001Invalid sync rules YAML - check details field
See Error Codes Reference for the complete list.