Sync Streams (Early Alpha)

​

Motivation

1. On-demand syncing: You define Sync Streams on the PowerSync Service, and a client can then subscribe to them one or more times with different parameters.
2. Temporary caching-like behavior: Each subscription includes a configurable ttl that keeps data active after your app unsubscribes, acting as a warm cache for recently accessed data.
3. Simpler developer experience: Simplified syntax and mental model, and capabilities such as your UI components automatically managing subscriptions (for example, React hooks).

​

Requirements for Using Sync Streams

• v1.15.0 of the PowerSync Service (Cloud instances are already on this version)
• Minimum SDK versions:
  • JS:
    • Web: v1.27.0
    • React Native: v1.25.0
    • React hooks: v1.8.0
  • Dart: v1.16.0
  • Kotlin: v1.7.0
  • Swift: Coming soon.
• Use of the Rust-based sync client

  Show instructions

  • JS
  • Dart
  • Kotlin
  • Swift

  In JavaScript SDKs, pass the clientImplementation option when connecting:

  Copy

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

  You can migrate back to the JavaScript client later by removing the option.
• Sync Stream definitions. They are currently defined in the same YAML file as Sync Rules: sync_rules.yaml (PowerSync Cloud) or config.yaml (Open Edition/self-hosted). To enable Sync Streams, add the following configuration:
  sync_rules.yaml

  Copy

  config:
    # see https://docs.powersync.com/usage/sync-rules/compatibility
    # this edition also deploys several backwards-incompatible fixes
    # see the docs for details
    edition: 2
  
  streams:
    ... # see 'Stream Definition Syntax' section below
  

​

Stream Definition Syntax

streams:
  <stream_name>:
    query: string # similar to Data Queries in Sync Rules, but also support limited subqueries.
    auto_subscribe: boolean # true to subscribe to this stream by default (similar to how Sync Rules work), false (default) if clients should explicitly subscribe.
    priority: number # sync priority, same as in Sync Rules: https://docs.powersync.com/usage/use-case-examples/prioritized-sync
    accept_potentially_dangerous_queries: boolean # silence warnings on dangerous queries, same as in Sync Rules.

config:
  edition: 2
streams:
  issue: # Define a stream to a specific issue
    query: select * from issues where id = subscription.parameters() ->> 'id' 
  issue_comments: # Define a stream to a specific issue's comments
    query: select * from comments where issue_id = subscription.parameters() ->> 'id' 

​

Just Queries with Subqueries

# use parameters directly in the query (see below for details on accessing parameters)
select * from issues where id = subscription.parameters() ->> 'id' and owner_id = auth.user_id()

# "in (subquery)" replaces parameter queries:
select * from comments where issue_id in (select id from issues where owner_id = auth.user_id())

​

Accessing Parameters

subscription.parameters() # all parameters for the subscription, as JSON
subscription.parameter('key') # shorthand for getting a single specific parameter

auth.parameters() # JWT token payload, as JSON
auth.parameter('key') # short-hand for getting a single specific token payload parameter
auth.user_id() # same as auth.parameter('sub')

connection.parameters() # all parameters for the connection, as JSON
connection.parameter('key') # shorthand for getting a single specific parameter

​

Usage Examples: Sync Rules vs Sync Streams

  bucket_definitions:
    global:
        data:
        # Sync all todos
        - SELECT * FROM todos
        # Sync all lists except archived ones
        - SELECT * FROM lists WHERE archived = false

  streams:
    all_todos:
        query: SELECT * FROM todos
        auto_subscribe: true 
    unarchived_lists:
        query: SELECT * FROM lists WHERE archived = false
        auto_subscribe: true     

  bucket_definitions:
    user_lists:
        priority: 1 # See https://docs.powersync.com/usage/use-case-examples/prioritized-sync  
        parameters: SELECT request.user_id() as user_id
        data:
        - SELECT * FROM lists WHERE owner_id = bucket.user_id

  streams:
    user_lists:
        priority: 1 # See https://docs.powersync.com/usage/use-case-examples/prioritized-sync  
        query: SELECT * FROM lists WHERE owner_id = auth.user_id()

  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

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

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

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

  streams:
    todos:
        # Select specific columns
        query: SELECT id, name, owner_id FROM todos 
        # Rename columns
        query: SELECT id, name, created_timestamp AS created_at FROM todos 
        # Cast number to text
        query: SELECT id, item_number :: text AS item_number FROM todos
        # Alternative syntax for the same cast
        query: id, CAST(item_number as TEXT) AS item_number FROM todos
        # Convert binary data (bytea) to base64
        query: id, base64(thumbnail) AS thumbnail_base64 FROM todos
        # Extract field from JSON or JSONB column
        query: id, metadata_json ->> 'description' AS description FROM todos
        # Convert time to epoch number
        query: id, unixepoch(created_at) AS created_at FROM todos

​

Client-Side Syntax

• Use db.syncStream(name, [subscription-params]) to get a SyncStream instance.
• Call subscribe() on a SyncStream to get a SyncStreamSubscription. This gives you access to waitForFirstSync() and unsubscribe().
• Inspect SyncStatus for a list of SyncSubscriptionDefinitions describing all Sync Streams your app is subscribed to (either due to an explicit subscription or because the Sync Stream has auto_subscribe: true). It also reports per-stream download progress.
• Each Sync Stream has a ttl (time-to-live). After you call unsubscribe(), or when the page/app closes, the stream keeps syncing for the ttl duration, enabling caching-like behavior. Each SDK lets you specify the ttl, or ignore the ttl and delete the data as soon as possible. If not specified, a default TTL of 24 hours applies.

const sub = await powerSync.syncStream('issues', {id: 'issue-id'}).subscribe(ttl: 3600);

// Resolve current status for subscription
const status = powerSync.currentStatus.forStream(sub);
const progress = status?.progress;

// Wait for this subscription to have synced
await sub.waitForFirstSync();

// When the component needing the subscription is no longer active...
sub.unsubscribe();

const stream = useSyncStream({ name: 'todo_list', parameters: { list: 'foo' } });
// Can then check for download progress or subscription information
stream?.progress;
stream?.subscription.hasSynced;

const results = useQuery(
  'SELECT ...',
  queryParameters,
  // This will wait for the stream to sync before running the query
  { streams: [{ name: 'todo_list', parameters: { list: 'foo' }, waitForStream: true }] }
);

​

Example

​

Dart

config:
  edition: 2
streams:
  lists:
    query: SELECT * FROM lists
    auto_subscribe: true
  todos:
    query: SELECT * FROM todos WHERE list_id = subscription.parameter('list')

• The app syncs lists by default (demonstrating equivalent behavior to Sync Rules, i.e. optimized for offline-first).
• The app syncs todos on demand when a user opens a list.
• When the user navigates back to the same list, they won’t see a loading state — demonstrating caching behavior.

​

JS

​

Kotlin