neonctl 2.22.2 → 2.23.1

package/README.md

@@ -58,6 +58,80 @@ neonctl projects list --api-key <neon_api_key>
 
 For information about obtaining an Neon API key, see [Authentication](https://api-docs.neon.tech/reference/authentication), in the _Neon API Reference_.
 
+## Connect with psql
+
+Several commands accept a `--psql` flag that opens a psql session against the resolved endpoint:
+
+```bash
+neonctl connection-string --psql --project-id <id>
+neonctl projects create --psql
+neonctl branches create --psql
+```
+
+Any arguments after `--` are forwarded to psql, for example:
+
+```bash
+neonctl cs --psql --project-id <id> -- -c "SELECT version()"
+neonctl cs --psql --project-id <id> -- -f script.sql --csv
+```
+
+### Embedded psql fallback
+
+If the system has `psql` installed on `$PATH`, `--psql` continues to spawn the native binary — there is no behavior change for existing users.
+
+If `psql` is not found on `$PATH`, neonctl now falls back to an embedded TypeScript implementation. There is nothing to install or configure; it ships with `neonctl`. This removes the "no psql binary" trap on machines (and CI runners) that don't have PostgreSQL client tools installed.
+
+Automatic fallback is the intended path — there is normally no flag to set. The embedded implementation can also be force-selected (primarily for tests and CI, e.g. to exercise it even when a native `psql` is present):
+
+- `--fallback` — force the embedded implementation on `connection-string`, `projects create`, and `branches create`. Intentionally hidden from `--help`: it's a test/CI knob, not a user-facing option (the automatic fallback above is the supported behavior).
+- `NEONCTL_PSQL_FALLBACK=1` — environment variable with the same effect as `--fallback`. Convenient for scripts and CI.
+
+The embedded implementation is verified against a conformance suite that
+diffs its behavior against real PostgreSQL (14–18) and the upstream psql
+regression + TAP tests.
+
+#### What works
+
+**REPL & scripting**
+
+- Interactive REPL with a hand-rolled VT100 line editor (no native bindings); vi and emacs edit modes (`VI_MODE` psql variable)
+- Persistent command history (`~/.psql_history`, libreadline format)
+- `~/.psqlrc` autoload (including `$PGSYSCONFDIR/psqlrc` and version-suffixed variants)
+- Scripted modes: `-c "SQL"`, `-f script.sql`, and stdin; `--single-transaction`, `ON_ERROR_STOP`, `ECHO`, `--echo-all`
+- `SINGLELINE` (`-S`), `\timing`, `\watch` (named flags `c=`/`i=`/`m=`, unbounded continuous mode)
+
+**Backslash commands**
+
+- All output formats: aligned, unaligned, wrapped, csv, json, html, asciidoc, latex, latex-longtable, troff-ms (`\a \H \t \x \pset \f \C` …)
+- All `\d*` describe commands with full upstream parity (columns, indexes, foreign keys, triggers, view definitions, sequences, RLS, replica identity, partitions, tablespaces, access methods, inheritance, FDW, stats objects, publications, subscriptions, per-column FDW options, TOAST owner)
+- `\copy` to/from file, `PROGRAM`, `STDIN`, `STDOUT` (incl. the `\.` EOF marker); `\g` / `\gx` / `\gset` / `\gdesc` / `\gexec` and `\g | program` pipes
+- Extended query + pipeline mode (`\bind`, `\bind_named`, `\startpipeline`, `\parse`, `\sendpipeline`)
+- `\crosstabview`, `\lo_*` large objects, `\e`/`\edit` (external editor), `\s` (history), `\?`/`\h` help, `\if`/`\elif`/`\else`/`\endif`, `\set`/`\unset`, `\connect`, `\encoding` (live `SET client_encoding`), `\!`, `\cd`, `\prompt` (incl. no-echo `-`), `\password`
+- Tab completion (~88 rules incl. live `pg_settings` GUC lookup, deep `ALTER` sub-actions, `JOIN` clauses, window `OVER`)
+
+**Connection & authentication**
+
+- libpq-equivalent lookup precedence: argv flags > URI > `PG*` env vars > `~/.pgpass` > `pg_service.conf` > libpq defaults
+- SCRAM-SHA-256 / SCRAM-SHA-256-PLUS with `tls-server-end-point` channel binding (`channel_binding`); MD5 and cleartext; `require_auth`
+- Multi-host failover & load balancing: `target_session_attrs` (any / read-write / read-only / primary / standby / prefer-standby), `load_balance_hosts`, DNS fan-out, `hostaddr`
+- Unix-domain sockets (host beginning with `/`); TCP keepalives (`keepalives`, `keepalives_idle`)
+
+**TLS**
+
+- `sslmode` disable → verify-full; client certs in **PEM or DER** via `sslcert` / `sslkey` (+ `sslpassword` for encrypted keys, with the libpq group/world-readable-key check)
+- Trust config: `sslrootcert` (incl. `=system` with `SSL_CERT_FILE` / `SSL_CERT_DIR`), default client-cert discovery (`~/.postgresql/postgresql.{crt,key}`), `sslcertmode`
+- CRL: `sslcrl` and `sslcrldir`; `ssl_min_protocol_version` / `ssl_max_protocol_version`; `sslsni`
+- Direct-SSL negotiation (`sslnegotiation=direct`, PostgreSQL 17+, via ALPN)
+
+#### What's not supported
+
+- **GSSAPI / SSPI** (`gssencmode`, Kerberos/SSPI auth, `requirepeer`). GSS transport encryption needs a native Kerberos binding, which the embedded psql deliberately avoids (pure TypeScript, zero native dependencies — the same reason the line editor is hand-rolled). `node-postgres` doesn't support it either, and Neon doesn't use it. `gssencmode=disable` / `prefer` are accepted; `gssencmode=require` is rejected with a clear error. `requirepeer` is parsed but a Unix-socket connection that sets it is refused (Node exposes no peer-credential API — it is not silently ignored).
+- **`keepalives_interval` / `keepalives_count`** — Node's socket API exposes only keepalive enable + initial delay, so these are accepted but not applied.
+
+### Known limitations
+
+- **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.
+
 ## Configure autocompletion
 
 The Neon CLI supports autocompletion, which you can configure in a few easy steps. See [Neon CLI commands — completion](https://neon.tech/docs/reference/cli-completion) for instructions.
@@ -205,6 +279,7 @@ $ cat .neon
 | [me](https://neon.com/docs/reference/cli-me)                               |                                                                                             | Show current user              |
 | [branches](https://neon.com/docs/reference/cli-branches)                   | `list`, `create`, `rename`, `add-compute`, `set-default`, `set-expiration`, `delete`, `get` | Manage branches                |
 | [databases](https://neon.com/docs/reference/cli-databases)                 | `list`, `create`, `delete`                                                                  | Manage databases               |
+| functions                                                                  | `deploy`, `list`, `get`, `delete`                                                           | Manage Neon Functions          |
 | [roles](https://neon.com/docs/reference/cli-roles)                         | `list`, `create`, `delete`                                                                  | Manage roles                   |
 | [operations](https://neon.com/docs/reference/cli-operations)               | `list`                                                                                      | Manage operations              |
 | [connection-string](https://neon.com/docs/reference/cli-connection-string) |                                                                                             | Get connection string          |
@@ -299,6 +374,15 @@ To run commands from the local build, replace the `neonctl` command with `node d
 node dist branches --help
 ```
 
+### Embedded psql tests
+
+The embedded TypeScript psql implementation has its own conformance test suite that runs the same scripts against the embedded psql and a reference `psql` binary, then diffs the output.
+
+```shell
+bun run test:conformance         # run against $PSQL_BINARY (defaults to the system psql)
+bun run test:conformance:matrix  # run across PG 14/15/16/17/18 locally (requires Docker)
+```
+
 ## Releasing
 
 Maintainers: see [`RELEASING.md`](./RELEASING.md) for the two-stage publish flow.

package/analytics.js

@@ -84,10 +84,13 @@ export const analyticsMiddleware = async (args) => {
         },
     });
 };
-export const closeAnalytics = async () => {
+export const closeAnalytics = async (opts) => {
     if (client) {
         log.debug('Flushing CLI analytics');
-        await client.closeAndFlush();
+        // `timeout` bounds how long we wait for in-flight events to flush so a
+        // slow / unreachable track.neon.tech can't hang a short-lived command
+        // (e.g. the psql launch path, which flushes here before process.exit).
+        await client.closeAndFlush(opts);
         log.debug('Flushed CLI analytics');
     }
 };

package/commands/branches.js

@@ -75,6 +75,12 @@ export const builder = (argv) => argv
         describe: 'Connect to a new branch via psql',
         default: false,
     },
+    fallback: {
+        type: 'boolean',
+        describe: 'Force the embedded TypeScript psql fallback (for testing)',
+        default: false,
+        hidden: true,
+    },
     annotation: {
         type: 'string',
         hidden: true,
@@ -325,7 +331,9 @@ const create = async (props) => {
         }
         const connection_uri = data.connection_uris[0].connection_uri;
         const psqlArgs = props['--'];
-        await psql(connection_uri, psqlArgs);
+        await psql(connection_uri, psqlArgs, {
+            mode: props.fallback ? 'ts' : 'auto',
+        });
     }
 };
 const rename = async (props) => {

package/commands/connection_string.js

@@ -59,6 +59,12 @@ export const builder = (argv) => {
             describe: 'Connect to a database via psql using connection string',
             default: false,
         },
+        fallback: {
+            type: 'boolean',
+            describe: 'Force the embedded TypeScript psql fallback (for testing)',
+            default: false,
+            hidden: true,
+        },
         ssl: {
             type: 'string',
             choices: SSL_MODES,
@@ -146,7 +152,9 @@ export const handler = async (props) => {
     }
     if (props.psql) {
         const psqlArgs = props['--'];
-        await psql(connectionString.toString(), psqlArgs);
+        await psql(connectionString.toString(), psqlArgs, {
+            mode: props.fallback ? 'ts' : 'auto',
+        });
     }
     else if (props.extended) {
         writer(props).end({

package/commands/functions.js

@@ -0,0 +1,268 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isAxiosError } from 'axios';
+import { retryOnLock } from '../api.js';
+import { log } from '../log.js';
+import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
+import { zipBundle } from '../utils/zip.js';
+import { bundleEntry } from '../utils/esbuild.js';
+import { writer } from '../writer.js';
+import { createDeployment, deleteFunction, getFunction, listFunctions, } from '../functions_api.js';
+const FUNCTION_FIELDS = [
+    'slug',
+    'name',
+    'invocation_url',
+    'created_at',
+];
+const DEPLOYMENT_FIELDS = [
+    'id',
+    'status',
+    'runtime',
+    'memory_mib',
+    'created_at',
+];
+const SLUG_PATTERN = /^[a-z0-9]{1,20}$/;
+const SLUG_HELP = 'Use 1-20 lowercase letters and digits (no hyphens or other characters).';
+// Overridable so tests can poll fast; defaults to 2s in real use.
+const POLL_INTERVAL_MS = Number(process.env.NEON_FUNCTIONS_POLL_INTERVAL_MS) || 2000;
+// Upper bound on --wait polling so the CLI never hangs (e.g. if our deployment
+// never becomes active_deployment). Overridable so tests can time out fast;
+// defaults to 10 minutes in real use.
+const POLL_TIMEOUT_MS = Number(process.env.NEON_FUNCTIONS_POLL_TIMEOUT_MS) || 600000;
+export const command = 'functions';
+export const describe = 'Manage Neon Functions';
+export const aliases = ['function'];
+export const builder = (argv) => argv
+    .usage('$0 functions <sub-command> [options]')
+    .options({
+    'project-id': {
+        describe: 'Project ID',
+        type: 'string',
+    },
+    branch: {
+        describe: 'Branch ID or name',
+        type: 'string',
+    },
+})
+    .middleware(fillSingleProject)
+    .command('deploy <slug>', 'Deploy a function from a local directory', (yargs) => yargs
+    .positional('slug', {
+    describe: 'Function slug (1-20 lowercase letters and digits)',
+    type: 'string',
+    demandOption: true,
+})
+    .options({
+    path: {
+        describe: 'Base directory for the function (resolves --entry)',
+        type: 'string',
+    },
+    entry: {
+        describe: 'Entry file to bundle, relative to --path',
+        type: 'string',
+    },
+    runtime: {
+        describe: 'Function runtime',
+        type: 'string',
+        choices: ['nodejs24'],
+    },
+    env: {
+        describe: 'Environment variable as KEY=VALUE (repeatable)',
+        type: 'string',
+        array: true,
+    },
+    wait: {
+        describe: 'Wait for the deployment to finish building',
+        type: 'boolean',
+        default: true,
+    },
+}), (args) => deploy(args))
+    .command('list', 'List functions on the branch', (yargs) => yargs, (args) => list(args))
+    .command('get <slug>', "Show a function's details", (yargs) => yargs.positional('slug', {
+    describe: 'Function slug',
+    type: 'string',
+    demandOption: true,
+}), (args) => get(args))
+    .command('delete <slug>', 'Delete a function on the branch', (yargs) => yargs.positional('slug', {
+    describe: 'Function slug',
+    type: 'string',
+    demandOption: true,
+}), (args) => deleteFn(args));
+export const handler = (args) => {
+    return args;
+};
+const parseEnv = (entries) => {
+    if (!entries || entries.length === 0)
+        return undefined;
+    const map = {};
+    for (const entry of entries) {
+        const eq = entry.indexOf('=');
+        if (eq <= 0) {
+            throw new Error(`Invalid --env value "${entry}". Expected KEY=VALUE.`);
+        }
+        map[entry.slice(0, eq)] = entry.slice(eq + 1);
+    }
+    return JSON.stringify(map);
+};
+const statusHint = (slug, projectId, branchId) => `Check status with: neonctl functions get ${slug} --project-id ${projectId} --branch ${branchId}`;
+// A poll error worth retrying: a network error (no HTTP response), a 5xx, or a
+// 404 from eventual consistency. Anything else (e.g. 401/403) is surfaced.
+const isTransient = (err) => isAxiosError(err) &&
+    (err.response === undefined ||
+        err.response.status === 404 ||
+        err.response.status >= 500);
+const deploy = async (props) => {
+    // At least one deploy option must be passed (--wait is excluded: it controls
+    // output, not what gets deployed).
+    const hasOption = props.path !== undefined ||
+        props.entry !== undefined ||
+        props.env !== undefined ||
+        props.runtime !== undefined;
+    if (!hasOption) {
+        throw new Error('Provide at least one option to deploy, e.g. --path, --entry, or --env. ' +
+            'See: neonctl functions deploy --help.');
+    }
+    // Cheap, offline validation first - fail before any network round-trip.
+    if (!SLUG_PATTERN.test(props.slug)) {
+        throw new Error(`Invalid function slug "${props.slug}". ${SLUG_HELP}`);
+    }
+    const path = props.path ?? '.';
+    const entry = props.entry ?? 'index.ts';
+    const runtime = props.runtime ?? 'nodejs24';
+    const environment = parseEnv(props.env);
+    const source = join(path, entry);
+    if (!existsSync(source)) {
+        throw new Error(`Entry file not found: ${source}. Pass --entry to point at your function's entry file (defaults to index.ts).`);
+    }
+    // Bundle before any network round-trip so a bundling failure fails fast.
+    const zip = zipBundle(await bundleEntry(source));
+    const branchId = await branchIdFromProps(props);
+    // Snapshot the active version before deploy so we can detect the new one
+    // afterward. A missing function (404) or no active version → undefined.
+    let before;
+    try {
+        const fn = await getFunction(props.apiClient, props.projectId, branchId, props.slug);
+        before = fn.active_deployment?.id;
+    }
+    catch (err) {
+        if (!(isAxiosError(err) && err.response?.status === 404))
+            throw err;
+    }
+    await retryOnLock(() => createDeployment(props.apiClient, props.projectId, branchId, props.slug, {
+        zip,
+        runtime,
+        environment,
+    }));
+    log.info(`Function deployment triggered for function ${props.slug}.`);
+    // Best-effort interrupt: a Ctrl-C lands at the next poll boundary. (No
+    // automated test; mirrors the resolution branches below, verified manually.)
+    let interrupted = false;
+    const onSignal = () => {
+        interrupted = true;
+    };
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    // Poll until a NEW active version appears (id greater than the snapshot, or
+    // any version if there was none). --no-wait stops there; --wait stops at a
+    // terminal status. Bounded by POLL_TIMEOUT_MS so it never hangs.
+    let resolved;
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    try {
+        while (!interrupted && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+            if (interrupted)
+                break;
+            // The deploy already succeeded server-side; tolerate transient poll
+            // failures and retry on the next interval. Surface anything else.
+            let dep;
+            try {
+                dep = (await getFunction(props.apiClient, props.projectId, branchId, props.slug)).active_deployment;
+            }
+            catch (err) {
+                if (isTransient(err))
+                    continue;
+                throw err;
+            }
+            const isNew = dep !== undefined && (before === undefined || dep.id > before);
+            if (isNew && dep) {
+                resolved = dep;
+                if (!props.wait)
+                    break;
+                if (dep.status === 'completed' || dep.status === 'failed')
+                    break;
+            }
+        }
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+    }
+    if (interrupted) {
+        log.info(statusHint(props.slug, props.projectId, branchId));
+        if (resolved)
+            writer(props).end(resolved, { fields: DEPLOYMENT_FIELDS });
+        return;
+    }
+    if (resolved === undefined) {
+        log.info(statusHint(props.slug, props.projectId, branchId));
+        throw new Error(`Timed out waiting for the deployment of ${props.slug} to start. It may still be in progress.`);
+    }
+    writer(props).end(resolved, { fields: DEPLOYMENT_FIELDS });
+    if (!props.wait) {
+        log.info(statusHint(props.slug, props.projectId, branchId));
+        return;
+    }
+    if (resolved.status === 'completed') {
+        log.info(`Function deployment ${props.slug}/${resolved.id} completed.`);
+        return;
+    }
+    if (resolved.status === 'failed') {
+        throw new Error(`Function deployment ${props.slug}/${resolved.id} failed.`);
+    }
+    // --wait, new version appeared but the deadline hit before it finished.
+    log.info(statusHint(props.slug, props.projectId, branchId));
+    throw new Error(`Timed out waiting for function deployment ${props.slug}/${resolved.id} to finish. It may still be building.`);
+};
+const get = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const fn = await getFunction(props.apiClient, props.projectId, branchId, props.slug);
+    if (props.output === 'json' || props.output === 'yaml') {
+        writer(props).end(fn, { fields: FUNCTION_FIELDS });
+        return;
+    }
+    const out = writer(props).write(fn, {
+        fields: FUNCTION_FIELDS,
+        title: 'function',
+    });
+    if (fn.active_deployment) {
+        out.write(fn.active_deployment, {
+            fields: DEPLOYMENT_FIELDS,
+            title: 'active deployment',
+        });
+    }
+    out.end();
+};
+const deleteFn = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    try {
+        await retryOnLock(() => deleteFunction(props.apiClient, props.projectId, branchId, props.slug));
+    }
+    catch (err) {
+        if (isAxiosError(err) && err.response?.status === 404) {
+            throw new Error(`Function "${props.slug}" not found on branch ${branchId}.`);
+        }
+        throw err;
+    }
+    log.info(`Function ${props.slug} deleted from branch ${branchId}`);
+};
+const list = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const functions = await listFunctions(props.apiClient, props.projectId, branchId);
+    if (props.output === 'json' || props.output === 'yaml') {
+        writer(props).end(functions, { fields: FUNCTION_FIELDS });
+        return;
+    }
+    writer(props).end(functions, {
+        fields: FUNCTION_FIELDS,
+        emptyMessage: 'No functions found on this branch.',
+    });
+};

package/commands/index.js

@@ -15,6 +15,8 @@ import * as checkout from './checkout.js';
 import * as link from './link.js';
 import * as init from './init.js';
 import * as dataApi from './data_api.js';
+import * as neonAuth from './neon_auth.js';
+import * as functions from './functions.js';
 export default [
     auth,
     users,
@@ -22,6 +24,7 @@ export default [
     projects,
     ipAllow,
     vpcEndpoints,
+    neonAuth,
     branches,
     databases,
     roles,
@@ -33,4 +36,5 @@ export default [
     link,
     init,
     dataApi,
+    functions,
 ];