neonctl 2.22.0 → 2.23.0

package/commands/data_api.js

@@ -0,0 +1,286 @@
+import { isAxiosError } from 'axios';
+import { retryOnLock } from '../api.js';
+import { branchIdFromProps, fillSingleProject, resolveSingleDatabase, } from '../utils/enrichers.js';
+import { log } from '../log.js';
+import { writer } from '../writer.js';
+const SETTINGS_FIELDS = [
+    'db_aggregates_enabled',
+    'db_anon_role',
+    'db_extra_search_path',
+    'db_max_rows',
+    'db_schemas',
+    'jwt_role_claim_key',
+    'jwt_cache_max_lifetime',
+    'openapi_mode',
+    'server_cors_allowed_origins',
+    'server_timing_enabled',
+];
+const settingsFlags = {
+    'db-aggregates-enabled': {
+        type: 'boolean',
+        describe: 'Enable aggregate functions in queries',
+    },
+    'db-anon-role': {
+        type: 'string',
+        describe: 'Database role used for anonymous (unauthenticated) requests',
+    },
+    'db-extra-search-path': {
+        type: 'string',
+        describe: 'Extra schemas appended to the search path',
+    },
+    'db-max-rows': {
+        type: 'number',
+        describe: 'Maximum number of rows returned by a single request',
+    },
+    'db-schemas': {
+        type: 'string',
+        describe: 'Comma-separated list of schemas exposed via the Data API',
+    },
+    'jwt-role-claim-key': {
+        type: 'string',
+        describe: 'JWT claim path used to extract the role',
+    },
+    'jwt-cache-max-lifetime': {
+        type: 'number',
+        describe: 'Maximum JWT cache lifetime in seconds',
+    },
+    'openapi-mode': {
+        type: 'string',
+        choices: ['ignore-privileges', 'disabled'],
+        describe: 'OpenAPI mode',
+    },
+    'server-cors-allowed-origins': {
+        type: 'string',
+        describe: 'CORS allowed origins',
+    },
+    'server-timing-enabled': {
+        type: 'boolean',
+        describe: 'Enable Server-Timing response headers',
+    },
+};
+export const command = 'data-api';
+export const describe = 'Manage the Neon Data API for a database';
+export const builder = (argv) => argv
+    .usage('$0 data-api <sub-command> [options]')
+    .options({
+    'project-id': {
+        describe: 'Project ID',
+        type: 'string',
+    },
+    branch: {
+        describe: 'Branch ID or name',
+        type: 'string',
+    },
+    database: {
+        describe: 'Database name',
+        type: 'string',
+    },
+})
+    .middleware(fillSingleProject)
+    .command('create', 'Provision the Neon Data API for a database', (yargs) => yargs.options({
+    'auth-provider': {
+        type: 'string',
+        choices: ['neon_auth', 'external'],
+        describe: 'Authentication provider',
+    },
+    'jwks-url': {
+        type: 'string',
+        describe: 'URL that lists the JWKS (used with external auth)',
+    },
+    'provider-name': {
+        type: 'string',
+        describe: 'Name of the auth provider (e.g. Clerk, Stytch, Auth0)',
+    },
+    'jwt-audience': {
+        type: 'string',
+        describe: 'Expected JWT audience claim',
+    },
+    'add-default-grants': {
+        type: 'boolean',
+        describe: 'Grant all permissions on tables in the public schema to authenticated users',
+    },
+    'skip-auth-schema': {
+        type: 'boolean',
+        describe: 'Skip creating the auth schema and RLS functions',
+    },
+    ...settingsFlags,
+}), (args) => create(args))
+    .command('get', 'Show the Neon Data API status and settings', (yargs) => yargs, (args) => get(args))
+    .command('update', 'Update Neon Data API settings (merges with current settings by default)', (yargs) => yargs.options({
+    replace: {
+        type: 'boolean',
+        default: false,
+        describe: 'Replace settings with only the flags provided. Omitted settings revert to server defaults.',
+    },
+    ...settingsFlags,
+}), (args) => update(args))
+    .command('refresh-schema', 'Refresh the Data API schema cache without changing settings', (yargs) => yargs, (args) => refreshSchema(args))
+    .command('delete', 'Tear down the Neon Data API for a database', (yargs) => yargs, (args) => deleteDataApi(args));
+export const handler = (args) => {
+    return args;
+};
+const TOP_LEVEL_CREATE_FIELDS = [
+    'auth_provider',
+    'jwks_url',
+    'provider_name',
+    'jwt_audience',
+    'add_default_grants',
+    'skip_auth_schema',
+];
+const argKey = (snake) => snake.replace(/_/g, '-');
+const buildSettings = (args) => {
+    const settings = {};
+    for (const field of SETTINGS_FIELDS) {
+        const value = args[argKey(field)];
+        if (value === undefined)
+            continue;
+        if (field === 'db_schemas' && typeof value === 'string') {
+            settings[field] = value
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+        }
+        else {
+            settings[field] = value;
+        }
+    }
+    return Object.keys(settings).length > 0
+        ? settings
+        : undefined;
+};
+const buildCreateBody = (args) => {
+    const body = {};
+    for (const field of TOP_LEVEL_CREATE_FIELDS) {
+        const value = args[argKey(field)];
+        if (value !== undefined)
+            body[field] = value;
+    }
+    const settings = buildSettings(args);
+    if (settings)
+        body.settings = settings;
+    return body;
+};
+const create = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const database = await resolveSingleDatabase({
+        apiClient: props.apiClient,
+        projectId: props.projectId,
+        branchId,
+        database: props.database,
+    });
+    const body = buildCreateBody(props);
+    const { data } = await retryOnLock(() => props.apiClient.createProjectBranchDataApi(props.projectId, branchId, database, body));
+    writer(props).end(data, { fields: ['url'] });
+};
+const GET_FIELDS = ['url', 'status', 'db_schemas'];
+const get = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const database = await resolveSingleDatabase({
+        apiClient: props.apiClient,
+        projectId: props.projectId,
+        branchId,
+        database: props.database,
+    });
+    const { data } = await props.apiClient.getProjectBranchDataApi(props.projectId, branchId, database);
+    // Drop available_schemas from json/yaml output (not part of the public surface).
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { available_schemas: _ignored, ...publicData } = data;
+    // For table output, flatten db_schemas onto the top-level for column rendering.
+    const tableRow = {
+        url: publicData.url,
+        status: publicData.status,
+        db_schemas: (publicData.settings?.db_schemas ?? []).join(', '),
+    };
+    if (props.output === 'json' || props.output === 'yaml') {
+        writer(props).end(publicData, {
+            fields: ['url', 'status', 'settings'],
+        });
+        return;
+    }
+    writer(props).end(tableRow, { fields: GET_FIELDS });
+};
+const update = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const database = await resolveSingleDatabase({
+        apiClient: props.apiClient,
+        projectId: props.projectId,
+        branchId,
+        database: props.database,
+    });
+    const userSettings = buildSettings(props);
+    if (!userSettings) {
+        throw new Error('No settings flags provided. Pass at least one setting flag to update, or use `data-api refresh-schema` to refresh the schema cache without changing settings.');
+    }
+    let settings;
+    if (props.replace) {
+        settings = userSettings;
+    }
+    else {
+        let current;
+        try {
+            const { data } = await props.apiClient.getProjectBranchDataApi(props.projectId, branchId, database);
+            current = data.settings ?? undefined;
+        }
+        catch (err) {
+            if (isAxiosError(err) && err.response?.status === 404) {
+                throw new Error(`Data API is not provisioned for ${database} on branch ${branchId}. Run \`neonctl data-api create\` first.`);
+            }
+            throw err;
+        }
+        if (!current) {
+            throw new Error(`Could not read current Data API settings for ${database} on branch ${branchId}. Retry, or pass --replace to overwrite.`);
+        }
+        settings = { ...current, ...(userSettings ?? {}) };
+    }
+    const body = {};
+    if (settings)
+        body.settings = settings;
+    try {
+        await retryOnLock(() => props.apiClient.updateProjectBranchDataApi(props.projectId, branchId, database, body));
+    }
+    catch (err) {
+        if (isAxiosError(err) && err.response?.status === 404) {
+            throw new Error(`Data API is not provisioned for ${database} on branch ${branchId}. Run \`neonctl data-api create\` first.`);
+        }
+        throw err;
+    }
+    log.info(`Data API settings updated for ${database} on branch ${branchId}`);
+};
+const refreshSchema = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const database = await resolveSingleDatabase({
+        apiClient: props.apiClient,
+        projectId: props.projectId,
+        branchId,
+        database: props.database,
+    });
+    try {
+        await retryOnLock(() => props.apiClient.updateProjectBranchDataApi(props.projectId, branchId, database, {}));
+    }
+    catch (err) {
+        if (isAxiosError(err) && err.response?.status === 404) {
+            throw new Error(`Data API is not provisioned for ${database} on branch ${branchId}. Run \`neonctl data-api create\` first.`);
+        }
+        throw err;
+    }
+    log.info(`Data API schema cache refreshed for ${database} on branch ${branchId}`);
+};
+const deleteDataApi = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const database = await resolveSingleDatabase({
+        apiClient: props.apiClient,
+        projectId: props.projectId,
+        branchId,
+        database: props.database,
+    });
+    try {
+        await retryOnLock(() => props.apiClient.deleteProjectBranchDataApi(props.projectId, branchId, database));
+    }
+    catch (err) {
+        if (isAxiosError(err) && err.response?.status === 404) {
+            throw new Error(`Data API is not provisioned for ${database} on branch ${branchId}.`);
+        }
+        throw err;
+    }
+    log.info(`Data API deleted for ${database} on branch ${branchId}`);
+};

package/commands/functions.js

@@ -0,0 +1,277 @@
+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]([a-z0-9-]{0,38}[a-z0-9])?$/;
+const SLUG_HELP = 'Use 1-40 lowercase letters, digits, and hyphens; it must start and end with a letter or digit.';
+const MEMORY_CHOICES = [256, 512, 1024, 2048, 4096, 8192];
+// 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 (lowercase DNS label)',
+    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',
+    },
+    'memory-mib': {
+        describe: 'Memory in MiB',
+        type: 'number',
+        choices: MEMORY_CHOICES,
+    },
+    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.memoryMib !== 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 memoryMib = props.memoryMib ?? 256;
+    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,
+        memoryMib,
+        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

@@ -9,8 +9,14 @@ import * as databases from './databases.js';
 import * as roles from './roles.js';
 import * as operations from './operations.js';
 import * as cs from './connection_string.js';
+import * as psql from './psql.js';
 import * as setContext from './set_context.js';
+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,
@@ -18,11 +24,17 @@ export default [
     projects,
     ipAllow,
     vpcEndpoints,
+    neonAuth,
     branches,
     databases,
     roles,
     operations,
     cs,
+    psql,
     setContext,
+    checkout,
+    link,
     init,
+    dataApi,
+    functions,
 ];