vybekiit 0.7.33 → 0.7.34

package/dist/global-skills/manifest.json

@@ -111,6 +111,7 @@
     "neon-postgres",
     "neon-postgres-branches",
     "neon-postgres-egress-optimizer",
+    "neon-realtime",
     "onboarding",
     "plan-my-idea",
     "publish-app",
@@ -152,5 +153,5 @@
   "resources": [
     "vybekiitReferences"
   ],
-  "count": 148
+  "count": 149
 }

package/dist/global-skills/neon/SKILL.md

@@ -2,16 +2,17 @@
 name: neon
 description: >-
   Overview of Neon, a complete set of cloud backend primitives around Lakebase
-  Postgres: Auth, Object Storage, Functions, and the AI Gateway. Start here to
+  Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to
   choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or
   MCP server, and follow the branch-first workflow. Use when building an app or
   backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child
   skill neon-postgres wins for an existing DATABASE_URL, SQL, schema, inspect,
   or search. Child skill neon-auth wins for login, users, sessions, identity
-  routing, and Managed Better Auth setup. Also use for object storage, S3, buckets, serverless functions,
-  function triggers, cron, AI gateway, LLM calls, logs, Loki, Grafana,
-  observability, postgres, database, backend, Claimable Neon, neon.new, or a
-  no-signup database.
+  routing, and Managed Better Auth setup. Child skill neon-realtime wins for
+  live queries in reactive apps and agents. Also use for object storage, S3,
+  buckets, serverless functions, function triggers, cron, AI gateway, LLM calls,
+  realtime, logs, Loki, Grafana, observability,
+  postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.
 metadata:
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon
 disable-model-invocation: true
@@ -19,7 +20,7 @@ disable-model-invocation: true
 
 # Neon
 
-Neon is a complete set of cloud backend primitives around Lakebase Postgres, from Databricks — Lakebase Postgres, Auth (managed Better Auth), long-running Functions, Object Storage, and an AI Gateway, all instant, branchable, and serverless.
+Neon is a complete set of cloud backend primitives around Lakebase Postgres, from Databricks — Lakebase Postgres, Auth (managed Better Auth), long-running Functions, Object Storage, an AI Gateway, and Realtime live queries, all instant, branchable, and serverless.
 
 **Lakebase Postgres** is the database itself. It is one product, reached two ways: through Neon, with a free plan and the full set of backend primitives above, or through Databricks, alongside the rest of the Databricks suite. Same infrastructure, same features, same engineering team. Call the database Lakebase Postgres, and use "Neon" for the brand and for this access path — not as a name for the database.
 
@@ -36,11 +37,12 @@ Neon bundles several backend primitives for building apps and agents that all br
 - **Object Storage** — S3-compatible object storage that branches with your projects.
 - **Functions** — Neon's compute offering: long-running serverless functions that run close to your database, for WebSocket servers, long agent HTTP streams, APIs, and server-sent event servers. A Function Trigger POSTs to a function on a cron.
 - **AI Gateway** — One API for frontier and open-source models, supporting the chat completions API and the responses API, powered by Databricks Unity AI Gateway.
+- **Realtime** (beta) — Makes any SQL query live. Subscribe in realtime to Lakebase Postgres and build reactive apps and agents with type-safe live queries and optimistic mutations.
 - **Data API** — Optional PostgREST-compatible HTTP interface. Use it only when the app already uses PostgREST or a Supabase database client, or is migrating that client. New apps query Postgres from Functions or existing handlers. There is no `neon-data-api` skill; configuration is `dataApi` in `neon.ts` (see [Type-safe config](#type-safe-config-invalid-setups-dont-compile) when you have chosen it).
 
 ### Region availability
 
-Object Storage, Functions, and AI Gateway are currently available on projects in `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`. Before guiding a user through any of these services, confirm they are working in one of these regions. If not, they will need to create a new project in a supported region.
+Object Storage, Functions, AI Gateway, and Realtime are currently available on projects in `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`. Before guiding a user through any of these services, confirm they are working in one of these regions. If not, they will need to create a new project in a supported region.
 
 ## Architecture: How to Use Neon
 
@@ -64,7 +66,7 @@ Functions have public HTTPS URLs. Verify a JWT or API key at the top of the hand
 
 Inspect the repo before provisioning.
 
-1. Map requested capabilities: login, files, HTTP APIs, LLM calls, SQL.
+1. Map requested capabilities: login, files, HTTP APIs, LLM calls, live data, SQL.
 2. Reuse what is already there: a supplied `DATABASE_URL`, an existing ORM or driver, Better Auth, Clerk or another auth provider, S3 or another object store, an existing `.neon` / `neon.ts`, an existing Data API or PostgREST client.
 3. Select Neon primitives for capabilities that are still undecided.
 4. Provision only when infrastructure is missing: `neon init` / `neon link` / Claimable, then `neon.ts`, then `neon deploy`.
@@ -82,7 +84,8 @@ New projects are created in AWS regions. Prefer pooled `DATABASE_URL` for applic
 | Existing Better Auth, Clerk, Supabase Auth, or another working IdP | Keep it. `neon-auth` only if they ask to migrate |
 | User asked to migrate from Supabase Auth | `neon-auth` (Managed Better Auth; keep `SupabaseAuthAdapter()` call shapes) |
 | Files, uploads, blobs (no existing object store) | Object Storage |
-| HTTP APIs, cron, WebSocket, SSE, long-running agents | Functions querying Postgres |
+| HTTP APIs, cron, custom WebSocket or SSE push, long-running agents | Functions querying Postgres |
+| Live queries for realtime, reactive apps and agents; optimistic mutations | `neon-realtime` (`preview.realtime` in `neon.ts`). Not available on Claimable projects until claimed |
 | LLM calls | AI Gateway |
 | SQL, schema, inspect, search | `neon-postgres` |
 | Existing PostgREST / Supabase database client | Data API (`dataApi` in `neon.ts`) |
@@ -125,6 +128,7 @@ The skills below live in the [`neondatabase/agent-skills`](https://github.com/ne
 | `neon-object-storage`            | Storing and serving files (uploads, images, blobs), including branching them with the database.                                                                                      |
 | `neon-functions`                 | Deploying long-running or streaming serverless functions — APIs, agents, SSE/WebSocket servers, and Function Triggers (cron and object-storage).                                     |
 | `neon-ai-gateway`                | Calling an LLM or routing across model providers with one credential, including discovering the branch's servable models at runtime via the OpenAI-compatible `/v1/models` endpoint. |
+| `neon-realtime`                  | Realtime makes any SQL query live, for realtime, reactive apps and agents: enabling Realtime, sealing queries, React and TanStack DB bindings, SSR, and optimistic mutations.      |
 | `neon-postgres-egress-optimizer` | Diagnosing or fixing excessive Postgres egress (network data-transfer) costs in a codebase.                                                                                          |
 
 There is no `neon-data-api` skill. Configure `dataApi` in `neon.ts` only for PostgREST / Supabase database-client compatibility or a migration that already depends on it.
@@ -328,7 +332,7 @@ export default defineConfig({
 
 ### Provision services with neon config
 
-Every project ships with Lakebase Postgres; `neon.ts` also declares Auth, Functions, buckets, and the AI Gateway. Data API is a compatibility toggle, not part of a default backend:
+Every project ships with Lakebase Postgres; `neon.ts` also declares Auth, Functions, buckets, and the AI Gateway. Realtime is declared under `preview`. Data API is a compatibility toggle, not part of a default backend:
 
 ```typescript
 // neon.ts
@@ -337,6 +341,7 @@ export default defineConfig({
   functions: {},
   buckets: {},
   aiGateway: true, // see the neon-ai-gateway skill
+  preview: { realtime: true }, // see the neon-realtime skill
 });
 ```
 

package/dist/global-skills/neon-functions/SKILL.md

@@ -11,11 +11,10 @@ description: >-
   a cron or an object-storage event that POSTs to a function. Triggers include
   "serverless function", "deploy an API", "long-running function",
   "streaming agent", "SSE server", "WebSocket server", "webhook handler",
-  "MCP server", "cron", "function trigger", "scheduled function", "cron job",
-  "object storage trigger", "on upload", "run code next to my database",
-  "function that won't time out", "function logs", "Neon Functions",
-  "Neon Compute", "DDoS protection", "rate limiting", and
-  "production hardening".
+  "MCP server", "cron", "scheduled function", "object storage trigger",
+  "on upload", "function that won't time out", "function logs",
+  "Neon Functions", "Neon Compute", "DDoS protection", "rate limiting", and
+  "production hardening". For live UIs over database rows, use neon-realtime.
 metadata:
   parent: neon
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-functions
@@ -453,13 +452,15 @@ beat.unref?.();
 
 The client skips these when handling messages. There is no protocol-level shortcut here: the standard `WebSocket` from `upgradeWebSocket` has no `ping()`, and a browser can't send ping frames from JavaScript, so an application-level message is the only keepalive a browser client can use. (A Node `ws` client can send ping frames, and the server auto-replies with a pong, but a browser can't.)
 
-### Keeping clients in sync across isolates (do not skip this)
+### Fan-out across isolates (do not skip this)
 
 Under load the runtime runs **several isolates in parallel, each with its own copy of module state** — so each isolate has its own `clients` set. Broadcasting only to that local set means a client on isolate A never sees an event produced on isolate B, and the feed silently fractures. It's easy to miss: `neon dev` runs a single process (one isolate), so in-process broadcast always _looks_ fine locally but breaks in production, where concurrent connections spread across many isolates.
 
+If the data is database rows (live dashboards, feeds, chat over stored messages), use Neon Realtime (the `neon-realtime` skill) instead of hand-rolling fan-out. Using Realtime does not prevent your database from scaling to zero. The strategies below are for push that doesn't come from database rows (presence, typing, LLM streams), and the fallback where Realtime isn't available, such as on Claimable projects until they're claimed.
+
 Module state doesn't survive eviction anyway, so **Postgres is the shared source of truth**. Pick a fan-out strategy. In every snippet below, `pool` is a pooled `pg` client and `clients` is this isolate's `Set` of live connections.
 
-**1. Poll Postgres — the default, and the only option that keeps Scale to Zero.** Each isolate re-reads the shared state (or rows past a cursor) on a short interval and pushes changes to its own clients. One query per isolate per tick (not per client), and none when the isolate has no clients — so an idle compute still suspends.
+**1. Poll Postgres — the default, and it keeps Scale to Zero.** Each isolate re-reads the shared state (or rows past a cursor) on a short interval and pushes changes to its own clients. One query per isolate per tick (not per client), and none when the isolate has no clients — so an idle compute still suspends.
 
 ```typescript
 let lastId = "0"; // bigint id, so a string
@@ -496,7 +497,7 @@ pool
   .finally(() => setInterval(poll, 1000).unref?.());
 ```
 
-- **Latency:** up to the interval (~1s) — fine for counters, chat, and dashboards.
+- **Latency:** up to the interval (~1s).
 - **Scaling:** database load grows with the number of live isolates, not clients. Keep the cursor on an indexed `serial`/`bigserial` PK and the interval sane.
 - **Scale to Zero:** ✅ preserved — polling stops when no clients are connected, so the compute suspends on its normal timer.
 - **Ordering:** `WHERE id > cursor` can skip a row that commits out of sequence: a transaction that took a lower id but commits after a higher one is already behind the cursor, so the poll never returns it. For a broadcast feed occasional loss is usually fine; when you need every row, use `LISTEN`/`NOTIFY` or poll by `created_at` with a small overlap window and dedupe by id.
@@ -540,7 +541,7 @@ function broadcast(event: unknown) {
 
 **3. External pub/sub (e.g. [Upstash](https://upstash.com) Redis) — best at scale.** For high fan-out, sub-second latency at large connection counts, or multi-region, publish/subscribe through a dedicated broker. Highest throughput, and it doesn't touch Postgres or block Scale to Zero — at the cost of another service to run.
 
-**Rule of thumb:** start with **polling** (works with Scale to Zero, no extra infra); switch to `LISTEN`/`NOTIFY` only on always-on compute that needs sub-second latency; move to Redis when fan-out outgrows Postgres.
+**Rule of thumb:** for database rows, use **Neon Realtime**. Otherwise start with **polling** (works with Scale to Zero, no extra infra); switch to `LISTEN`/`NOTIFY` only on always-on compute that needs sub-second latency; move to Redis when fan-out outgrows Postgres.
 
 ### Client must reconnect
 
@@ -570,7 +571,7 @@ async function connect() {
 connect();
 ```
 
-Together — `upgradeWebSocket` inside `fetch`, JWT auth over `?token=`, cross-isolate fan-out, and client backoff — these compose into a complete realtime chat backend on a single function.
+Together — `upgradeWebSocket` inside `fetch`, JWT auth over `?token=`, cross-isolate fan-out, and client backoff — these compose into a complete WebSocket backend on a single function, for push that doesn't come from database rows (presence, typing, LLM streams) or where Realtime isn't available. For persisted chat, feeds, and other live UIs over database rows, use Neon Realtime (the `neon-realtime` skill).
 
 ## Server-Sent Events (SSE)
 
@@ -606,7 +607,7 @@ export default {
 };
 ```
 
-The same rules as WebSockets apply. **Heartbeat:** a stream stays open only while bytes flow — Neon's window is 15 minutes ([Timeouts and Runtime Limits](#timeouts-and-runtime-limits)) but proxies are usually far stricter, so emit a `: ping\n\n` comment every ~25–30s (shown above) to keep idle streams from being dropped. Keep state in Postgres, and fan out across isolates using one of the [sync strategies](#keeping-clients-in-sync-across-isolates-do-not-skip-this) (hold a `Set` of stream controllers and `enqueue` to each). `EventSource` is GET-only and can't set headers, so authenticate with a `?token=` query param or cookie, exactly like the WebSocket case. [references/sse.md](https://neon.com/docs/ai/skills/neon-functions/references/sse.md) has the full pattern — Hono variant, cross-isolate fan-out, wire format, client, and caveats.
+The same rules as WebSockets apply. **Heartbeat:** a stream stays open only while bytes flow — Neon's window is 15 minutes ([Timeouts and Runtime Limits](#timeouts-and-runtime-limits)) but proxies are usually far stricter, so emit a `: ping\n\n` comment every ~25–30s (shown above) to keep idle streams from being dropped. Keep state in Postgres, and fan out across isolates using one of the [fan-out strategies](#fan-out-across-isolates-do-not-skip-this) (hold a `Set` of stream controllers and `enqueue` to each). `EventSource` is GET-only and can't set headers, so authenticate with a `?token=` query param or cookie, exactly like the WebSocket case. [references/sse.md](https://neon.com/docs/ai/skills/neon-functions/references/sse.md) has the full pattern — Hono variant, cross-isolate fan-out, wire format, client, and caveats.
 
 ## Function Triggers
 

package/dist/global-skills/neon-functions/references/sse.md

@@ -79,7 +79,7 @@ export default app;
 
 ## Push to every client, across isolates
 
-The fan-out rule is identical to WebSockets ([Keeping clients in sync across isolates](../SKILL.md#keeping-clients-in-sync-across-isolates-do-not-skip-this)): each isolate keeps its **own** set of open streams, so broadcasting in-process only reaches the clients on that isolate. Hold a `Set` of stream controllers and pick a strategy there — **poll Postgres** by default (keeps Scale to Zero), or `LISTEN`/`NOTIFY` (shown below) for lowest latency on always-on compute. Keep the source-of-truth state in Postgres — module state doesn't survive eviction.
+If the data is database rows (live dashboards, feeds, chat over stored messages), use Neon Realtime (the `neon-realtime` skill) instead of hand-rolling fan-out. Otherwise, the fan-out rule is identical to WebSockets ([Fan-out across isolates](../SKILL.md#fan-out-across-isolates-do-not-skip-this)): each isolate keeps its **own** set of open streams, so broadcasting in-process only reaches the clients on that isolate. Hold a `Set` of stream controllers and pick a strategy there — **poll Postgres** by default (keeps Scale to Zero), or `LISTEN`/`NOTIFY` (shown below) for lowest latency on always-on compute. Keep the source-of-truth state in Postgres — module state doesn't survive eviction.
 
 ```typescript
 import { attachDatabasePool } from "@neon/functions";
@@ -160,4 +160,4 @@ source.onerror = () => {
 - **CORS.** A SPA hits the function cross-origin, so set `Access-Control-Allow-Origin`. `EventSource` sends no credentials by default, so `*` is fine for public streams.
 - **One-way only.** SSE is server → client. For client → server, the browser makes normal `fetch`/`POST` calls (often to the same function); reach for [WebSockets](../SKILL.md#websocket-servers) only when you need bidirectional, low-latency frames.
 
-Together — a Hono `fetch` SSE endpoint, cross-isolate fan-out, heartbeat, a counter persisted in Postgres, and a client-only TanStack Router SPA consuming it with `EventSource` — these compose into a complete realtime backend on a single function.
+Together — a Hono `fetch` SSE endpoint, cross-isolate fan-out, heartbeat, a counter persisted in Postgres, and a client-only TanStack Router SPA consuming it with `EventSource` — these compose into a complete push backend on a single function, for push that doesn't come from database rows (presence, typing, LLM streams) or where Realtime isn't available. For persisted chat, feeds, and other live UIs over database rows, use Neon Realtime (the `neon-realtime` skill).

package/dist/global-skills/neon-object-storage/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: neon-object-storage
 description: >-
-  S3-compatible object storage that branches with your Neon project, so files
-  and the database stay in sync across every branch. Use when a user wants
+  S3-compatible object storage that branches with your database, so each
+  branch gets its own copy of the files and the rows that point at them.
+  Use when a user wants
   object storage, a bucket, blob/file storage, or somewhere to put uploads,
   images, documents, avatars, or user-generated files for their app or agent —
   especially when they already use (or are setting up) Lakebase Postgres and don't
@@ -30,7 +31,7 @@ neon skills -s neon -y
 
 Currently available in `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`.
 
-Neon Object Storage is S3-compatible object storage that branches with your projects: every branch gets its own isolated storage state, so files and database rows stay in sync across dev, preview, staging, and production.
+Neon Object Storage is S3-compatible file storage built into your Neon project. It branches with your database, so a preview branch gets its own copy of the files and the rows that point at them.
 
 Use this skill to help the user store and serve files that branch alongside their database. Deliver a working bucket and upload/download flow, a branch-aware S3 client wired to the injected env vars, or a precise answer from the official Neon docs.
 
@@ -39,7 +40,7 @@ Use this skill to help the user store and serve files that branch alongside thei
 Reach for Neon Object Storage for the files an app and its users produce — uploads, attachments, avatars, images, documents, generated assets, backups. It is the default place to put them when the app is already on Neon:
 
 - **They already use Lakebase Postgres and don't want a second provider.** One backend, one bill, one CLI, one set of branches — instead of standing up and wiring a separate AWS S3 / R2 / Supabase Storage account. The same Neon credential that backs the database backs storage.
-- **Files must stay in sync with the database across environments.** Storage branches _together with_ your Postgres data. Fork a branch and the child instantly inherits the parent's buckets and objects at that point in time — copy-on-write, so no data is duplicated. This is what makes agent, dev, preview, and test environments seamless: a preview branch gets a consistent snapshot of _both_ the rows and the files they reference, and writes on the child never touch the parent.
+- **Files must branch with the database across environments.** Storage branches _together with_ your Postgres data. Fork a branch and the child instantly inherits the parent's buckets and objects at that point in time — copy-on-write, so no data is duplicated. This is what makes agent, dev, preview, and test environments seamless: a preview branch gets a consistent snapshot of _both_ the rows and the files they reference, and writes on the child never touch the parent.
 - **They want safe, throwaway environments.** Upload, overwrite, and delete files in a preview/CI branch without any risk to production data, then drop the branch.
 - **They want standard S3 tooling.** It's built on S3 semantics and speaks the S3 API, so the AWS SDKs, `boto3`, the AWS CLI, and presigned URLs all work — reliable and familiar, with no proprietary client.
 

package/dist/global-skills/neon-postgres/SKILL.md

@@ -6,7 +6,8 @@ description: >-
   scale-to-zero, instant restore, read replicas, IP allow lists, logical
   replication, and Lakebase Search. Use when the work is an existing
   DATABASE_URL, SQL, schema, inspect, or search. New backends, Auth, files,
-  Functions, and LLM calls go to the parent `neon` skill. Also use for
+  Functions, and LLM calls go to the parent `neon` skill. Live queries, reactive
+  UIs, and realtime data go to `neon-realtime`. Also use for
   "@neondatabase/serverless", "@neondatabase/neon-js", "neon inspect db",
   "semantic search", "vector search", "full-text search", "BM25", or
   "hybrid search".
@@ -32,6 +33,8 @@ It is the same database whether you reach it through Neon or through Databricks;
 
 Login, users, sessions, and `@neondatabase/auth` belong in `neon-auth`.
 
+Live queries, reactive UIs, and realtime data belong in `neon-realtime`.
+
 ## Setup Flow
 
 ### 1. Select the organization and project

package/dist/global-skills/neon-realtime/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: neon-realtime
+description: >-
+  Neon Realtime makes any SQL query live. Build realtime, reactive apps and agents on Lakebase Postgres with live SQL queries and reactivity primitives. Use when app UI or agent state must update live from database rows (dashboards, feeds, collaboration, multi-user or multi-device sync), for optimistic mutations, or to replace polling or other realtime sync systems. Triggers include "live query", "subscribe", "sync engine", "useLiveQuery", "TanStack DB", "optimistic updates", "@neon/realtime". For push that doesn't come from database rows (presence, typing, LLM streams), use neon-functions.
+metadata:
+  parent: neon
+  source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-realtime
+disable-model-invocation: true
+---
+
+**FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.
+
+If the `neon` skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:
+
+```bash
+neon skills -s neon -y
+```
+
+# Neon Realtime
+
+Neon's Realtime makes any SQL query live. Subscribe in realtime to your Lakebase Postgres database. Develop apps and agents with end-to-end reactivity using type-safe live queries and optimistic mutations.
+
+Realtime is new and in beta, so its APIs aren't in your training data. Start from the core pattern below, and read each section's reference file before writing that code.
+
+## How It Works
+
+Realtime's layers compose: a live query engine inside Postgres, the Live SQL API (a WebSocket API), lower-level client SDKs (`seal()`, `subscribe()`), and reactivity primitives such as `useLiveQuery`.
+
+1. In trusted backend code, **define** a live query (any read-only SQL, including joins, aggregates, ordering and limits), **seal** it with `NEON_REALTIME_SECRET` and **expose** it from an authenticated endpoint or server function. The client can't read or change a sealed query's SQL or parameters.
+2. The client **subscribes** with the sealed query. It receives the full initial result, then each committed transaction's changes as one batch. Results stay consistent, but delivery of every change event isn't guaranteed.
+3. **Writes** go through your own API, which returns each write's `txid` for `awaitTxId()`.
+
+## Core Pattern
+
+The guides' chat app, with `messages` authorized through `channel_members`. The backend seals the query and returns each write's `txid`:
+
+```ts
+import { createRealtime, rawSql } from "@neon/realtime/server"
+import { drizzleAdapter } from "@neon/realtime-drizzle"
+import { and, desc, eq, getTableColumns, sql } from "drizzle-orm"
+import { Hono } from "hono"
+import { HTTPException } from "hono/http-exception"
+import { requireUser } from "./auth"
+import { db } from "./db"
+import { channelMembers, messages, type Message } from "./schema"
+
+export const realtime = createRealtime({ secret: process.env.NEON_REALTIME_SECRET!, db: "neondb", adapter: drizzleAdapter() })
+
+// Each selected key must match its column name
+export function messagesQuery(userId: string, channelId: number) {
+  return db
+    .select(getTableColumns(messages)).from(messages)
+    .innerJoin(channelMembers, eq(channelMembers.channel_id, messages.channel_id))
+    .where(and(eq(channelMembers.user_id, userId), eq(messages.channel_id, channelId)))
+    .orderBy(desc(messages.created_at))
+    .limit(50)
+}
+
+// Or raw SQL
+const rawMessagesQuery = (userId: string, channelId: number) => rawSql<Message>(
+    `SELECT messages.author_id, messages.body, messages.channel_id, messages.created_at, messages.id FROM messages
+     INNER JOIN channel_members ON channel_members.channel_id = messages.channel_id WHERE channel_members.user_id = $1 AND messages.channel_id = $2 ORDER BY messages.created_at DESC LIMIT 50`,
+    [userId, channelId]
+  )
+
+// The id of the transaction that made the change, read in the write's own RETURNING
+const txid = sql<string>`pg_current_xact_id()::text`
+
+const app = new Hono()
+  .post("/api/v1/messages/live", async (c) => {
+    const user = await requireUser(c)
+    const { channelId } = await c.req.json<{ channelId: number }>() // validate input
+    return c.json(await realtime.seal({ query: messagesQuery(user.id, channelId) }))
+  })
+  .post("/api/v1/messages", async (c) => {
+    const user = await requireUser(c)
+    const { id, channelId, body } = await c.req.json<{ id: string; channelId: number; body: string }>() // validate input
+    // One statement. The membership row supplies channel_id and author_id, so only a member's message is inserted.
+    // List every column in table order, alias each sql field, and cast untyped params (they resolve to text)
+    const [sent] = await db.insert(messages).select(
+      db.select({
+          id: sql`${id}::uuid`.as("id"), channel_id: channelMembers.channel_id, author_id: channelMembers.user_id,
+          body: sql`${body}`.as("body"), created_at: sql`now()`.as("created_at"),
+        })
+        .from(channelMembers)
+        .where(and(eq(channelMembers.channel_id, channelId), eq(channelMembers.user_id, user.id)))
+    ).returning({ txid })
+    if (!sent) throw new HTTPException(403, { message: "Not a member of this channel" })
+    return c.json({ kind: "committed", txid: sent.txid })
+  })
+```
+
+The React frontend subscribes and sends optimistic messages:
+
+```tsx
+import { createRealtimeClient, type SealedLiveQuery } from "@neon/realtime/client"
+import { drizzleParsers } from "@neon/realtime-drizzle/client"
+import { useLiveQuery } from "@neon/realtime-react"
+import { startTransition, useCallback, useOptimistic } from "react"
+import type { Message } from "../backend/schema"
+import { fetchSealedMessages, sendMessage } from "./api"
+
+// One client per app, because subscriptions share its connection. Wrap the app in <RealtimeProvider client={client}>
+export const client = createRealtimeClient({ url: import.meta.env.VITE_NEON_REALTIME_URL, parsers: { ...drizzleParsers } })
+
+const NO_MESSAGES: readonly Message[] = []
+type Props = { sealedQuery: SealedLiveQuery<Message>; channelId: number; userId: string }
+
+export function Messages({ sealedQuery, channelId, userId }: Props) {
+  const refreshQuery = useCallback(() => fetchSealedMessages(channelId), [channelId])
+  const { data, status, error, utils } = useLiveQuery(sealedQuery, { refreshQuery })
+  // Once the sent message syncs, show only the synced row
+  const [messages, addOptimistic] = useOptimistic(data ?? NO_MESSAGES, (current, message: Message) =>
+    current.some(({ id }) => id === message.id) ? current : [message, ...current]
+  )
+
+  function send(body: string) {
+    // The server sets author and timestamp but keeps this id
+    const message = { id: crypto.randomUUID(), channel_id: channelId, author_id: userId, body, created_at: new Date() }
+    startTransition(async () => {
+      addOptimistic(message)
+      try {
+        const result = await sendMessage(message) // maps channel_id to channelId
+        if (result.kind === "committed") await utils.awaitTxId(result.txid, 10_000)
+      } catch { /* show "Couldn't confirm the change" */ }
+    })
+  }
+
+  if (status === "error") return <p role="alert">Live updates stopped: {error.message}</p>
+  if (data === undefined) return <p>Loading messages</p>
+  return (
+    <form action={(form) => send(String(form.get("body")))}>
+      <input name="body" required />
+      <ul>{messages.map((message) => <li key={message.id}>{message.body}</li>)}</ul>
+    </form>
+  )
+}
+```
+
+## Choose the Stack
+
+A live query replaces fetching app data from an API or another sync system. Reuse existing query code, and use the highest layer that fits rather than wiring changes into app state by hand.
+
+| Use | For |
+| --- | --- |
+| `drizzleAdapter()` from `@neon/realtime-drizzle`, or `kyselyAdapter()` from `@neon/realtime-kysely` | Queries written in Drizzle or Kysely |
+| `rawSql` from `@neon/realtime/server` | Any other ORM, or none |
+| `useLiveQuery` from `@neon/realtime-react` | React. Binds one sealed query to a component's state |
+| `realtimeCollectionOptions` from `@neon/realtime-tanstack` | Many views over the same data, or an app on TanStack DB. Oversync one broader query into a collection, then derive local live queries from it |
+| `client.subscribe()` from `@neon/realtime/client` | Other frameworks |
+| `realtime.subscribe()` from `@neon/realtime/server` | Agents and workers, in trusted backend code |
+
+Migrating from Electric: Realtime is a drop-in replacement for Electric's role in your stack. Live SQL queries replace shapes, and `realtimeCollectionOptions()` replaces `electricCollectionOptions()`.
+
+## Setup
+
+- **New app:** `neon bootstrap my-app --template realtime-react`, then `neon deploy` in `my-app`.
+- **Enable** it on the linked branch with [`neon realtime enable --allowed-origin <app origin>`](https://neon.com/docs/cli/realtime.md), or declare [`preview: { realtime: true }`](https://neon.com/docs/reference/neon-ts.md#realtime) in `neon.ts` (`neon config add realtime`) and run `neon deploy`. Child branches inherit it. It's unavailable on Claimable projects until claimed, or outside the [supported regions](https://neon.com/docs/realtime/overview.md#which-regions-is-it-enabled-in).
+- **Tables** need a [stable replica identity](references/queries.md#table-requirements); a primary key is enough.
+- **Environment:** `neon env pull --service postgres --service realtime` writes `DATABASE_URL`, `NEON_REALTIME_URL` and `NEON_REALTIME_SECRET`. Expose only the URL to the browser, under your framework's public prefix (like `VITE_`). `url` options take `NEON_REALTIME_URL`; `db` takes the database name from `DATABASE_URL`.
+- **Install** `@neon/realtime` and the packages chosen above. Use these SDKs, not the still-evolving WebSocket protocol.
+
+## Define and Seal Queries
+
+Read [references/queries.md](references/queries.md) before writing query or sealing code, including Kysely and server functions.
+
+- **Read-only and deterministic.** A raw query is a single `SELECT` with no `;` and `$1` placeholders. It can't call `now()` or `gen_random_uuid()`, so pass such values as parameters, wrapping every value except strings, numbers, booleans, bigints and null in a `pgParam` helper (`pgParam.timestamptz(date)`).
+- **Authorize in the query.** Check the session before sealing, and join through your membership tables so revoked access drops out. Any web framework auth works, including Managed Better Auth, but not [RLS](references/queries.md#why-not-row-level-security) yet. See [Authorization](references/queries.md#authorization).
+- **A sealed query is a bearer token.** Keep it out of URLs, logs and persistent storage, and never fill its parameters from unchecked input.
+- **Check a query** before wiring it in: [`neon realtime subscribe "SELECT ..."`](https://neon.com/docs/cli/realtime.md#subscribe) prints the initial result, then each transaction's changes, until you stop it. With `--output json`, each change prints a full snapshot. Set `debugMode` on `createRealtime` for full database errors (development only).
+- **Sealed queries expire.** Pass `refreshQuery` to the bindings or call `renew()`, sealing the same query and parameters, or the subscription errors. New parameters need a new sealed query and subscription. In Next.js, renew from a Route Handler, because server actions run one at a time.
+
+## Subscribe
+
+Read [references/reactivity.md](references/reactivity.md) before writing React or TanStack DB code. Read [references/subscribing.md](references/subscribing.md) before subscribing directly with `client.subscribe(sealed)` (`getSnapshot`, `onChange`, `onStateChange`), or from agents and workers, which add `url` to `createRealtime` and `await realtime.subscribe(query)` to seal in-process.
+
+- **One database per client.** The first sealed query binds the connection to its `db`.
+- **Select a stable, unique key for every row** and key rows by it, including TanStack DB's `getKey`: usually the primary key, the grouped columns for aggregates, or the combined keys for joins that repeat a row. Never use `rowId`, which every `rows` update invalidates.
+- **`error` is final**, even after `renew()`. Fetch a fresh sealed query and subscribe again, with a new client if the connection failed. Watch `onStateChange` on direct subscriptions; `useLiveQuery()` reports errors through `status`, not by throwing or suspending.
+- **When the session changes, leave with a full page load.** It drops the Realtime client, any TanStack `DbClient` and the previous user's rows. The hook retries a failed renewal every second, so stop renewing once one fails as signed out. Check on every renewal and write that the session's user is the one the page was loaded for, or a write from the old page lands in the new user's account. See [When the session changes](references/ssr.md#when-the-session-changes).
+
+## Optimistic Writes
+
+Realtime has no write path, so writes keep your backend's usual auth. Read [references/mutations.md](references/mutations.md) before writing mutations, for each layer.
+
+- [Return the txid from the write itself](references/mutations.md#returning-the-txid-from-your-backend): `` .returning({ txid: sql<string>`pg_current_xact_id()::text` }) ``, in one round trip on any Postgres driver. Write a batch in one statement, so there's one txid. Never open `db.transaction()` just to `select pg_current_xact_id()`: that's four round trips holding a pooled connection. When a write genuinely needs several statements, put the txid in the `RETURNING` of a write that always changes a row.
+- Always pass `awaitTxId()` a timeout: it keeps waiting through reconnects and renewals, and never settles if the txid doesn't reach the query.
+- A write that changes no rows has no txid, so skip `awaitTxId()` and let the optimistic state drop.
+
+## Server-Side Rendering
+
+Read [references/ssr.md](references/ssr.md) before rendering live queries on the server, for Next.js and TanStack Start.
+
+- Create the client in a `useState` initializer rather than at module level, render `initialData` as live rows without a loading state, and never share a TanStack `DbClient` between requests.
+- Keep row shapes identical on both sides. `JSON.stringify` turns dates into strings, and `int8` and `numeric` arrive as strings.
+
+## More Docs
+
+| Task | Page |
+| --- | --- |
+| Beta scope, regions, pricing, FAQ, other systems | [Overview](https://neon.com/docs/realtime/overview.md) |
+| Architecture and consistency | [How it works](https://neon.com/docs/realtime/how-it-works.md) |
+| A first live query | [Quickstart](https://neon.com/docs/realtime/quickstart.md) |
+| Every SDK export | [TypeScript SDK reference](https://neon.com/docs/realtime/sdks/typescript.md) |
+| Full-stack apps with auth and SSR | [Next.js](https://neon.com/docs/realtime/examples/nextjs.md), [TanStack](https://neon.com/docs/realtime/examples/tanstack.md) |
+| Live agent workflows | [Mastra](https://neon.com/docs/realtime/examples/mastra.md) |
+| ORM adapters | [Drizzle](https://neon.com/docs/realtime/examples/drizzle.md), [Kysely](https://neon.com/docs/realtime/examples/kysely.md) |