convex-backend: Convex Turns Every Database Query Into a Live Subscription

The open-source backend records exactly what each query reads, so your UI updates without cache invalidation. Here is how the read-set tracking actually works.

8 min read • View on GitHub • More from convex

A wide editorial illustration of a vast reading room where a single reader sits at a desk with a stack of open books while a mechanical scribe arm writes in a ledger beside them. Thin taut strings run from the reader's hands to specific shelves across the room, and a small bell hangs above the desk ready to ring when a shelf is disturbed. The scene encodes how a Convex query reads documents while the backend records every read in a journal, then re-runs the query only when a tracked shelf changes.
A query as a standing subscription: the reader pulls books, the scribe records which ones, and the bell rings only when a recorded shelf is disturbed.
Key Takeaways

The Receipt Behind Every Query

In most databases a query is a one-shot deal. You ask for rows, you get rows, and the transaction closes. If the data changes a second later, nothing tells you. That gap is why application code grows a second nervous system: caches, polling loops, websocket channels, and the invalidation logic tying them together.

Convex queries do something stranger. When a query runs, the backend returns the result and a serialized record of everything the query touched: which documents it read, which index ranges it scanned. The type in the open-source Rust tree is called SerializedQueryJournal, and it travels back to the client alongside the data.

That manifest is the whole trick. A normal database returns rows. Convex returns rows plus a receipt listing every shelf the query pulled from.

import { query } from "./_generated/server";
import { v } from "convex/values";

export const listMessages = query({
  args: { channel: v.string() },
  handler: async (ctx, args) => {
    return await ctx.db
      .query("messages")
      .withIndex("by_channel", (q) => q.eq("channel", args.channel))
      .collect();
  },
});

The journal is not a debugging log. It is the input to the update decision. Because the backend knows exactly which documents a query read, it can answer a question that usually requires guesswork: when a mutation lands, which live subscriptions does it actually affect?

Convex is the open-source reactive database designed to make life easy for web app developers, whether human or LLM.

Convex project, Project description in the GitHub repository · get-convex/convex-backend README

Why Put Your Functions In The Database

Read-set tracking only works if the database can see every read. That requirement explains a design choice that otherwise looks eccentric: Convex queries are TypeScript functions that execute inside the database, in the same transaction as the data they read.

In Convex, the queries are not SQL queries but functions written in Typescript or JavaScript that run directly in the database.

Convex interviewee, Convex representative interviewed about the product · Cerebral Valley interview

If the query ran in a separate service, its reads would cross a network boundary and the database would lose visibility into them. Keeping user code inside the transaction keeps the reads observable. The journal falls out of the execution model rather than being bolted on top of it.

Running your functions in the database allows us to do a couple of unique things - for example, we can exactly cache your data so you never have to think about caching, and provide you with dynamic real-time subscriptions where every query can be subscribed to in real time.

Convex interviewee, Convex representative interviewed about the product · Cerebral Valley interview
An extreme close-up editorial illustration of a single ledger page, showing one handwritten line of read entries with hash marks and a small stamped seal at the bottom resembling a transaction timestamp. In the margin, a key turns inside a small padlock drawn as part of the page's border ornament. The image zooms in on the journal itself at the moment it locks a query's read-set into a transaction.
The journal up close: a read-set recorded inside the transaction, sealed with a timestamp.

How a Query Becomes a Subscription

The loop is short. A client subscribes to a query. The backend runs it and writes the read-set into a journal. A mutation lands somewhere in storage. The backend checks whether the changed document appears in any live journal. If it does, that query re-runs and pushes a new result. If it does not, nothing happens.

Step through the reactive loop: subscribe, run and journal, mutate, then check overlap. Only a mutation that lands inside the read-set wakes the query.

The magic is in the last step. A mutation that touches a document no live query has read produces zero re-runs. A mutation that touches a tracked document produces exactly one re-run per affected subscription. The backend is not broadcasting changes and letting clients sort it out. It is consulting a precise index of who read what.

Inside the Rust Backend

The backend is a Rust workspace, and the most architecturally revealing file is crates/application/src/api.rs. It defines an ApplicationApi trait whose doc comment states its job: it owns all state and validation logic so HTTP routes can stay thin and stateless, and it is also the point where the hosted cloud routes a request to the right backend. That single seam lets self-hosted deployments and Convex Cloud share the same code path.

User code runs in a pool of V8 isolates, sized by a concurrency knob, so arbitrary TypeScript can execute without escaping the transaction that gives the journal its visibility. The layer stack is straightforward: HTTP routes pass through ApplicationApi, into a FunctionRouter that dispatches by function kind, and out to either the V8 pool for execution or the storage engine for reads and writes.

Two more details signal how seriously the team treats the runtime. The server requires a nightly Rust toolchain, enabling features like try_blocks and coroutines in the application crate. And system metadata (components, schemas, modules, environment variables) is itself stored as database tables, accessed through typed model wrappers that take a transaction. The database does not have a separate control store. It keeps its own bookkeeping in the same engine.

Convex In Context

The interesting comparison is not a feature checklist. It is the mechanism each backend uses to keep a client in sync, and where application logic is allowed to run.

BackendHow reactivity worksWhere application logic runs
ConvexRead-set journals; only queries overlapping a change re-runInside the database, transactionally
SupabasePostgres plus Realtime; developer wires explicit channel subscriptionsIn the database or separate edge functions
FirebaseFirestore listeners composed from separate servicesOutside the data, in Cloud Functions
AppwriteExplicit channel subscriptions (vendor claim)In separate functions
ElectricSQLSync-oriented replication to local databasesLocal-first on the client

The Appwrite row comes from Convex's own published comparison page and should be read as a vendor claim, not a neutral measurement. The other rows describe publicly documented architectures.

The pattern is consistent. Most platforms give developers real-time delivery as a feature layered onto a database and a separate compute service. Convex makes the live subscription a property of the query itself, which is only possible because the query and the data share a transaction.

The Self-Hosting Tradeoff

The repository is not a stripped-down demo. According to Convex's open-source announcement, it uses the same up-to-date code as the cloud service and supports the app APIs cloud projects rely on, with a self-hosted install that includes most of the cloud product, including the dashboard and CLI. Postgres, SQLite, Neon, Fly.io, Vercel, and RDS are named as compatible environments.

The license is the Functional Source License, which converts to Apache 2.0 two years after each release. Convex frames the choice as an attempt to support customers and developers while discouraging large cloud providers from reselling the product, and it cites Sentry's adoption of the FSL as precedent.

The announcement is unusually candid about what self-hosting costs you. Running the backend in production transfers scaling, backups, high availability, and migrations to the operator, and the managed service remains the recommended path for teams that need those. Some features still depend on the cloud platform, including the dashboard, certain streaming import and export integrations, log streams to observability services, and exception streaming.

So the honest summary is this: the open-source release exposes the data plane, the part that runs queries, journals their reads, and pushes updates. The control plane that manages deployments stays in the cloud. That is a genuinely unusual posture, and it is worth reading the announcement before deciding which side of the line you fall on.