Skip to content

New Sync Streams navigration #640

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
benitav wants to merge 1 commit into
base: main
Choose a base branch
from
Open

New Sync Streams navigration #640

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion configuration/app-backend/client-side-integration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ After you've [instantiated](/intro/setup-guide#instantiate-the-powersync-databas

| Purpose | Description |
|---------|-------------|
| **Uploading mutations to your backend:** | Mutations that are made to the client-side SQLite database are uploaded to your backend application, where you control how they're applied to your backend source database (Postgres, MongoDB, MySQL, SQL Server, or Convex). This is how PowerSync achieves bi-directional syncing of data: The [PowerSync Service](/architecture/powersync-service) provides the _server-to-client read path_ based on your [Sync Streams or Sync Rules (legacy)](/sync/overview), and the _client-to-server write path_ goes via your backend. |
| **Uploading mutations to your backend:** | Mutations that are made to the client-side SQLite database are uploaded to your backend application, where you control how they're applied to your backend source database (Postgres, MongoDB, MySQL, SQL Server, or Convex). This is how PowerSync achieves bi-directional syncing of data: The [PowerSync Service](/architecture/powersync-service) provides the _server-to-client read path_ based on your [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)), and the _client-to-server write path_ goes via your backend. |
| **Authentication integration:** (optional) | PowerSync uses JWTs for authentication between the Client SDK and PowerSync Service. Some [authentication providers](/configuration/auth/overview#common-authentication-providers) generate JWTs for users which PowerSync can verify directly. For others, some code must be [added to your application backend](/configuration/auth/custom) to generate the JWTs. |


Expand Down
2 changes: 1 addition & 1 deletion configuration/source-db/postgres-maintenance.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: "Manage Postgres replication slots and WAL lag for reliable PowerSy

Postgres logical replication slots are used to keep track of [replication](/architecture/powersync-service#replication-from-the-source-database) progress (recorded as a [LSN](https://www.postgresql.org/docs/current/datatype-pg-lsn.html)).

Every time a new version of [Sync Streams or Sync Rules](/sync/overview) is deployed, PowerSync creates a new replication slot. Once the new version is fully processed, PowerSync switches to use the new slot and deletes the old one. The Service logs these steps and, during a snapshot, how much WAL budget remains. See [Postgres Replication Slots and WAL Budget](/debugging/log-reference#postgres-replication-slots-and-wal-budget) in the Log Reference.
Every time a new version of [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)) is deployed, PowerSync creates a new replication slot. Once the new version is fully processed, PowerSync switches to use the new slot and deletes the old one. The Service logs these steps and, during a snapshot, how much WAL budget remains. See [Postgres Replication Slots and WAL Budget](/debugging/log-reference#postgres-replication-slots-and-wal-budget) in the Log Reference.

The replication slots can be viewed using this query:

Expand Down
2 changes: 1 addition & 1 deletion debugging/error-codes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,17 @@

This reference documents PowerSync error codes organized by component, with troubleshooting suggestions for developers. Use the search bar to look up specific error codes (e.g., `PSYNC_R0001`).

## PSYNC_Rxxxx: Sync Config issues

Check warning on line 9 in debugging/error-codes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

debugging/error-codes.mdx#L9 

Did you really mean 'PSYNC_Rxxxx'?

- **PSYNC_R0001**:
Catch-all [Sync Config](/sync/overview) parsing error, if no more specific error is available
Catch-all [Sync Config](/sync/streams/quickstart#defining-streams) parsing error, if no more specific error is available

@claude claude Bot Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This error code is a catch-all for "Sync Config" parsing, which still covers legacy Sync Rules configs too (see the many generic "Sync Config" mentions elsewhere on this page). Linking "Sync Config" to the Sync-Streams-only Quickstart section sends Sync Rules readers hitting this error to content that doesn't apply to their config format. Consider linking to a page/section that covers Sync Config generally, or to the Sync Streams and Sync Rules overview pages separately.


- **PSYNC_R2201**:
A table or schema wildcard (`%`) is not supported by the configured source connector.

Wildcard support is connector-specific. For example, SQL Server requires exact table and schema names, while some other connectors support table wildcards but not schema wildcards.

## PSYNC_Sxxxx: Service issues

Check warning on line 19 in debugging/error-codes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (powersync) - vale-spellcheck

debugging/error-codes.mdx#L19 

Did you really mean 'PSYNC_Sxxxx'?

- **PSYNC_S0001**:
Internal assertion.
Expand Down
61 changes: 32 additions & 29 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,42 +183,23 @@
]
},
{
"group": "Sync Streams & Rules",
"group": "Sync Streams",
"icon": "arrows-rotate",
"pages": [
"sync/overview",
{
"group": "Sync Streams",
"pages": [
"sync/streams/overview",
"sync/streams/parameters",
"sync/streams/queries",
"sync/streams/ctes",
"sync/streams/bucket-count",
"sync/streams/examples",
"sync/streams/client-usage",
"sync/streams/migration"
]
},
{
"group": "Sync Rules (Legacy)",
"pages": [
"sync/rules/overview",
"sync/rules/organize-data-into-buckets",
"sync/rules/global-buckets",
"sync/rules/parameter-queries",
"sync/rules/data-queries",
"sync/rules/many-to-many-join-tables",
"sync/rules/client-parameters"
]
},
"sync/streams/overview",
"sync/streams/quickstart",
"sync/streams/parameters",
"sync/streams/queries",
"sync/streams/ctes",
"sync/streams/bucket-count",
"sync/streams/client-usage",
"sync/types",
"sync/streams/examples",
{
"group": "Supported SQL",
"pages": [
"sync/supported-sql",
"sync/grammar/sync-streams/index",
"sync/grammar/sync-rules/index"
"sync/grammar/sync-streams/index"
]
},
{
Expand All @@ -237,6 +218,20 @@
"sync/advanced/partitioned-tables",
"sync/advanced/sharded-databases"
]
},
{
"group": "Sync Rules (Legacy)",
"pages": [
"sync/rules/migrate-to-sync-streams",
"sync/rules/overview",
"sync/rules/organize-data-into-buckets",
"sync/rules/global-buckets",
"sync/rules/parameter-queries",
"sync/rules/data-queries",
"sync/rules/many-to-many-join-tables",
"sync/rules/client-parameters",
"sync/grammar/sync-rules/index"
]
}
]
},
Expand Down Expand Up @@ -784,6 +779,14 @@
"source": "/usage/sync-streams",
"destination": "/sync/streams/overview"
},
{
"source": "/sync/overview",
"destination": "/sync/streams/overview"
},
{
"source": "/sync/streams/migration",
"destination": "/sync/rules/migrate-to-sync-streams"
},
{
"source": "/usage/sync-rules/types",
"destination": "/sync/types"
Expand Down
2 changes: 1 addition & 1 deletion snippets/binary-type.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
<Note>
Binary data can be accessed in the Sync Streams / Sync Rules, but cannot be used as [parameters](/sync/overview#how-it-works). To sync binary columns/fields to clients, those columns need to be converted to hex or base64 representation using the relevant [functions](/sync/supported-sql#functions).
Binary data can be accessed in Sync Streams, but cannot be used as [parameters](/sync/streams/parameters). To sync binary columns/fields to clients, those columns need to be converted to hex or base64 representation using the relevant [functions](/sync/supported-sql#functions).

@claude claude Bot Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This snippet is also included on sync/types.mdx, a page that still serves legacy Sync Rules users (type mapping applies to both). Dropping the Sync Rules mention and pointing "parameters" only at /sync/streams/parameters means Sync Rules readers lose an accurate cross-reference (Sync Rules parameters work differently, via client parameters). Consider keeping a Sync Rules mention here, e.g. "Binary data can be accessed in Sync Streams (or legacy Sync Rules), but cannot be used as parameters," with a link that covers both, or two links.

Suggested change
Binary data can be accessed in Sync Streams, but cannot be used as [parameters](/sync/streams/parameters). To sync binary columns/fields to clients, those columns need to be converted to hex or base64 representation using the relevant [functions](/sync/supported-sql#functions).
Binary data can be accessed in Sync Streams (or legacy Sync Rules), but cannot be used as a parameter (see [Sync Streams parameters](/sync/streams/parameters) or [Sync Rules client parameters](/sync/rules/client-parameters)). To sync binary columns/fields to clients, those columns need to be converted to hex or base64 representation using the relevant [functions](/sync/supported-sql#functions).

</Note>
2 changes: 1 addition & 1 deletion sync/advanced/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Advanced Topics"
description: "Advanced Sync Streams and Sync Rules topics."
description: "Advanced Sync Streams topics."

@claude claude Bot Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This description now says these are Sync Streams-only topics, but several pages linked from this index (prioritized-sync, sync-data-by-time, partitioned-tables, sharded-databases, multiple-client-versions, compatibility, case-sensitivity) still document legacy Sync Rules behavior in depth, including parallel "Sync Rules (Legacy)" tabs. Consider restoring a mention of Sync Rules here so the description matches the actual page content.

sidebarTitle: Overview
---

Expand Down
2 changes: 1 addition & 1 deletion sync/advanced/storage-version-4.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ The PowerSync Cloud and self-hosted columns below apply during the Beta only. On
| Incremental reprocessing | MongoDB | Sync Streams | Included with version 4 | Included with version 4 |
| S3 object storage | Any | Sync Streams or Sync Rules | Enabled per instance by PowerSync on request | [Set up S3 object storage](#self-hosted-s3-setup) |

Incremental reprocessing for Postgres and other source databases is planned. See the [proposal](https://github.com/orgs/powersync-ja/discussions/349) for background. It is not supported for legacy [Sync Rules](/sync/rules/overview). If you still use Sync Rules, [migrate to Sync Streams](/sync/streams/migration).
Incremental reprocessing for Postgres and other source databases is planned. See the [proposal](https://github.com/orgs/powersync-ja/discussions/349) for background. It is not supported for legacy [Sync Rules](/sync/rules/overview). If you still use Sync Rules, [migrate to Sync Streams](/sync/rules/migrate-to-sync-streams).

## Opt In

Expand Down
2 changes: 1 addition & 1 deletion sync/grammar/sync-streams/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: "Grammar Reference (Sync Streams)"
title: "Grammar Reference"
description: "Railroad diagram reference for the SQL grammar supported in Sync Streams queries."
---

Expand Down
90 changes: 0 additions & 90 deletions sync/overview.mdx
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion sync/rules/client-parameters.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ PowerSync already supports using **token parameters** in parameter queries. An e
<Tip>
[Sync Streams](/sync/streams/overview) make it easier to manage dynamic parameters, especially for apps where parameters are managed across different UI components and tabs. Sync Streams offer _subscription parameters_ (specified when subscribing to a stream) and _connection parameters_ (the equivalent of client parameters).

We recommend Sync Streams for new projects, and [migrating](/sync/streams/migration) existing projects.
We recommend Sync Streams for new projects, and [migrating](/sync/rules/migrate-to-sync-streams) existing projects.
</Tip>

### Usage
Expand Down
Loading
Loading