Add PowerSync DB Collection

[stevensJourney]

🎯 Changes

This PR adds a PowerSync integration for TanStack DB collections.

Special thanks to @KyleAMathews for his advice when developing the initial POC of this integration!

This PR integrates TanStackDB collections with the PowerSync synced SQLite database. TanStack DB collections are tied to the local synced SQLite tables with the help of collection builders. These collection builders link the TanStack collection state to the SQLite table via SQLite Trigger based diff tracking. Mutations made on TanStack DB collections are persisted to SQLite via PowerSyncTransactor, once persisted the PowerSync upload queue ensures changes are uploaded to a backend.

flowchart TB
    subgraph UI[UI Layer]
        UI_Component[UI Components]
    end

    subgraph TanStack[TanStack DB Layer]
        TS_Cache[In-Memory Cache]
        TS_Collections[TanStack Collections]
    end

    subgraph PowerSync[PowerSync Layer]
        PS_SQLite[Local SQLite DB]
        PS_Client[PowerSync Client]
    end

    subgraph Backend[Backend Infrastructure]
        Backend_App[Application Backend]
        PS_Service[PowerSync Service]
    end

    UI_Component -->|Mutations| TS_Collections
    TS_Cache -->|Updates| UI_Component

    TS_Collections -->|Persist| PS_SQLite
    PS_SQLite -->|Watch| TS_Cache

    PS_Client -->|Sync| PS_SQLite
    PS_SQLite -->|Changes| PS_Client
    PS_Client -->|Changes| Backend_App
    Backend_App -->|Apply| PS_Service
    PS_Service -->|Sync| PS_Client

    style UI fill:#f9f,stroke:#333,stroke-width:2px
    style TanStack fill:#bbf,stroke:#333,stroke-width:2px
    style PowerSync fill:#bfb,stroke:#333,stroke-width:2px
    style Backend fill:#fdb,stroke:#333,stroke-width:2px

Loading

Detailed examples are in the unit tests. The main flow is to:

Create a PowerSync SDK Client

const APP_SCHEMA = new Schema({
  users: new Table({
    name: column.text
  }),
  documents: new Table({
    name: column.text
  })
});

const db = new PowerSyncDatabase({
  database: {
    dbFilename: `test.sqlite`
  },
  schema: APP_SCHEMA
});

db.connect(connector);

Define TanStack DB collections using the database

const documentsCollection = createCollection(
  powerSyncCollectionOptions({
    database: db,
    table: APP_SCHEMA.props.documents
  })
);

Use the TanStack DB collections as one would any other collection

// Create a new item synchronously
const id = randomUUID();
const tx = documentsCollection.insert({
  id,
  name: `new`
});

// More advanced transactions can do this
const addTx = createTransaction({
  autoCommit: false,
  mutationFn: async ({ transaction }) => {
    await new PowerSyncTransactor({ database: db }).applyTransaction(transaction);
  }
});

addTx.mutate(() => {
  for (let i = 0; i < 5; i++) {
    documentsCollection.insert({ id: randomUUID(), name: `tx-${i}` });
    usersCollection.insert({ id: randomUUID(), name: `user` });
  }
});

✅ Checklist

• I have followed the steps in the Contributing guide.
  • This file does not seem to exist?
• I have tested this code locally with pnpm test:pr.
  • This script does not seem to exist?

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

[changeset-bot]

🦋 Changeset detected

Latest commit: 718c4f9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@tanstack/powersync-db-collection	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[stevensJourney]

Feel free to suggest alternatives for this. I've just used standard values we typically use at PowerSync.

[KyleAMathews]

serlization.ts → serialization.ts

It'd be simpler to keep everything MIT I think if that's ok with y'all. Apache is more heavy operationally vs MIT and I'd rather keep things simple.

[KyleAMathews]

Otherwise I think the PR is looking good!

[stevensJourney]

serlization.ts → serialization.ts

It'd be simpler to keep everything MIT I think if that's ok with y'all. Apache is more heavy operationally vs MIT and I'd rather keep things simple.

Thanks for the quick feedback! Our team is happy with MIT, we've made these changes :)

[KyleAMathews]

Ok great! I need to do the initial manual release locally for the "PR / Preview" CI job to pass so will do that a bit later today.

[pkg-pr-new]

More templates

• @tanstack/db-example-paced-mutations-demo
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• @tanstack/db-example-solid-todo
• todos

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@747

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@747

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@747

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@747

@tanstack/powersync-db-collection

npm i https://pkg.pr.new/@tanstack/powersync-db-collection@747

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@747

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@747

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@747

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@747

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@747

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@747

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@747

commit: 718c4f9

[KyleAMathews]

[KyleAMathews]

I'll merge the release PR in a bit — lemme know how you'd like help publicizing this!

[github-actions]

🎉 This PR has been released!

• @tanstack/powersync-db-collection@0.1.0

Thank you for your contribution!