neonctl 2.27.1 → 2.29.0

package/dist/commands/branches.js

@@ -1,39 +1,39 @@
-import { EndpointType } from '@neondatabase/api-client';
-import { contextBranch, readContextFile } from '../context.js';
-import { writer } from '../writer.js';
-import { branchCreateRequest } from '../parameters.gen.js';
-import { retryOnLock } from '../api.js';
-import { branchIdFromProps, branchIdResolve, fillSingleProject, } from '../utils/enrichers.js';
-import { looksLikeBranchId, looksLikeLSN, looksLikeTimestamp, } from '../utils/formats.js';
-import { psql } from '../utils/psql.js';
-import { parsePointInTime } from '../utils/point_in_time.js';
-import { log } from '../log.js';
-import { parseSchemaDiffParams, schemaDiff } from './schema_diff.js';
-import { getComputeUnits } from '../utils/compute_units.js';
+import { retryOnLock } from "../api.js";
+import { contextBranch, readContextFile } from "../context.js";
+import { log } from "../log.js";
+import { branchCreateRequest } from "../parameters.gen.js";
+import { EndpointType } from "../utils/api_enums.js";
+import { getComputeUnits } from "../utils/compute_units.js";
+import { branchIdFromProps, branchIdResolve, fillSingleProject, } from "../utils/enrichers.js";
+import { looksLikeBranchId, looksLikeLSN, looksLikeTimestamp, } from "../utils/formats.js";
+import { parsePointInTime } from "../utils/point_in_time.js";
+import { psql } from "../utils/psql.js";
+import { writer } from "../writer.js";
+import { parseSchemaDiffParams, schemaDiff } from "./schema_diff.js";
 export const BRANCH_FIELDS = [
-    'name',
-    'id',
-    'current_state',
-    'created_at',
-    'expires_at',
+    "name",
+    "id",
+    "current_state",
+    "created_at",
+    "expires_at",
 ];
 const BRANCH_FIELDS_RESET = [
-    'name',
-    'id',
-    'default',
-    'current_state',
-    'created_at',
-    'last_reset_at',
+    "name",
+    "id",
+    "default",
+    "current_state",
+    "created_at",
+    "last_reset_at",
 ];
-export const command = 'branches';
-export const describe = 'Manage branches';
-export const aliases = ['branch'];
+export const command = "branches";
+export const describe = "Manage branches";
+export const aliases = ["branch"];
 export const builder = (argv) => argv
-    .usage('$0 branches <sub-command> [options]')
+    .usage("$0 branches <sub-command> [options]")
     .options({
-    'project-id': {
-        describe: 'Project ID',
-        type: 'string',
+    "project-id": {
+        describe: "Project ID",
+        type: "string",
     },
 })
     .middleware(fillSingleProject)
@@ -41,172 +41,173 @@ export const builder = (argv) => argv
     // Provide alias for analytics
     args.branchId ?? (args.branchId = args.id);
 })
-    .command('list', 'List branches', (yargs) => yargs, (args) => list(args))
-    .command('create', 'Create a branch', (yargs) => yargs.options({
-    name: branchCreateRequest['branch.name'],
+    .command("list", "List branches", (yargs) => yargs, (args) => list(args))
+    .command("create", "Create a branch", (yargs) => yargs.options({
+    name: branchCreateRequest["branch.name"],
     parent: {
-        describe: 'Parent branch name or id or timestamp or LSN. Defaults to the default branch',
-        type: 'string',
+        describe: "Parent branch name or id or timestamp or LSN. Defaults to the default branch",
+        type: "string",
     },
     compute: {
-        describe: 'Create a branch with or without a compute. By default branch is created with a read-write compute. To create a branch without compute use --no-compute',
-        type: 'boolean',
+        describe: "Create a branch with or without a compute. By default branch is created with a read-write compute. To create a branch without compute use --no-compute",
+        type: "boolean",
         default: true,
     },
     type: {
-        describe: 'Type of compute to add',
-        type: 'string',
-        implies: 'compute',
+        describe: "Type of compute to add",
+        type: "string",
+        implies: "compute",
         default: EndpointType.ReadWrite,
         choices: Object.values(EndpointType),
     },
-    'suspend-timeout': {
-        describe: 'Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the global default.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe maximum value is `604800` seconds (1 week).',
-        type: 'number',
-        implies: 'compute',
+    "suspend-timeout": {
+        describe: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the global default.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe maximum value is `604800` seconds (1 week).",
+        type: "number",
+        implies: "compute",
         default: 0,
     },
     cu: {
         describe: 'The number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3").',
-        type: 'string',
-        implies: 'compute',
+        type: "string",
+        implies: "compute",
     },
     psql: {
-        type: 'boolean',
-        describe: 'Connect to a new branch via psql',
+        type: "boolean",
+        describe: "Connect to a new branch via psql",
         default: false,
     },
     fallback: {
-        type: 'boolean',
-        describe: 'Force the embedded TypeScript psql fallback (for testing)',
+        type: "boolean",
+        describe: "Force the embedded TypeScript psql fallback (for testing)",
         default: false,
         hidden: true,
     },
     annotation: {
-        type: 'string',
+        type: "string",
         hidden: true,
-        default: '{}',
+        default: "{}",
     },
-    'schema-only': {
-        describe: 'Create a schema-only branch. Requires exactly one read-write compute.',
-        type: 'boolean',
+    "schema-only": {
+        describe: "Create a schema-only branch. Requires exactly one read-write compute.",
+        type: "boolean",
         default: false,
     },
-    'expires-at': {
-        describe: 'Set an expiration date for the branch. Accepts a date string (e.g., 2024-12-31T23:59:59Z).',
-        type: 'string',
+    "expires-at": {
+        describe: "Set an expiration date for the branch. Accepts a date string (e.g., 2024-12-31T23:59:59Z).",
+        type: "string",
         requiresArg: true,
     },
 }), (args) => create(args))
-    .command('reset <id|name>', 'Reset a branch', (yargs) => yargs.options({
+    .command("reset <id|name>", "Reset a branch", (yargs) => yargs.options({
     parent: {
-        describe: 'Reset to a parent branch',
-        type: 'boolean',
+        describe: "Reset to a parent branch",
+        type: "boolean",
         default: false,
     },
-    'preserve-under-name': {
-        describe: 'Name under which to preserve the old branch',
+    "preserve-under-name": {
+        describe: "Name under which to preserve the old branch",
     },
 }), (args) => reset(args))
-    .command('restore <target-id|name> <source>[@(timestamp|lsn)]', 'Restores a branch to a specific point in time\n<source> can be: ^self, ^parent, or <source-branch-id|name>', (yargs) => yargs
+    .command("restore <target-id|name> <source>[@(timestamp|lsn)]", "Restores a branch to a specific point in time\n<source> can be: ^self, ^parent, or <source-branch-id|name>", (yargs) => yargs
     // we want to show meaningful help for the command
     // but it makes yargs to fail on parsing the command
     // so we need to fill in the missing args manually
     .middleware((args) => {
     args.id = args.targetId;
-    args.pointInTime = args['source@(timestamp'];
+    args.pointInTime = args["source@(timestamp"];
     args.branchId = args.id; // for analytics
 })
-    .usage('$0 branches restore <target-id|name> <source>[@(timestamp|lsn)]')
+    .usage("$0 branches restore <target-id|name> <source>[@(timestamp|lsn)]")
     .options({
-    'preserve-under-name': {
-        describe: 'Name under which to preserve the old branch',
+    "preserve-under-name": {
+        describe: "Name under which to preserve the old branch",
     },
 })
     .example([
     [
-        '$0 branches restore main br-source-branch-123456',
-        'Restores main to the head of the branch with id br-source-branch-123456',
+        "$0 branches restore main br-source-branch-123456",
+        "Restores main to the head of the branch with id br-source-branch-123456",
     ],
     [
-        '$0 branches restore main source@2021-01-01T00:00:00Z',
-        'Restores main to the timestamp 2021-01-01T00:00:00Z of the source branch',
+        "$0 branches restore main source@2021-01-01T00:00:00Z",
+        "Restores main to the timestamp 2021-01-01T00:00:00Z of the source branch",
     ],
     [
-        '$0 branches restore my-branch ^self@0/123456',
-        'Restores my-branch to the LSN 0/123456 from its own history',
+        "$0 branches restore my-branch ^self@0/123456",
+        "Restores my-branch to the LSN 0/123456 from its own history",
     ],
     [
-        '$0 branches restore my-branch ^parent',
-        'Restore my-branch to the head of its parent branch',
+        "$0 branches restore my-branch ^parent",
+        "Restore my-branch to the head of its parent branch",
     ],
 ]), (args) => restore(args))
-    .command('rename <id|name> <new-name>', 'Rename a branch', (yargs) => yargs, (args) => rename(args))
-    .command('set-default <id|name>', 'Set a branch as default', (yargs) => yargs, (args) => setDefault(args))
+    .command("rename <id|name> <new-name>", "Rename a branch", (yargs) => yargs, (args) => rename(args))
+    .command("set-default <id|name>", "Set a branch as default", (yargs) => yargs, (args) => setDefault(args))
     .command({
-    command: 'set-expiration <id|name>',
-    describe: 'Set an expiration date for the branch',
+    command: "set-expiration <id|name>",
+    describe: "Set an expiration date for the branch",
     builder: (yargs) => yargs.options({
-        'expires-at': {
-            describe: 'Set a expiration date for the branch. If omitted, expiration will be removed. Format [RFC3339]: 2024-12-31T23:59:59Z',
-            type: 'string',
+        "expires-at": {
+            describe: "Set a expiration date for the branch. If omitted, expiration will be removed. Format [RFC3339]: 2024-12-31T23:59:59Z",
+            type: "string",
             requiresArg: false,
         },
     }),
     handler: (args) => setExpiration(args),
 })
-    .command('add-compute <id|name>', 'Add a compute to a branch', (yargs) => yargs.options({
+    .command("add-compute <id|name>", "Add a compute to a branch", (yargs) => yargs.options({
     type: {
-        type: 'string',
+        type: "string",
         choices: Object.values(EndpointType),
-        describe: 'Type of compute to add',
+        describe: "Type of compute to add",
         default: EndpointType.ReadOnly,
     },
     cu: {
         describe: 'The number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3").',
-        type: 'string',
+        type: "string",
     },
     name: {
-        type: 'string',
-        describe: 'Optional name of the compute',
+        type: "string",
+        describe: "Optional name of the compute",
     },
 }), (args) => addCompute(args))
-    .command('delete <id|name>', 'Delete a branch', (yargs) => yargs, (args) => deleteBranch(args))
-    .command('get <id|name>', 'Get a branch', (yargs) => yargs, (args) => get(args))
+    .command("delete <id|name>", "Delete a branch", (yargs) => yargs, (args) => deleteBranch(args))
+    .command("get <id|name>", "Get a branch", (yargs) => yargs, (args) => get(args))
     .command({
-    command: 'schema-diff [base-branch] [compare-source[@(timestamp|lsn)]]',
-    aliases: ['sd'],
+    command: "schema-diff [base-branch] [compare-source[@(timestamp|lsn)]]",
+    aliases: ["sd"],
     describe: "Compare the latest schemas of any two branches, or compare a branch to its own or another branch's history.",
     builder: (yargs) => {
         return yargs
-            .middleware((args) => (args.compareSource = args['compare-source@(timestamp']))
+            .middleware((args) => (args.compareSource =
+            args["compare-source@(timestamp"]))
             .middleware(parseSchemaDiffParams)
             .options({
             database: {
-                alias: 'db',
-                type: 'string',
-                description: 'Name of the database for which the schema comparison is performed',
+                alias: "db",
+                type: "string",
+                description: "Name of the database for which the schema comparison is performed",
             },
         })
             .example([
             [
-                '$0 branches schema-diff main br-compare-branch-123456',
-                'Compares the main branch to the head of the branch with ID br-compare-branch-123456',
+                "$0 branches schema-diff main br-compare-branch-123456",
+                "Compares the main branch to the head of the branch with ID br-compare-branch-123456",
             ],
             [
-                '$0 branches schema-diff main compare@2024-06-01T00:00:00Z',
-                'Compares the main branch to the state of the compare branch at timestamp 2024-06-01T00:00:00.000Z',
+                "$0 branches schema-diff main compare@2024-06-01T00:00:00Z",
+                "Compares the main branch to the state of the compare branch at timestamp 2024-06-01T00:00:00.000Z",
             ],
             [
-                '$0 branches schema-diff my-branch ^self@0/123456',
-                'Compares my-branch to LSN 0/123456 from its own history',
+                "$0 branches schema-diff my-branch ^self@0/123456",
+                "Compares my-branch to LSN 0/123456 from its own history",
             ],
             [
-                '$0 branches schema-diff my-branch ^parent',
-                'Compares my-branch to the head of its parent branch',
+                "$0 branches schema-diff my-branch ^parent",
+                "Compares my-branch to the head of its parent branch",
             ],
             [
-                '$0 branches schema-diff',
+                "$0 branches schema-diff",
                 "If a branch is specified in 'set-context', compares this branch to its parent. Otherwise, compares the default branch to its parent.",
             ],
         ]);
@@ -227,27 +228,27 @@ const list = async (props) => {
     writer(props).end(branches, {
         fields: BRANCH_FIELDS,
         renderColumns: {
-            expires_at: (br) => br.expires_at || 'never',
+            expires_at: (br) => br.expires_at || "never",
             // Word labels (not symbols) so they read clearly and match the existing `[anon]`.
             name: (br) => {
                 const annotation = annotations[br.id];
                 const isAnon = annotation?.value.anonymized;
                 const labels = [];
                 if (br.default) {
-                    labels.push('[default]');
+                    labels.push("[default]");
                 }
                 if (br.protected) {
-                    labels.push('[protected]');
+                    labels.push("[protected]");
                 }
                 if (isAnon) {
-                    labels.push('[anon]');
+                    labels.push("[anon]");
                 }
                 if (currentBranch !== undefined &&
                     (br.id === currentBranch || br.name === currentBranch)) {
-                    labels.push('[current]');
+                    labels.push("[current]");
                 }
                 labels.push(br.name);
-                return labels.join(' ');
+                return labels.join(" ");
             },
         },
     });
@@ -260,7 +261,7 @@ const create = async (props) => {
         if (!props.parent) {
             const branch = branches.find((b) => b.default);
             if (!branch) {
-                throw new Error('No default branch found');
+                throw new Error("No default branch found");
             }
             return { parent_id: branch.id };
         }
@@ -282,27 +283,33 @@ const create = async (props) => {
     // Validate schema-only branch requirements
     if (props.schemaOnly) {
         if (!props.compute) {
-            throw new Error('Schema-only branches require a compute endpoint');
+            throw new Error("Schema-only branches require a compute endpoint");
         }
         if (props.type !== EndpointType.ReadWrite) {
-            throw new Error('Schema-only branches require a read-write compute endpoint');
+            throw new Error("Schema-only branches require a read-write compute endpoint");
         }
     }
     const { data } = await retryOnLock(() => props.apiClient.createProjectBranch(props.projectId, {
         branch: {
             name: props.name,
             ...parentProps,
-            ...(props.schemaOnly ? { init_source: 'schema-only' } : {}),
-            ...(props['expires-at']
-                ? { expires_at: new Date(props['expires-at']).toISOString() }
+            ...(props.schemaOnly ? { init_source: "schema-only" } : {}),
+            ...(props["expires-at"]
+                ? {
+                    expires_at: new Date(props["expires-at"]).toISOString(),
+                }
                 : {}),
         },
         endpoints: props.compute
             ? [
                 {
                     type: props.type,
-                    suspend_timeout_seconds: props.suspendTimeout === 0 ? undefined : props.suspendTimeout,
-                    ...(props.cu ? getComputeUnits(props.cu) : undefined),
+                    suspend_timeout_seconds: props.suspendTimeout === 0
+                        ? undefined
+                        : props.suspendTimeout,
+                    ...(props.cu
+                        ? getComputeUnits(props.cu)
+                        : undefined),
                 },
             ]
             : [],
@@ -312,26 +319,26 @@ const create = async (props) => {
     }));
     const parent = branches.find((b) => b.id === data.branch.parent_id);
     if (parent?.protected) {
-        log.warning('The parent branch is protected; a unique role password has been generated for the new branch.');
+        log.warning("The parent branch is protected; a unique role password has been generated for the new branch.");
     }
     const out = writer(props);
     out.write(data.branch, {
         fields: BRANCH_FIELDS,
-        title: 'branch',
-        emptyMessage: 'No branches have been found.',
+        title: "branch",
+        emptyMessage: "No branches have been found.",
     });
     if (data.endpoints?.length > 0) {
         out.write(data.endpoints, {
-            fields: ['id', 'created_at'],
-            title: 'endpoints',
-            emptyMessage: 'No endpoints have been found.',
+            fields: ["id", "created_at"],
+            title: "endpoints",
+            emptyMessage: "No endpoints have been found.",
         });
     }
     if (data.connection_uris?.length) {
         out.write(data.connection_uris, {
-            fields: ['connection_uri'],
-            title: 'connection_uris',
-            emptyMessage: 'No connection uris have been found',
+            fields: ["connection_uri"],
+            title: "connection_uris",
+            emptyMessage: "No connection uris have been found",
         });
     }
     out.end();
@@ -340,9 +347,9 @@ const create = async (props) => {
             throw new Error(`Branch ${data.branch.id} doesn't have a connection uri`);
         }
         const connection_uri = data.connection_uris[0].connection_uri;
-        const psqlArgs = props['--'];
+        const psqlArgs = props["--"];
         await psql(connection_uri, psqlArgs, {
-            mode: props.fallback ? 'ts' : 'auto',
+            mode: props.fallback ? "ts" : "auto",
         });
     }
 };
@@ -367,9 +374,12 @@ const setDefault = async (props) => {
 const deleteBranch = async (props) => {
     const branchId = await branchIdFromProps(props);
     const { data } = await retryOnLock(() => props.apiClient.deleteProjectBranch(props.projectId, branchId));
-    writer(props).end(data.branch, {
-        fields: BRANCH_FIELDS,
-    });
+    // A 204 (branch already gone) carries no body; only a 200 returns it.
+    if (data) {
+        writer(props).end(data.branch, {
+            fields: BRANCH_FIELDS,
+        });
+    }
 };
 const get = async (props) => {
     const branchId = await branchIdFromProps(props);
@@ -390,17 +400,17 @@ const addCompute = async (props) => {
         },
     }));
     writer(props).end(data.endpoint, {
-        fields: ['id', 'host'],
+        fields: ["id", "host"],
     });
 };
 const reset = async (props) => {
     if (!props.parent) {
-        throw new Error('Only resetting to parent is supported for now');
+        throw new Error("Only resetting to parent is supported for now");
     }
     const branchId = await branchIdFromProps(props);
     const { data: { branch: { parent_id }, }, } = await props.apiClient.getProjectBranch(props.projectId, branchId);
     if (!parent_id) {
-        throw new Error('Branch has no parent');
+        throw new Error("Branch has no parent");
     }
     const { data } = await retryOnLock(() => props.apiClient.restoreProjectBranch(props.projectId, branchId, {
         source_branch_id: parent_id,
@@ -423,30 +433,30 @@ const restore = async (props) => {
         projectId: props.projectId,
         api: props.apiClient,
     });
-    log.info(`Restoring branch ${targetBranchId} to the branch ${pointInTime.branchId} ${(pointInTime.tag === 'lsn' && 'LSN ' + pointInTime.lsn) ||
-        (pointInTime.tag === 'timestamp' &&
-            'timestamp ' + pointInTime.timestamp) ||
-        'head'}`);
+    log.info(`Restoring branch ${targetBranchId} to the branch ${pointInTime.branchId} ${(pointInTime.tag === "lsn" && "LSN " + pointInTime.lsn) ||
+        (pointInTime.tag === "timestamp" &&
+            "timestamp " + pointInTime.timestamp) ||
+        "head"}`);
     const { data } = await retryOnLock(() => props.apiClient.restoreProjectBranch(props.projectId, targetBranchId, {
         source_branch_id: pointInTime.branchId,
         preserve_under_name: props.preserveUnderName || undefined,
-        ...(pointInTime.tag === 'lsn' && { source_lsn: pointInTime.lsn }),
-        ...(pointInTime.tag === 'timestamp' && {
+        ...(pointInTime.tag === "lsn" && { source_lsn: pointInTime.lsn }),
+        ...(pointInTime.tag === "timestamp" && {
             source_timestamp: pointInTime.timestamp,
         }),
     }));
     const writeInst = writer(props).write(data.branch, {
-        title: 'Restored branch',
-        fields: ['id', 'name', 'last_reset_at'],
-        emptyMessage: 'No branches have been restored.',
+        title: "Restored branch",
+        fields: ["id", "name", "last_reset_at"],
+        emptyMessage: "No branches have been restored.",
     });
     const parentId = data.branch.parent_id;
     if (props.preserveUnderName && parentId) {
         const { data } = await props.apiClient.getProjectBranch(props.projectId, parentId);
         writeInst.write(data.branch, {
-            title: 'Backup branch',
-            fields: ['id', 'name'],
-            emptyMessage: 'Backup branch has not been found.',
+            title: "Backup branch",
+            fields: ["id", "name"],
+            emptyMessage: "Backup branch has not been found.",
         });
     }
     writeInst.end();
@@ -457,7 +467,7 @@ const setExpiration = async (props) => {
         ...props,
         id: props.branchId,
     });
-    const expiresAt = typeof props.expiresAt === 'string'
+    const expiresAt = typeof props.expiresAt === "string"
         ? new Date(props.expiresAt).toISOString()
         : null;
     const { data } = await retryOnLock(() => props.apiClient.updateProjectBranch(props.projectId, branchId, {