neon 8.4.2 → 8.4.3

package/README.md

@@ -306,6 +306,35 @@ regression + TAP tests.
 
 - **TLS cipher is runtime-dependent.** The negotiated TLS 1.3 ciphersuite is chosen by the host runtime's TLS library from an offer byte-identical to libpq's. Under Node (OpenSSL) that is `TLS_AES_256_GCM_SHA384`, matching vanilla psql; under Bun (BoringSSL) it is `TLS_AES_128_GCM_SHA256`. Both are TLS 1.3 AEAD suites with no practical security difference, and neither runtime exposes a client-side knob to steer the selection.
 
+## Subscribe to a Realtime query
+
+`neon subscribe` streams a live SQL query until interrupted:
+
+```bash
+neon subscribe "SELECT id, title, completed FROM realtime_todos ORDER BY id"
+```
+
+The default terminal output is append-only. It identifies the selected project,
+branch, and database; prints the initial result once; reports connection-state
+changes; and then prints each published batch with its transaction IDs, a compact
+`+insert ~update -delete` summary, and the affected rows. It does not take over the
+terminal or require keyboard navigation. Pass `--changes` to display the raw reset
+and batch events instead of the materialized view.
+
+For scripts and agents, JSON output is a JSON Lines stream with one complete event
+per line. YAML output uses one document per event:
+
+```bash
+neon subscribe --changes --output json "SELECT * FROM realtime_todos" |
+  jq --unbuffered 'select(.type == "batch")'
+
+neon subscribe --output yaml "SELECT * FROM realtime_todos"
+```
+
+Machine-readable output retains the event stream: without `--changes`, each event is
+a complete `snapshot`; with `--changes`, events are raw `reset` and `batch` objects.
+Lifecycle labels and the target header are terminal-only.
+
 ## Configure autocompletion
 
 The Neon CLI supports autocompletion, which you can configure in a few easy steps. See [Neon CLI commands — completion](https://neon.com/docs/cli/completion) for instructions.

package/dist/commands/subscribe.js

@@ -26,11 +26,11 @@ const builder = (argv) => argv.usage("$0 subscribe \"<query>\" [options]").posit
 		type: "string"
 	},
 	changes: {
-		describe: "Show raw resets and transaction batches instead of full query results",
+		describe: "Show raw resets and transaction batches",
 		type: "boolean",
 		default: false
 	}
-}).example("$0 subscribe \"SELECT * FROM items\"", "Print the full result whenever it changes").example("$0 subscribe --changes \"SELECT * FROM items\"", "Print raw reset and delta events").epilogue("The subscription runs until interrupted. JSON output is newline-delimited; YAML output uses one document per event.").middleware(fillSingleProject).strict();
+}).example("$0 subscribe \"SELECT * FROM items\"", "Print the initial result followed by a readable transaction log").example("$0 subscribe --changes \"SELECT * FROM items\"", "Print raw reset and delta events").epilogue("The subscription runs until interrupted. Terminal output is an append-only snapshot and transaction log; JSON output is newline-delimited; YAML output uses one document per event.").middleware(fillSingleProject).strict();
 const handler = async (props) => {
 	const controller = new AbortController();
 	const stop = (exitCode) => {
@@ -56,6 +56,7 @@ const subscribe = async (props, dependencies = {}) => {
 	const resolveBranchId = dependencies.resolveBranchId ?? branchIdFromProps;
 	const resolveEnv = dependencies.resolveEnv ?? resolveNeonEnvVars;
 	const connect = dependencies.connect ?? connectRealtime;
+	const now = dependencies.now ?? (() => /* @__PURE__ */ new Date());
 	const branchId = await resolveBranchId(props);
 	const { vars } = await resolveEnv({
 		cwd: props.cwd ?? process.cwd(),
@@ -67,12 +68,20 @@ const subscribe = async (props, dependencies = {}) => {
 		services: ["postgres", "realtime"],
 		...props.runtimeApi ? { api: props.runtimeApi } : {}
 	});
+	const url = requiredEnv(vars, "NEON_REALTIME_URL");
+	const secret = requiredEnv(vars, "NEON_REALTIME_SECRET");
+	const database = await databaseName(requiredEnv(vars, "DATABASE_URL"));
 	const realtime = await connect({
-		url: requiredEnv(vars, "NEON_REALTIME_URL"),
-		secret: requiredEnv(vars, "NEON_REALTIME_SECRET"),
-		database: await databaseName(requiredEnv(vars, "DATABASE_URL"))
+		url,
+		secret,
+		database
 	});
-	const render = createRenderer(props);
+	const render = createRenderer(props, {
+		project: props.projectId,
+		branch: branchDisplayName(props, branchId),
+		database,
+		query: props.query
+	}, now);
 	let subscription;
 	try {
 		if (props.changes) {
@@ -81,7 +90,8 @@ const subscribe = async (props, dependencies = {}) => {
 		} else {
 			const materialized = await realtime.subscribeMaterialized(props.query);
 			subscription = materialized;
-			await consumeSnapshots(materialized, render, props.signal);
+			if (props.output === "table") await consumeChanges(materialized, render, props.signal);
+			else await consumeSnapshots(materialized, render, props.signal);
 		}
 	} finally {
 		subscription?.unsubscribe();
@@ -123,10 +133,23 @@ const databaseName = async (connectionString) => {
 	if (database) return database;
 	throw new Error("DATABASE_URL must include a database name.");
 };
-const createRenderer = (props) => {
+const createRenderer = (props, context, now) => {
 	const out = props.out ?? process.stdout;
-	let renderedTableFrame = false;
+	let hasBaseline = false;
+	let lastStatus;
+	const rowsById = /* @__PURE__ */ new Map();
+	if (props.output === "table") renderHumanHeader(out, context, props.changes);
 	return (event) => {
+		if (event.type === "status") {
+			if (props.output === "table") {
+				const status = humanStatus(event.state);
+				if (status !== lastStatus) {
+					lastStatus = status;
+					out.write(`${timestamp(now)} ${status}\n`);
+				}
+			}
+			return;
+		}
 		if (props.output === "json") {
 			out.write(`${JSON.stringify(event)}\n`);
 			return;
@@ -135,22 +158,25 @@ const createRenderer = (props) => {
 			out.write(`---\n${YAML.stringify(event)}`);
 			return;
 		}
-		if (renderedTableFrame) out.write("\n");
-		renderedTableFrame = true;
-		renderTableEvent(out, event);
+		out.write("\n");
+		if (event.type === "reset" && !props.changes) {
+			const label = hasBaseline ? "Reset" : "Initial snapshot";
+			hasBaseline = true;
+			rowsById.clear();
+			for (const { rowId, row } of event.rows) rowsById.set(rowId, row);
+			renderMaterializedRows(out, event.rows.map(({ row }) => row), `${timestamp(now)} ${label}`);
+			return;
+		}
+		if (event.type === "batch" && !props.changes) {
+			renderHumanBatch(out, event, rowsById, now);
+			return;
+		}
+		renderTableEvent(out, event, now);
 	};
 };
-const renderTableEvent = (out, event) => {
+const renderTableEvent = (out, event, now) => {
 	if (event.type === "snapshot") {
-		const fields = rowFields(event.rows);
-		writer({
-			output: "table",
-			out
-		}).end(event.rows, {
-			fields,
-			humanTitle: "Query result",
-			emptyMessage: "Query returned no rows."
-		});
+		renderMaterializedRows(out, event.rows, `${timestamp(now)} Snapshot`);
 		return;
 	}
 	if (event.type === "reset") {
@@ -158,14 +184,7 @@ const renderTableEvent = (out, event) => {
 			row_id: rowId,
 			row
 		}));
-		writer({
-			output: "table",
-			out
-		}).end(rows, {
-			fields: ["row_id", "row"],
-			humanTitle: "Reset",
-			emptyMessage: "Reset contains no rows."
-		});
+		renderRows(out, rows, ["row_id", "row"], `${timestamp(now)} Reset · ${rowCount(rows.length)}`, "Reset contains no rows.");
 		return;
 	}
 	const rows = event.changes.map((change) => ({
@@ -173,18 +192,110 @@ const renderTableEvent = (out, event) => {
 		row_id: change.rowId,
 		row: change.type === "upsert" ? change.row : void 0
 	}));
+	renderRows(out, rows, [
+		"type",
+		"row_id",
+		"row"
+	], `${timestamp(now)} ${transactionLabel(event.txids)} · ${rawChangeSummary(event.changes)}`, "Batch contains no row changes.");
+};
+const renderHumanHeader = (out, context, rawChanges) => {
+	const target = {
+		project: context.project,
+		branch: context.branch,
+		database: context.database,
+		mode: rawChanges ? "Raw changes" : "Materialized result",
+		query: context.query
+	};
 	writer({
 		output: "table",
 		out
-	}).end(rows, {
+	}).end(target, {
 		fields: [
-			"type",
-			"row_id",
-			"row"
+			"project",
+			"branch",
+			"database",
+			"mode",
+			"query"
 		],
-		humanTitle: `Batch (txids: ${event.txids.join(", ") || "none"})`,
-		emptyMessage: "Batch contains no row changes."
+		humanTitle: "Live query"
+	});
+};
+const renderMaterializedRows = (out, rows, title) => {
+	const humanTitle = `${title} · ${rowCount(rows.length)}`;
+	renderRows(out, rows, rowFields(rows), humanTitle, "Query returned no rows.");
+};
+const renderHumanBatch = (out, event, rowsById, now) => {
+	const changes = classifyChanges(event.changes, rowsById);
+	const inserted = changes.filter((change) => change.operation === "+ insert");
+	const updated = changes.filter((change) => change.operation === "~ update");
+	const deleted = changes.filter((change) => change.operation === "- delete");
+	const rowFieldsInBatch = rowFields(changes.flatMap((change) => change.row ? [change.row] : []));
+	const operationField = uniqueOperationField(rowFieldsInBatch);
+	const rows = changes.map((change) => ({
+		...change.row ?? {},
+		[operationField]: change.operation
+	}));
+	renderRows(out, rows, [operationField, ...rowFieldsInBatch], `${timestamp(now)} ${transactionLabel(event.txids)} · +${inserted.length} ~${updated.length} -${deleted.length}`, "Transaction contains no row changes.");
+};
+const renderRows = (out, rows, fields, title, emptyMessage) => {
+	writer({
+		output: "table",
+		out
+	}).end(rows, {
+		fields,
+		humanTitle: title
 	});
+	if (rows.length === 0) out.write(`${emptyMessage}\n`);
+};
+const classifyChanges = (changes, rowsById) => changes.map((change) => {
+	if (change.type === "upsert") {
+		const operation = rowsById.has(change.rowId) ? "~ update" : "+ insert";
+		rowsById.set(change.rowId, change.row);
+		return {
+			operation,
+			row: change.row
+		};
+	}
+	const row = rowsById.get(change.rowId);
+	rowsById.delete(change.rowId);
+	return {
+		operation: "- delete",
+		...row ? { row } : {}
+	};
+});
+const uniqueOperationField = (fields) => {
+	for (const candidate of [
+		"change",
+		"operation",
+		"event"
+	]) if (!fields.includes(candidate)) return candidate;
+	let suffix = 1;
+	while (fields.includes(`change_${suffix}`)) suffix += 1;
+	return `change_${suffix}`;
+};
+const transactionLabel = (txids) => {
+	if (txids.length === 0) return "Update (no transaction ID)";
+	return `${txids.length === 1 ? "Transaction" : "Transactions"} ${txids.join(", ")}`;
+};
+const rawChangeSummary = (changes) => {
+	const upserts = changes.filter((change) => change.type === "upsert").length;
+	const removals = changes.length - upserts;
+	return `${upserts} upsert${upserts === 1 ? "" : "s"}, ${removals} removal${removals === 1 ? "" : "s"}`;
+};
+const rowCount = (count) => `${count} ${count === 1 ? "row" : "rows"}`;
+const timestamp = (now) => `[${now().toISOString()}]`;
+const humanStatus = (state) => {
+	switch (state.status) {
+		case "connecting": return "Connecting…";
+		case "live": return "Live — waiting for changes.";
+		case "stale": return "Stale — showing the last known result.";
+		case "closed": return "Subscription closed.";
+		case "error": return `Subscription failed — ${state.error.message}`;
+	}
+};
+const branchDisplayName = (props, branchId) => {
+	const branch = "branch" in props ? props.branch : props.id;
+	return branch === branchId ? branchId : `${branch} (${branchId})`;
 };
 const rowFields = (rows) => {
 	const seen = /* @__PURE__ */ new Set();
@@ -203,7 +314,7 @@ const consumeSnapshots = async (subscription, render, signal) => consumeSubscrip
 		type: "snapshot",
 		rows
 	});
-}))], signal);
+}))], render, signal);
 const consumeChanges = async (subscription, render, signal) => consumeSubscription(subscription, (fail) => [subscription.onReset((rows) => attempt(fail, () => render({
 	type: "reset",
 	rows
@@ -211,8 +322,8 @@ const consumeChanges = async (subscription, render, signal) => consumeSubscripti
 	type: "batch",
 	txids: batch.txids,
 	changes
-})))], signal);
-const consumeSubscription = (subscription, listenForData, signal) => new Promise((resolve, reject) => {
+})))], render, signal);
+const consumeSubscription = (subscription, listenForData, render, signal) => new Promise((resolve, reject) => {
 	let settled = false;
 	let detachData = [];
 	let detachState = () => void 0;
@@ -227,6 +338,11 @@ const consumeSubscription = (subscription, listenForData, signal) => new Promise
 	};
 	const fail = (error) => finish(reject, error);
 	const onState = (state) => {
+		attempt(fail, () => render({
+			type: "status",
+			state
+		}));
+		if (settled) return;
 		if (state.status === "error") fail(state.error);
 		else if (state.status === "closed") finish(resolve);
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "8.4.2",
+  "version": "8.4.3",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -66,10 +66,10 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
-    "@neon/config": "1.9.1",
     "@neon/config-runtime": "1.9.1",
-    "@neon/realtime": "0.0.1",
-    "@neon/sdk": "7.2.0"
+    "@neon/config": "1.9.1",
+    "@neon/sdk": "7.2.0",
+    "@neon/realtime": "0.0.1"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",