neon 8.4.2 → 8.4.4

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/analytics.js

@@ -2,7 +2,7 @@ import { a as OAUTH, t as storeFor } from "./_chunks/credential_io-ByNuojoE.js";
 import { getCliAgent, getGithubEnvVars, isCi } from "./env.js";
 import { log } from "./log.js";
 import pkg_default from "./pkg.js";
-import { getApiClient, isNeonApiError } from "./api.js";
+import { UnreadableResponseError, getApiClient, isNeonApiError } from "./api.js";
 import { getAuthContext } from "./auth_context.js";
 import { n as credentialsPath } from "./_chunks/paths-DMq0Lt7a.js";
 import "./config.js";
@@ -271,7 +271,7 @@ const sendError = (err, errCode) => {
 		});
 	});
 	log.debug("Sent CLI error event: %s", errCode);
-	if (errCode === "UNKNOWN_ERROR" && isUnexpectedError(err)) {
+	if (errCode === "UNKNOWN_ERROR" && isUnexpectedError(err) || err instanceof UnreadableResponseError) {
 		const report = import("./error_reporting.js").then(({ reportUnexpectedError }) => reportUnexpectedError(err, redactCredentialTokenIds)).catch((reportError) => {
 			log.debug("Could not report the error to Sentry: %s", reportError);
 		});

package/dist/api.js

@@ -42,6 +42,16 @@ var NeonApiError = class extends Error {
 		this.code = init.code;
 	}
 };
+/**
+* A 2xx response whose body could not be read or parsed. The request succeeded, so this is
+* reported to Sentry as well as counted as an API error.
+*/
+var UnreadableResponseError = class extends NeonApiError {
+	constructor(message, init) {
+		super(message, init);
+		this.name = "UnreadableResponseError";
+	}
+};
 /** Narrow an unknown error to a {@link NeonApiError}. */
 function isNeonApiError(err) {
 	return err instanceof NeonApiError;
@@ -170,6 +180,20 @@ function httpError(response, body) {
 	});
 }
 /**
+* The cause's message is left out: `JSON.parse` quotes the input, and the body can carry a
+* password or token that would reach stderr and analytics.
+*/
+function unreadableBodyError(response, cause) {
+	const base = httpError(response, void 0);
+	const reason = cause instanceof SyntaxError ? "the body is not valid JSON" : "the body could not be read";
+	return new UnreadableResponseError(`Could not read the Neon API response (${response.status} ${response.statusText}) to ${base.requestPath ?? "the request"}: ${reason}`, {
+		status: base.status,
+		statusText: base.statusText,
+		headers: base.headers,
+		requestPath: base.requestPath
+	});
+}
+/**
 * Translate a thrown `fetch` failure into a {@link NeonApiError}. A request
 * timeout uses `ECONNABORTED` (matching the old axios behaviour, and excluded
 * from `isNetworkError`'s connectivity codes so it's still reported as a
@@ -283,6 +307,7 @@ const getApiClient = ({ apiKey, apiHost, requestTimeoutMs = REQUEST_TIMEOUT_MS }
 		const response = result.response;
 		if (!response) throw networkError(result.error ?? /* @__PURE__ */ new Error("No response from Neon API"));
 		if (!response.ok) throw httpError(response, rawErrorBody(result.error) ?? result.data);
+		if (result.error !== void 0 && result.error !== null) throw unreadableBodyError(response, rawErrorBody(result.error));
 		return {
 			data: result.data,
 			status: response.status,
@@ -978,4 +1003,4 @@ const getApiClient = ({ apiKey, apiHost, requestTimeoutMs = REQUEST_TIMEOUT_MS }
 	};
 };
 //#endregion
-export { ContentType, NeonApiError, codeFromBody, getApiClient, isNeonApiError, messageFromBody, retryOnLock };
+export { ContentType, NeonApiError, UnreadableResponseError, codeFromBody, getApiClient, isNeonApiError, messageFromBody, retryOnLock };

package/dist/commands/dev.js

@@ -4,11 +4,11 @@ import { isClaimableEnvTarget } from "../claimable/state.js";
 import { getCliName } from "../utils/cli_name.js";
 import { readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { l as functionBaseUrlKey } from "../_chunks/env-BpP3Dqpe.js";
-import { branchIdResolve } from "../utils/enrichers.js";
-import { bundleEntry } from "../utils/esbuild.js";
 import { a as resolveDevEnv } from "../_chunks/env-4WGRW2nw.js";
 import { findConfigFunctionBySource, resolveFunctionsFromConfig } from "../dev/functions.js";
 import { resolveWatchInputs } from "../dev/inputs.js";
+import { branchIdResolve } from "../utils/enrichers.js";
+import { bundleEntry } from "../utils/esbuild.js";
 import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/commands/env.js

@@ -8,9 +8,9 @@ import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { t as NEON_ENV_VAR_KEYS, u as isFunctionBaseUrlKey } from "../_chunks/env-BpP3Dqpe.js";
 import { ENV_PULL_KEY_HELP, ENV_PULL_SERVICES, envKeysForSelection, envPullFlagValue, ownedEnvServiceKeys, parseEnvPullKeys } from "../env_services.js";
 import { listedServices } from "../utils/staging.js";
+import { i as dropClaimableUnsupported, o as resolveNeonEnvVars } from "../_chunks/env-4WGRW2nw.js";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { warnAiGateway } from "../utils/ai_gateway_notice.js";
-import { i as dropClaimableUnsupported, o as resolveNeonEnvVars } from "../_chunks/env-4WGRW2nw.js";
 import { formatPulledEnv, pulledBranch } from "./env_output.js";
 import { existsSync } from "node:fs";
 import chalk from "chalk";

package/dist/commands/subscribe.js

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { writer } from "../writer.js";
-import { branchIdFromProps, fillSingleProject } from "../utils/enrichers.js";
 import { o as resolveNeonEnvVars } from "../_chunks/env-4WGRW2nw.js";
+import { branchIdFromProps, fillSingleProject } from "../utils/enrichers.js";
 import YAML from "yaml";
 //#region src/commands/subscribe.ts
 var subscribe_exports = /* @__PURE__ */ __exportAll({
@@ -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,46 +192,135 @@ 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();
 	for (const row of rows) for (const key of Object.keys(row)) seen.add(key);
 	return [...seen];
 };
-const consumeSnapshots = async (subscription, render, signal) => consumeSubscription(subscription, (fail) => [subscription.onReset(() => attempt(fail, () => {
-	const rows = subscription.getSnapshot().data;
-	if (rows !== void 0) render({
-		type: "snapshot",
-		rows
-	});
-})), subscription.onBatch(() => attempt(fail, () => {
+const consumeSnapshots = async (subscription, render, signal) => consumeSubscription(subscription, (fail) => [subscription.onUpdate(() => attempt(fail, () => {
 	const rows = subscription.getSnapshot().data;
 	if (rows !== void 0) render({
 		type: "snapshot",
 		rows
 	});
-}))], signal);
-const consumeChanges = async (subscription, render, signal) => consumeSubscription(subscription, (fail) => [subscription.onReset((rows) => attempt(fail, () => render({
-	type: "reset",
-	rows
-}))), subscription.onBatch((changes, batch) => attempt(fail, () => render({
-	type: "batch",
-	txids: batch.txids,
-	changes
-})))], signal);
-const consumeSubscription = (subscription, listenForData, signal) => new Promise((resolve, reject) => {
+}))], render, signal);
+const consumeChanges = async (subscription, render, signal) => consumeSubscription(subscription, (fail) => [subscription.onUpdate((update) => {
+	if (update.type === "rows") attempt(fail, () => render({
+		type: "reset",
+		rows: update.rows
+	}));
+	else attempt(fail, () => render({
+		type: "batch",
+		txids: update.batch.txids,
+		changes: update.changes
+	}));
+})], render, signal);
+const consumeSubscription = (subscription, listenForData, render, signal) => new Promise((resolve, reject) => {
 	let settled = false;
 	let detachData = [];
 	let detachState = () => void 0;
@@ -227,6 +335,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/dist/index.js

@@ -1,6 +1,6 @@
 import { log } from "./log.js";
 import pkg_default from "./pkg.js";
-import { codeFromBody, isNeonApiError, messageFromBody } from "./api.js";
+import { UnreadableResponseError, codeFromBody, isNeonApiError, messageFromBody } from "./api.js";
 import { getAuthContext } from "./auth_context.js";
 import { r as defaultDir } from "./_chunks/paths-DMq0Lt7a.js";
 import { ensureConfigDir } from "./config.js";
@@ -188,6 +188,7 @@ async function handleError(msg, err, canRetry) {
 		} else {
 			const serverMessage = messageFromBody(err.data);
 			if (serverMessage) log.error(serverMessage);
+			else if (err instanceof UnreadableResponseError) log.error(err.message);
 			else log.error([`HTTP ${err.status ?? ""} ${err.statusText ?? ""}`.trim(), err.requestPath].filter(Boolean).join(" | "));
 			log.debug("status: %d %s | path: %s", err.status, err.statusText, err.requestPath);
 			sendError(err, "API_ERROR");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "8.4.2",
+  "version": "8.4.4",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -68,7 +68,7 @@
     "yoctocolors": "^2.1.2",
     "@neon/config": "1.9.1",
     "@neon/config-runtime": "1.9.1",
-    "@neon/realtime": "0.0.1",
+    "@neon/realtime": "0.0.3",
     "@neon/sdk": "7.2.0"
   },
   "optionalDependencies": {