Local-Only Usage

Some apps need to store data before the user registers or signs in. Some of these users register later and start syncing their data with other devices or users. Others keep using the app without registering or going online. By default, the client SDK places every local write in the upload queue. When the user registers and the app connects, the client SDK uploads these writes to your backend. If the user never registers, the upload queue keeps growing. In many apps the queue stays small, but data-intensive apps can avoid this growth with one of these approaches:

Local-only tables: Store data in tables that do not record writes in the upload queue. Copy the data to synced tables when the user registers.
Clearing the upload queue: Store data in synced tables and delete the upload queue periodically.

Local-Only Tables

The client SDK does not place writes to local-only tables in the upload queue, so the queue does not grow. Store data in local-only tables until the user registers or signs in. To define a local-only table, mark it as local-only in your client schema:

import { column, Schema, Table } from '@powersync/web'; // Or @powersync/react-native, @powersync/node

const local_lists = new Table(
  {
    created_at: column.text,
    name: column.text
  },
  { localOnly: true }
);

export const AppSchema = new Schema({
  local_lists
});

import 'package:powersync/powersync.dart';

const schema = Schema([
  Table.localOnly('local_lists', [
    Column.text('created_at'),
    Column.text('name'),
  ]),
]);

import com.powersync.db.schema.Column
import com.powersync.db.schema.Schema
import com.powersync.db.schema.Table

val AppSchema: Schema = Schema(
  listOf(
    Table(
      name = "local_lists",
      columns = listOf(
        Column.text("created_at"),
        Column.text("name")
      ),
      localOnly = true
    )
  )
)

import PowerSync

let localLists = Table(
  name: "local_lists",
  columns: [
    Column.text("created_at"),
    Column.text("name")
  ],
  localOnly: true
)

let AppSchema = Schema(localLists)

using PowerSync.Common.DB.Schema;
using PowerSync.Common.DB.Schema.Attributes;

[Table("local_lists", LocalOnly = true)]
public class LocalList
{
    // Attribute-based schema requires an explicit id; other syntaxes define an implicit id key. Learn more in the .NET SDK reference.
    [Column("id")]
    public string Id { get; set; }

    [Column("created_at")]
    public string CreatedAt { get; set; }

    [Column("name")]
    public string Name { get; set; }
}

public static class AppSchema
{
    public static Schema PowerSyncSchema = new Schema(typeof(LocalList));
}

use powersync::schema::{Column, Schema, Table};

pub fn app_schema() -> Schema {
    let mut schema = Schema::default();
    let local_lists = Table::create(
        "local_lists",
        vec![Column::text("created_at"), Column::text("name")],
        |tbl| tbl.options.local_only = true,
    );
    schema.tables.push(local_lists);
    schema
}

Moving Data to Synced Tables

Define each local-only table and its synced counterpart as separate tables in your schema, for example local_lists and lists. When the user registers or signs in, run these statements in one write transaction:

INSERT INTO lists(id, created_at, name, owner_id)
  SELECT id, created_at, name, ? FROM local_lists;
DELETE FROM local_lists;

The ? parameter sets owner_id to the ID of the signed-in user. The inserts place the rows in the upload queue, and the client SDK uploads them to your backend.

Keep the local-only table and the synced table separate. If you change an existing table from local-only to synced, or remove or rename a local-only table in your schema, the client SDK deletes that table and its data when the app applies the new schema. This data cannot be recovered.

To keep the same table name in app queries before and after registration, use the viewName option:

Before registration, set the view name of the local-only table to lists. Give the synced table an unused view name, such as inactive_synced_lists.
When the user registers, update the schema so that the synced table uses the view name lists. Give the local-only table an unused view name, such as inactive_local_lists.
Copy the data with the statements above. Replace local_lists with inactive_local_lists in both statements.

These example apps implement this approach with updateSchema():

Client framework	Link
React To-Do List App (with Supabase)	react-supabase-todolist-optional-sync
Flutter To-Do List App (with Supabase)	supabase-todolist-optional-sync

If you use Drift with local-only tables that override viewName, Drift’s watch streams may not update. See the Drift troubleshooting guide for the fix.

Clearing the Upload Queue

If you store data in synced tables, you can delete the upload queue periodically, for example on every app start:

DELETE FROM ps_crud

The client SDK does not upload the deleted writes when the user registers. Your app must upload this data itself, for example by reading it from the tables and sending it to your backend. The client SDK also stores one entry in the ps_updated_rows table for each row written locally. Do not delete these entries. When the app syncs, the client SDK uses them to find local rows that are missing from the synced data and removes those rows. Without these entries, such rows stay on the device. If this overhead is too large for your app, use local-only tables instead.

Local-Only Columns on Synced Tables

To store individual local-only columns on a table that otherwise syncs, use raw tables.

Get Started

Configuration Details

Sync Streams

Client SDKs

Handling Writes

Maintenance & Ops

Integrations

Tools

Resources

Local-Only Tables

Moving Data to Synced Tables

Clearing the Upload Queue

Local-Only Columns on Synced Tables

​Local-Only Tables

​Moving Data to Synced Tables

​Clearing the Upload Queue

​Local-Only Columns on Synced Tables

Local-Only Tables

Moving Data to Synced Tables

Clearing the Upload Queue

Local-Only Columns on Synced Tables