> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powersync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Sync Streams (Sync Config)

> Update Sync Streams/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

<Info>
  During deployment, existing Sync Streams/Sync Rules continue serving clients while new sync config processes. Clients seamlessly transition once [initial replication](/architecture/powersync-service#initial-replication-vs-incremental-replication) completes.
</Info>

<Tip>
  Run `powersync validate` in the CLI before deploying to catch errors in your sync config without applying changes.
</Tip>

## 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:

<Steps>
  <Step title="Edit Sync Config">
    Update `powersync/sync-config.yaml` in your project directory.
  </Step>

  <Step title="Validate">
    ```bash theme={null}
    powersync validate
    ```
  </Step>

  <Step title="Apply">
    ```bash theme={null}
    powersync docker reset
    ```

    This restarts the PowerSync Service and applies your updated sync config.
  </Step>
</Steps>

## Option 2: Config File

Define your sync config in `service.yaml` either inline or via a separate file. See [Self-Hosted Instance Configuration](/configuration/powersync-service/self-hosted-instances) for the full config reference.

<Steps>
  <Step title="Edit Config">
    Update the `sync_config:` section in your `service.yaml`. The `sync_config:` key is used for both Sync Streams and Sync Rules:

    <CodeGroup>
      ```yaml Sync Streams — Separate File (Recommended) theme={null}
      sync_config:
        path: sync-config.yaml
      ```

      ```yaml Sync Streams — Inline theme={null}
      sync_config:
        content: |
          config:
            edition: 3
          streams:
            users:
              auto_subscribe: true
              query: SELECT * FROM public.users
      ```

      ```yaml Sync Rules — Separate File (Legacy) theme={null}
      sync_config:
        path: sync-config.yaml
      ```

      ```yaml Sync Rules — Inline (Legacy) theme={null}
      sync_config:
        content: |
          bucket_definitions:
            global:
              data:
                - SELECT * FROM public.users
      ```
    </CodeGroup>
  </Step>

  <Step title="Restart Service">
    Restart your service to apply changes:

    ```shell theme={null}
    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.
  </Step>
</Steps>

## Option 3: Deploy via API

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

<Warning>
  The API is disabled when Sync Streams (or legacy Sync Rules) are defined in `service.yaml`.
  Sync Streams/Sync Rules defined in `service.yaml` always take precedence.
</Warning>

<Steps>
  <Step title="Configure API Token">
    Add an API token to your `service.yaml` and restart:

    ```yaml service.yaml theme={null}
    api:
      tokens:
        - !env PS_API_TOKEN
    ```
  </Step>

  <Step title="Deploy Sync Streams">
    ```shell theme={null}
    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.
  </Step>
</Steps>

### 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](/debugging/error-codes) for the complete list.