What's changing: A new validation check added to the Sync Streams compiler (from_sql.ts) throws an explicit error for any query containing a JOIN clause — "JOIN clauses are not currently supported in Sync Streams. They silently sync zero rows when the source table is aliased." This replaces two previous failure modes: silent zero-row syncing when the source table is aliased, and a generic "Must SELECT from a single table" error for other JOIN variants. The error points users toward a subquery rewrite as the alternative.
High priority — existing docs are now inaccurate or incomplete
-
Writing Queries (https://docs.powersync.com/sync/streams/queries) — The "Using Joins" section documents INNER JOIN as a supported Sync Streams feature with multiple working examples including basic joins, multiple chained joins, and self-joins with aliases. If this PR is merged, all of these examples would throw the new "JOIN clauses are not currently supported" error. Confirmed in sync/streams/queries.mdx.
-
Supported SQL (https://docs.powersync.com/sync/supported-sql) — The "JOIN Syntax" section explicitly defines valid Sync Streams JOIN patterns (inner joins only, single output table, equality conditions) and shows a working example: SELECT comments.* FROM comments INNER JOIN issues ON comments.issue_id = issues.id. This section would document syntax that now throws an error at compile time. Confirmed in sync/supported-sql.mdx.
-
Examples, Patterns & Demos (https://docs.powersync.com/sync/streams/examples) — The "Hierarchical Data" and "Many-to-Many Relationships" sections present INNER JOIN queries as equivalent alternatives to nested subqueries, with the explicit statement "Sync Streams support INNER JOINs." These examples and the surrounding prose would be wrong. Confirmed in sync/streams/examples.mdx.
-
Neon integration guide (https://docs.powersync.com/integrations/neon) — Contains an INNER JOIN example in a Sync Streams config block: SELECT paragraphs.* FROM paragraphs INNER JOIN notes ON notes.id = paragraphs.note_id WHERE notes.owner_id = auth.user_id(). Confirmed in integrations/neon.mdx.
-
Supabase integration guide (https://docs.powersync.com/integrations/supabase/guide) — Contains an INNER JOIN example in a Sync Streams config block: SELECT todos.* FROM todos INNER JOIN lists ON todos.list_id = lists.id WHERE lists.owner_id = auth.user_id(). Confirmed in integrations/supabase/guide.mdx.
For reviewer consideration — may be worth documenting
This PR is from an external contributor and has had no maintainer review as of filing. The PR's central premise — "JOIN clauses are not currently supported in Sync Streams" — conflicts directly with the current docs, which have a dedicated "Using Joins" section, a "JOIN Syntax" reference, and JOIN examples across integration guides. Before any docs update, maintainers need to determine whether: (a) the documented JOIN patterns actually work correctly and the PR is too broad — the real bug is only in the aliased-source-table pattern (variants A and D in the PR's test matrix, where the join causes silent zero-row syncing), and non-aliased INNER JOIN queries work as documented; or (b) JOINs have never worked correctly in Sync Streams and the docs have been wrong. That determination decides whether the PR needs narrowing, rejection, or whether the docs need correction. It cannot be resolved from the PR text alone.
Source PR: powersync-ja/powersync-service#662. At the time of filing, the PR is open. Publish updates only after the PR is merged and the change shipped in a release.
Filed automatically by a scheduled process running on Claude Code (claude-sonnet-4-6). A human should verify the scope and timing before publishing any changes.
What's changing: A new validation check added to the Sync Streams compiler (
from_sql.ts) throws an explicit error for any query containing a JOIN clause — "JOIN clauses are not currently supported in Sync Streams. They silently sync zero rows when the source table is aliased." This replaces two previous failure modes: silent zero-row syncing when the source table is aliased, and a generic "Must SELECT from a single table" error for other JOIN variants. The error points users toward a subquery rewrite as the alternative.High priority — existing docs are now inaccurate or incomplete
Writing Queries (https://docs.powersync.com/sync/streams/queries) — The "Using Joins" section documents INNER JOIN as a supported Sync Streams feature with multiple working examples including basic joins, multiple chained joins, and self-joins with aliases. If this PR is merged, all of these examples would throw the new "JOIN clauses are not currently supported" error. Confirmed in
sync/streams/queries.mdx.Supported SQL (https://docs.powersync.com/sync/supported-sql) — The "JOIN Syntax" section explicitly defines valid Sync Streams JOIN patterns (inner joins only, single output table, equality conditions) and shows a working example:
SELECT comments.* FROM comments INNER JOIN issues ON comments.issue_id = issues.id. This section would document syntax that now throws an error at compile time. Confirmed insync/supported-sql.mdx.Examples, Patterns & Demos (https://docs.powersync.com/sync/streams/examples) — The "Hierarchical Data" and "Many-to-Many Relationships" sections present INNER JOIN queries as equivalent alternatives to nested subqueries, with the explicit statement "Sync Streams support
INNER JOINs." These examples and the surrounding prose would be wrong. Confirmed insync/streams/examples.mdx.Neon integration guide (https://docs.powersync.com/integrations/neon) — Contains an INNER JOIN example in a Sync Streams config block:
SELECT paragraphs.* FROM paragraphs INNER JOIN notes ON notes.id = paragraphs.note_id WHERE notes.owner_id = auth.user_id(). Confirmed inintegrations/neon.mdx.Supabase integration guide (https://docs.powersync.com/integrations/supabase/guide) — Contains an INNER JOIN example in a Sync Streams config block:
SELECT todos.* FROM todos INNER JOIN lists ON todos.list_id = lists.id WHERE lists.owner_id = auth.user_id(). Confirmed inintegrations/supabase/guide.mdx.For reviewer consideration — may be worth documenting
This PR is from an external contributor and has had no maintainer review as of filing. The PR's central premise — "JOIN clauses are not currently supported in Sync Streams" — conflicts directly with the current docs, which have a dedicated "Using Joins" section, a "JOIN Syntax" reference, and JOIN examples across integration guides. Before any docs update, maintainers need to determine whether: (a) the documented JOIN patterns actually work correctly and the PR is too broad — the real bug is only in the aliased-source-table pattern (variants A and D in the PR's test matrix, where the join causes silent zero-row syncing), and non-aliased INNER JOIN queries work as documented; or (b) JOINs have never worked correctly in Sync Streams and the docs have been wrong. That determination decides whether the PR needs narrowing, rejection, or whether the docs need correction. It cannot be resolved from the PR text alone.
Source PR: powersync-ja/powersync-service#662. At the time of filing, the PR is open. Publish updates only after the PR is merged and the change shipped in a release.
Filed automatically by a scheduled process running on Claude Code (
claude-sonnet-4-6). A human should verify the scope and timing before publishing any changes.