Migrate to Sync Streams

Sync Streams do everything Sync Rules do, and more. A stream with auto_subscribe: true syncs when the client connects, the same way a bucket definition does, so apps that sync all relevant data upfront for offline use keep working the same way after migrating. The migration tool sets auto_subscribe: true on every generated stream, so no client-side changes are required when you first deploy.

Why Migrate?

Beyond matching Sync Rules, Sync Streams add:

More expressive queries: Stream queries support JOINs, CTEs, subqueries, and multiple queries per stream, with syntax closer to plain SQL. Parameter queries become inline subqueries, so you write one query instead of separate parameters: and data: blocks.
On-demand syncing: Define a stream once, then subscribe from your app one or more times with different parameters. Each subscription has its own lifecycle, so two screens or browser tabs can subscribe to the same stream independently. With Sync Rules, Client Parameters approximate this, but you have to aggregate the parameter values yourself across screens and tabs, and remove them when they are no longer needed.
Built-in caching: Each subscription has a configurable ttl that keeps data on the device after unsubscribing. When users return to a screen, the data is often already available.
Framework integration: React hooks, Vue composables, TanStack Query, and Kotlin Compose extensions let UI components manage subscriptions based on what is rendered.
Access to new features: Newer PowerSync Service features such as wildcard schemas and incremental reprocessing require Sync Streams.

You can migrate incrementally. Deploy the generated streams with auto_subscribe: true first, then convert individual streams to on-demand subscriptions where that benefits your app.

Requirements

PowerSync Service v1.20.0+ (Cloud instances already meet this)
Latest SDK versions with Rust-based sync client (enabled by default on latest SDKs)
config: edition: 3 in your Sync Config

Minimum SDK Versions
Enable Rust Client (older SDKs)

SDK	Minimum Version	Rust Client Default
JS Web	v1.27.0	v1.32.0
React Native	v1.25.0	v1.29.0
React hooks	v1.8.0	—
Node.js	v0.11.0	v0.16.0
Capacitor	v0.0.1	v0.3.0
Tauri	v0.0.1	Always (Rust client only)
Dart/Flutter	v1.16.0	v1.17.0
Kotlin	v1.7.0	v1.9.0
Swift	v1.11.0	v1.8.0
.NET	v0.0.8-alpha.1	v0.0.5-alpha.1

If you’re on an SDK version below the “Rust Client Default” version, enable the Rust client manually:JavaScript:

await db.connect(new MyConnector(), {
  clientImplementation: SyncClientImplementation.RUST
});

Dart:

database.connect(
  connector: YourConnector(),
  options: const SyncOptions(
    syncImplementation: SyncClientImplementation.rust,
  ),
);

Kotlin:

database.connect(MyConnector(), options = SyncOptions(
  newClientImplementation = true,
))

Swift:

import PowerSync

try await db.connect(connector: connector, options: ConnectOptions(
  newClientImplementation: true,
))

Migration Tool

You can generate a Sync Streams draft from your existing Sync Rules in two ways:

Dashboard: In the PowerSync Dashboard, use the Migrate to Sync Streams button. It converts your Sync Rules into a Sync Streams draft that you can review before deploying.
CLI: Run powersync migrate sync-rules to produce a Sync Streams draft from your current Sync Config.

The output uses auto_subscribe: true by default, preserving your existing sync-everything-upfront behavior so no client-side changes are required when you first deploy. Next steps: Review the draft, then deploy it (via the Dashboard or powersync deploy sync-config). After that, you can optionally migrate individual streams to on-demand subscriptions over time — remove auto_subscribe: true from specific streams and update client code to use the syncStream() API where it makes sense for your app.

Stream Definition Reference

config:
  edition: 3

streams:
  <stream_name>:
    # CTEs (optional) - define with block inside each stream
    with:
      <cte_name>: SELECT ... FROM ...

    # Behavior options (place above query/queries)
    auto_subscribe: true    # Auto-subscribe clients on connect (default: false)
    priority: 1             # Sync priority (optional). Lower number -> higher priority
    accept_potentially_dangerous_queries: true  # Silence security warnings (default: false)

    # Query options (use one)
    query: SELECT * FROM <table> WHERE ...         # Single query
    queries:                                       # Multiple queries
      - SELECT * FROM <table_a> WHERE ...
      - SELECT * FROM <table_b> WHERE ...

    

Option	Default	Description
`query`	—	SQL-like query defining which data to sync. Use either `query` or `queries`, not both. See Writing Queries.
`queries`	—	Array of queries defining which data to sync. More efficient than defining separate streams: the client manages one subscription and PowerSync merges the data from all queries (see Multiple Queries per Stream).
`with`	—	CTEs available to this stream’s queries. Define the `with` block inside each stream.
`auto_subscribe`	`false`	When `true`, clients automatically subscribe on connect.
`priority`	—	Sync priority (lower value = higher priority). See Prioritized Sync.
`accept_potentially_dangerous_queries`	`false`	Silences security warnings when queries use client-controlled parameters (i.e. connection parameters and subscription parameters), as opposed to authentication parameters that are signed as part of the JWT. Set to `true` only if you’ve verified the query is safe. See Using Parameters.

Migration Examples

Global Data (No Parameters)

In Sync Rules, a “global” bucket syncs the same data to all users. In Sync Streams, you achieve this with queries that have no parameters. Add auto_subscribe: true to maintain the Sync Rules behavior where data syncs automatically on connect. Sync Rules:

bucket_definitions:
  global:
    data:
      - SELECT * FROM todos
      - SELECT * FROM lists WHERE archived = false

Sync Streams:

config:
  edition: 3

streams:
  shared_data:
    auto_subscribe: true  # Sync automatically like Sync Rules
    queries:
      - SELECT * FROM todos
      - SELECT * FROM lists WHERE archived = false

Without auto_subscribe: true, clients would need to explicitly subscribe to these streams. This gives you flexibility to migrate incrementally or switch to on-demand syncing later.

User-Scoped Data

Sync Rules:

bucket_definitions:
  user_lists:
    priority: 1
    parameters: SELECT request.user_id() as user_id
    data:
      - SELECT * FROM lists WHERE owner_id = bucket.user_id

Sync Streams:

config:
  edition: 3

streams:
  user_lists:
    auto_subscribe: true
    priority: 1
    query: SELECT * FROM lists WHERE owner_id = auth.user_id()

Data with Subqueries (Replaces Parameter Queries)

Sync Rules:

bucket_definitions:
  owned_lists:
    parameters: |
      SELECT id as list_id FROM lists WHERE owner_id = request.user_id()
    data:
      - SELECT * FROM lists WHERE lists.id = bucket.list_id
      - SELECT * FROM todos WHERE todos.list_id = bucket.list_id

Sync Streams:

config:
  edition: 3

streams:
  owned_lists:
    auto_subscribe: true
    query: SELECT * FROM lists WHERE owner_id = auth.user_id()
  list_todos:
    query: |
      SELECT * FROM todos 
      WHERE list_id = subscription.parameter('list_id') 
        AND list_id IN (SELECT id FROM lists WHERE owner_id = auth.user_id())

Client Parameters → Subscription Parameters

Sync Rules used global Client Parameters:

bucket_definitions:
  posts:
    parameters: SELECT (request.parameters() ->> 'current_page') as page_number
    data:
      - SELECT * FROM posts WHERE page_number = bucket.page_number

Sync Streams use Subscription Parameters, which are more flexible — you can subscribe multiple times with different values:

config:
  edition: 3

streams:
  posts:
    query: SELECT * FROM posts WHERE page_number = subscription.parameter('page_number')

// Subscribe to multiple pages simultaneously
const page1 = await db.syncStream('posts', { page_number: 1 }).subscribe();
const page2 = await db.syncStream('posts', { page_number: 2 }).subscribe();

Parameter Syntax Changes

Sync Rules	Sync Streams
`request.user_id()`	`auth.user_id()`
`request.jwt() ->> 'claim'`	`auth.parameter('claim')`
`request.parameters() ->> 'key'`	`subscription.parameter('key')` (subscription parameter) or `connection.parameter('key')` (connection parameter)
`bucket.param_name`	Use the parameter directly in the query e.g. `subscription.parameter('key')`

Client-Side Changes

Streams generated by the migration tool with auto_subscribe: true need no client changes. When you convert a stream to on-demand syncing, replace connect-time parameters with a subscription:

// Before (Sync Rules with Client Parameters)
await db.connect(connector, {
  params: { current_project: projectId }
});

// After (Sync Streams with Subscriptions)
await db.connect(connector);
const sub = await db.syncStream('project_data', { project_id: projectId }).subscribe();

If you want to keep passing values at connect time instead, use connection parameters. See Client-Side Usage for detailed examples.

Get Started

Configuration Details

Sync Streams

Client SDKs

Handling Writes

Maintenance & Ops

Integrations

Tools

Resources

Migrate to Sync Streams

Why Migrate?

Requirements

Migration Tool

Stream Definition Reference

Migration Examples

Global Data (No Parameters)

User-Scoped Data

Data with Subqueries (Replaces Parameter Queries)

Client Parameters → Subscription Parameters

Parameter Syntax Changes

Client-Side Changes

​Why Migrate?

​Requirements

​Migration Tool

​Stream Definition Reference

​Migration Examples

​Global Data (No Parameters)

​User-Scoped Data

​Data with Subqueries (Replaces Parameter Queries)

​Client Parameters → Subscription Parameters

​Parameter Syntax Changes

​Client-Side Changes

Why Migrate?

Requirements

Migration Tool

Stream Definition Reference

Migration Examples

Global Data (No Parameters)

User-Scoped Data

Data with Subqueries (Replaces Parameter Queries)

Client Parameters → Subscription Parameters

Parameter Syntax Changes

Client-Side Changes