Synching towards FlashQL on the browser.

[MirjamElad]

Hi again, I unfortunately couldn't find the time to test this promising library and I am unsure about some important details.

Here is the architectural pattern I want to implement for my webapp. React on the front end, HONO on the server and PostgreSQL as the database.
I want to use LinkedQL and FlashQL.
On the HONO server, I want a LinkedQL instance subscribing with queries to the the PostgreSQL database's WAL.
On the front end (i.e. living on the browser) I want a read-only in-memory FlashQL instance. The FlashQL would in turn subscribe to the HONO's LinkedQL.
Please help me answer these questions:
1- Does LinkedQL already handle automatic subscription between itself and FlashQL on the browser or do I have to manually create a custom transport layer between Hono and browser FlashQL (likely WebSocket with manual message passing of diffs).
2- Does FlashQL need any custom code to be configured to subscribe to the HONO's LinkedQL's end point?

Thank you again.

PS:
1- If not already implemented, would automatic synching between LinkedQL and FlashQL be implemented/facilitated-further in the future?
2- If such thing already exists could you please point me to how it is to be done!

[ox-harris]

Hey @MirjamElad — first off, apologies for the late response on this.
Your question actually came in right when I was deep in the latest major iteration of LinkedQL – the version that actually properly answers what you're asking. It’s now live BTW.

That said, what you're trying to build is exactly the kind of setup LinkedQL is meant for. Let me answer your questions directly and plainly.

---

Your architecture again is...

React (browser) → Hono (server) → PostgreSQL
FlashQL in the browser, LinkedQL in between

This is a solid setup. You’re not off at all.

But one important shift in thinking as to your approach is:

You don’t manually wire “subscriptions” between these layers.

LinkedQL abstracts that away.

---

1. So, do you need to build your own subscription layer?

No — you don’t need WebSockets, manual diffs, or anything like that.

What you do instead is:

Define what data you want locally (in the form of VIEWS inside FlashQL). Sync in LinkedQL is based on views:

await db.query(`
  CREATE VIEW public.orders AS
  SELECT * FROM public.orders
  WITH (replication_origin = '/api/db')
`);

The WITH (replication_origin = ... part is the part that turns a regular view into an upstream-backed view. For your use case, define it as a REALTIME view. These views materialize the upstream data locally and stay in sync with it:

await db.query(`
  CREATE REALTIME VIEW public.orders AS
  SELECT * FROM public.orders
  WITH (replication_origin = '/api/db')
`);

That’s it.

LinkedQL handles:

• initial data fetch
• subscribing to upstream changes
• replay if the client was offline
• keeping things in sync over time

So instead of thinking:

“how do I stream changes?”

Think:

“what data do I want locally?”

The whole story is here – in the new README

---

2. Does FlashQL need custom code to subscribe to your Hono server?

No custom subscription code.

You just expose LinkedQL on your server, and FlashQL knows how to talk to it.

On the Hono side

As shown in the new README, you expose a LinkedQL endpoint using EdgeWorker:

const worker = new EdgeWorker({ client: pgClient });

app.post('/db', async (c) => {
  const op = c.req.query('op');
  const args = await c.req.json();

  const result = await worker.handle(op, args);
  return c.json(result ?? {});
});

---

On the client side

You instantiate FlashQL with a way to reach the remote database:

const db = new FlashQL({
  async getUpstreamClient(originUrl) {
    return new EdgeClient({
      url: originUrl,
      type: 'http',
    });
  }
});

// It's at this point you define your views:
await db.query(`CREATE REALTIME VIEW ...`);

The architecture now becomes:

browser:                     db = new FlashQL({ getUpstreamClient: () => new EdgeClient({ url: '/api/db', type: 'http' }) }); // define your views for sync
server (/api/db):        EdgeWorker.http({ db: new PGClient })

For most use cases, you might want to run the FlashQL instance in a WebWorker or a SharedWorker and let your UI-side code connect to the FlashQL instance in the worker. This would look like this:

UI:                               db = new EdgeClient({ url: './db.js', type: 'shared_worker' })
worker (./db.js):         EdgeWorker.sharedWorker({ db: new FlashQL({ getUpstreamClient: () => new EdgeClient({ url: '/api/db', type: 'http' }) }) }) // define your views for sync
server (/api/db):        EdgeWorker.http({ db: new PGClient })

On the client side, db always behaves like your upstream PG client.

---

Where to look

Right now, the README is the most accurate reference (more than the docs site for this part).

Specifically:

• Section 1: Core Interface → db.sync.sync()
• Section 3: Architecture & Orchestration → the full local-first + sync flow

---

If you try this and something feels unclear in practice, share your setup — happy to walk through it with you. And yeah, I’ll be better on turnaround time going forward.

[ox-harris]

Hi again @MirjamElad , how's it going.
Was wondering if you had a chance to look through my reply. Made a few modifications to the API shape in there to reflect the current shape of the API.

The README also relfects that. Hoping that you find this good enough.