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.
- A Convex query returns data plus a serialized record of every document and index range it read, so the backend never has to guess which subscriptions a change affects.
- Running TypeScript functions inside the database transaction is what makes read-set tracking possible, because the backend observes every read as it happens.
- Cache invalidation disappears because the journal already names the exact queries a mutation touches, and only those re-run.
- The open-source backend is the same data plane that serves Convex Cloud, released under the Functional Source License, with scaling, backups, and migrations left to the operator.
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.
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.
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.
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.
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.
| Backend | How reactivity works | Where application logic runs |
|---|---|---|
| Convex | Read-set journals; only queries overlapping a change re-run | Inside the database, transactionally |
| Supabase | Postgres plus Realtime; developer wires explicit channel subscriptions | In the database or separate edge functions |
| Firebase | Firestore listeners composed from separate services | Outside the data, in Cloud Functions |
| Appwrite | Explicit channel subscriptions (vendor claim) | In separate functions |
| ElectricSQL | Sync-oriented replication to local databases | Local-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.





