Migrate to Sync Streams

• Every generated stream has auto_subscribe: true, so clients keep syncing all their data when they connect, exactly as they do with Sync Rules.
• Client Parameters become connection parameters. Your app passes them the same way when it connects.
• Once your SDKs meet the minimum versions, no client-side code changes are needed.

​

Why Migrate?

• More expressive queries: Stream queries support JOINs, CTEs, subqueries, and multiple queries per stream, with syntax closer to plain SQL. 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. 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 incremental reprocessing require Sync Streams.

​

Requirements

• PowerSync Service v1.20.0+ (Cloud instances already meet this)
• An SDK version that supports Sync Streams (see table). Streams run on the Rust-based sync client, which is the default in current SDKs. If your version is between the two columns, enable it manually.
• config: edition: 3 in your Sync Config (the migration tool sets this)

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

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

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

import PowerSync

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

​

Migrate With the Migration Tool

​

What the Tool Generates

bucket_definitions:
  global:
    data:
      - SELECT * FROM categories
  user_lists:
    parameters: SELECT request.user_id() as user_id
    data:
      - SELECT * FROM lists WHERE owner_id = bucket.user_id
  list_todos:
    parameters: SELECT id as list_id FROM lists WHERE owner_id = request.user_id()
    data:
      - SELECT * FROM todos WHERE list_id = bucket.list_id
  page_posts:
    parameters: SELECT request.parameters() ->> 'page_number' as page_number
    data:
      - SELECT * FROM posts WHERE page_number = bucket.page_number

config:
  edition: 3
streams:
  migrated_to_streams:
    auto_subscribe: true
    with:
      list_todos_param: SELECT id AS list_id FROM lists WHERE owner_id = auth.user_id()
    queries:
      # Translated from "global" bucket definition.
      - SELECT * FROM categories
      # Translated from "user_lists" bucket definition.
      - SELECT * FROM lists WHERE owner_id = auth.user_id()
      # Translated from "list_todos" bucket definition.
      - "SELECT todos.* FROM todos,list_todos_param AS bucket WHERE todos.list_id = bucket.list_id"
      # Translated from "page_posts" bucket definition.
      - SELECT * FROM posts WHERE page_number = connection.parameter('page_number')

• Compatibility edition: It sets config: edition: 3, which Sync Streams require, and keeps any other options in your config block.
• One stream per priority: Bucket definitions with the same priority are merged into one stream named migrated_to_streams. Comments mark which bucket definition each group of queries came from. If your bucket definitions use different priorities, the tool creates one stream per priority, named migrated_to_streams_prio_<priority>.
• Same sync behavior: Every stream has auto_subscribe: true. Queries are always written as a queries: list so that you can add more.
• Parameters: request.* functions become auth.* and connection.* functions. See Parameter Syntax Changes for the full mapping. Parameter queries that only select request values, such as SELECT request.user_id() as user_id, are replaced by those values in the data queries: bucket.user_id becomes auth.user_id(). Parameter queries that read from a table become CTEs in a with: block, named <bucket_definition>_param, and the data queries join them under the alias bucket.
• Cleanup: The bucket_definitions: section is removed.

​

What to Check Before You Deploy

• Compatibility edition: If your Sync Rules had no edition set, edition: 3 also turns on the edition 2 fixes, such as ISO 8601 timestamp formatting and custom Postgres type handling. These change how some values look in the client database. See Compatibility for the full list. To keep the old behavior for a fix, set its option to false next to the edition:
  config:
    edition: 3
    timestamps_iso8601: false
  
• Queries the tool cannot convert: This is rare. When it happens, the tool stops and reports the query it could not parse. The Dashboard shows the error and its line in the validation panel, and the CLI prints it. Convert that bucket definition by hand using Parameter Syntax Changes, or ask on Discord.

​

Adopt Sync Streams Features

​

Split the Merged Stream

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

​

Replace Parameter CTEs With Subqueries

streams:
  list_todos:
    auto_subscribe: true
    query: SELECT * FROM todos WHERE list_id IN (SELECT id FROM lists WHERE owner_id = auth.user_id())

​

Sync Data On Demand

streams:
  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())

const sub = await db.syncStream('list_todos', { list_id: listId }).subscribe();
await sub.waitForFirstSync();

// When the screen closes
sub.unsubscribe();

​

Convert Connection Parameters to Subscription Parameters

streams:
  page_posts:
    auto_subscribe: true
    query: SELECT * FROM posts WHERE page_number = connection.parameter('page_number')

await db.connect(connector, {
  params: { page_number: 1 }
});

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

await db.connect(connector);

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

​

Parameter Syntax Changes

​

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 ...