neonctl 1.26.2 → 1.27.0-beta.1

package/commands/branches.js

@@ -2,9 +2,11 @@ import { EndpointType } from '@neondatabase/api-client';
 import { writer } from '../writer.js';
 import { branchCreateRequest } from '../parameters.gen.js';
 import { retryOnLock } from '../api.js';
-import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.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';
 const BRANCH_FIELDS = [
     'id',
     'name',
@@ -72,6 +74,38 @@ export const builder = (argv) => argv
         describe: 'Name under which to preserve the old branch',
     },
 }), async (args) => await 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
+    // 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'];
+})
+    .usage('$0 branches restore <target-id|name> <source>[@(timestamp|lsn)]')
+    .options({
+    'preserve-under-name': {
+        describe: 'Name under which to preserve the old branch',
+    },
+})
+    .example([
+    [
+        '$0 branches restore main br-source-branch-123456',
+        'Restore main to the head of the branch with id br-source-branch-123456',
+    ],
+    [
+        '$0 branches restore main source@2021-01-01T00:00:00Z',
+        'Restore main to the timestamp 2021-01-01T00:00:00Z of the source branch',
+    ],
+    [
+        '$0 branches restore my-branch ^self@0/123456',
+        'Restore my-branch to the LSN 0/123456 of the branch itself',
+    ],
+    [
+        '$0 branches restore my-branch ^parent',
+        'Restore my-branch to the head of the parent branch',
+    ],
+]), async (args) => await restore(args))
     .command('rename <id|name> <new-name>', 'Rename a branch', (yargs) => yargs, async (args) => await rename(args))
     .command('set-primary <id|name>', 'Set a branch as primary', (yargs) => yargs, async (args) => await setPrimary(args))
     .command('add-compute <id|name>', 'Add a compute to a branch', (yargs) => yargs.options({
@@ -233,3 +267,45 @@ const reset = async (props) => {
         fields: BRANCH_FIELDS_RESET,
     });
 };
+const restore = async (props) => {
+    const targetBranchId = await branchIdResolve({
+        branch: props.id,
+        projectId: props.projectId,
+        apiClient: props.apiClient,
+    });
+    const pointInTime = await parsePointInTime({
+        pointInTime: props.pointInTime,
+        targetBranchId,
+        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'}`);
+    const { data } = await retryOnLock(() => props.apiClient.request({
+        method: 'POST',
+        path: `/projects/${props.projectId}/branches/${targetBranchId}/reset`,
+        body: {
+            source_branch_id: pointInTime.branchId,
+            preserve_under_name: props.preserveUnderName || undefined,
+            ...(pointInTime.tag === 'lsn' && { source_lsn: pointInTime.lsn }),
+            ...(pointInTime.tag === 'timestamp' && {
+                source_timestamp: pointInTime.timestamp,
+            }),
+        },
+    }));
+    const branch = data.branch;
+    const writeInst = writer(props).write(branch, {
+        title: 'Restored branch',
+        fields: ['id', 'name', 'last_reset_at'],
+    });
+    if (props.preserveUnderName && branch.parent_id) {
+        const { data } = await props.apiClient.getProjectBranch(props.projectId, branch.parent_id);
+        writeInst.write(data.branch, {
+            title: 'Backup branch',
+            fields: ['id', 'name'],
+        });
+    }
+    writeInst.end();
+};

package/commands/branches.test.js

@@ -1,6 +1,7 @@
 import { describe } from '@jest/globals';
 import { testCliCommand } from '../test_utils/test_cli_command.js';
 describe('branches', () => {
+    /* list */
     testCliCommand({
         name: 'list',
         args: ['branches', 'list', '--project-id', 'test'],
@@ -8,6 +9,7 @@ describe('branches', () => {
             snapshot: true,
         },
     });
+    /* create */
     testCliCommand({
         name: 'create by default with r/w endpoint',
         args: [
@@ -150,6 +152,7 @@ describe('branches', () => {
             snapshot: true,
         },
     });
+    /* delete */
     testCliCommand({
         name: 'delete by id',
         args: [
@@ -163,19 +166,7 @@ describe('branches', () => {
             snapshot: true,
         },
     });
-    testCliCommand({
-        name: 'delete by id',
-        args: [
-            'branches',
-            'delete',
-            'br-cloudy-branch-12345678',
-            '--project-id',
-            'test',
-        ],
-        expected: {
-            snapshot: true,
-        },
-    });
+    /* rename */
     testCliCommand({
         name: 'rename',
         args: [
@@ -190,6 +181,7 @@ describe('branches', () => {
             snapshot: true,
         },
     });
+    /* set primary */
     testCliCommand({
         name: 'set primary by id',
         args: [
@@ -203,19 +195,7 @@ describe('branches', () => {
             snapshot: true,
         },
     });
-    testCliCommand({
-        name: 'set primary by id',
-        args: [
-            'branches',
-            'set-primary',
-            'br-cloudy-branch-12345678',
-            '--project-id',
-            'test',
-        ],
-        expected: {
-            snapshot: true,
-        },
-    });
+    /* get */
     testCliCommand({
         name: 'get by id',
         args: ['branches', 'get', 'br-sunny-branch-123456', '--project-id', 'test'],
@@ -250,6 +230,7 @@ describe('branches', () => {
             snapshot: true,
         },
     });
+    /* add compute */
     testCliCommand({
         name: 'add compute',
         args: ['branches', 'add-compute', 'test_branch', '--project-id', 'test'],
@@ -257,6 +238,7 @@ describe('branches', () => {
             snapshot: true,
         },
     });
+    /* reset */
     testCliCommand({
         name: 'reset branch to parent',
         args: [
@@ -271,4 +253,69 @@ describe('branches', () => {
             snapshot: true,
         },
     });
+    /* restore */
+    testCliCommand({
+        name: 'restore branch to lsn',
+        args: [
+            'branches',
+            'restore',
+            'br-self-tolsn-123456',
+            '^self@0/123ABC',
+            '--project-id',
+            'test',
+            '--preserve-under-name',
+            'backup',
+        ],
+        mockDir: 'restore',
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'restore to parent branch timestamp by name',
+        args: [
+            'branches',
+            'restore',
+            'parent-tots',
+            '^parent@2021-01-01T00:00:00.000Z',
+            '--project-id',
+            'test',
+        ],
+        mockDir: 'restore',
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'restore to another branch head',
+        args: [
+            'branches',
+            'restore',
+            'br-another-branch-123456',
+            'br-any-branch-123456',
+            '--project-id',
+            'test',
+        ],
+        mockDir: 'restore',
+        expected: {
+            snapshot: true,
+        },
+    });
+    testCliCommand({
+        name: 'restore with unexisted branch outputs error',
+        args: [
+            'branches',
+            'restore',
+            'unexisting-branch',
+            '^parent',
+            '--project-id',
+            'test',
+        ],
+        mockDir: 'restore',
+        expected: {
+            code: 1,
+            stderr: `ERROR: Branch unexisting-branch not found.
+               Available branches: self-tolsn-123456, any-branch, parent-tots, another-branch`,
+        },
+    });
 });

package/commands/connection_string.js

@@ -49,6 +49,11 @@ export const builder = (argv) => {
             describe: 'Connect to a database via psql using connection string',
             default: false,
         },
+        ssl: {
+            type: 'boolean',
+            describe: 'Add sslmode=require to the connection string',
+            default: true,
+        },
     })
         .middleware(fillSingleProject);
 };
@@ -107,6 +112,9 @@ export const handler = async (props) => {
             connectionString.searchParams.set('pgbouncer', 'true');
         }
     }
+    if (props.ssl) {
+        connectionString.searchParams.set('sslmode', 'require');
+    }
     if (props.psql) {
         const psqlArgs = props['--'];
         await psql(connectionString.toString(), psqlArgs);

package/commands/connection_string.test.js

@@ -165,4 +165,22 @@ describe('connection_string', () => {
             snapshot: true,
         },
     });
+    testCliCommand({
+        name: 'connection_string without ssl',
+        args: [
+            'connection-string',
+            'test_branch',
+            '--project-id',
+            'test',
+            '--database-name',
+            'test_db',
+            '--role-name',
+            'test_role',
+            '--ssl',
+            'false',
+        ],
+        expected: {
+            snapshot: true,
+        },
+    });
 });

package/commands/ip_allow.test.js

@@ -21,8 +21,7 @@ describe('ip-allow', () => {
         args: ['ip-allow', 'add', '--projectId', 'test'],
         expected: {
             stderr: `ERROR: Enter individual IP addresses, define ranges with a dash, or use CIDR notation for more flexibility.
-       Example: neonctl ip-allow add 192.168.1.1, 192.168.1.20-192.168.1.50, 192.168.1.0/24 --project-id <id>
-`,
+       Example: neonctl ip-allow add 192.168.1.1, 192.168.1.20-192.168.1.50, 192.168.1.0/24 --project-id <id>`,
         },
     });
     testCliCommand({
@@ -44,8 +43,7 @@ describe('ip-allow', () => {
         name: 'Remove IP allow - Error',
         args: ['ip-allow', 'remove', '--project-id', 'test'],
         expected: {
-            stderr: `ERROR: Remove individual IP addresses and ranges. Example: neonctl ip-allow remove 192.168.1.1 --project-id <id>
-`,
+            stderr: `ERROR: Remove individual IP addresses and ranges. Example: neonctl ip-allow remove 192.168.1.1 --project-id <id>`,
         },
     });
     testCliCommand({
@@ -65,8 +63,7 @@ name: test_project
 IP_addresses: []
 primary_branch_only: false
 `,
-            stderr: `INFO: The IP allowlist has been reset. All databases on project "test_project" are now exposed to the internet
-`,
+            stderr: `INFO: The IP allowlist has been reset. All databases on project "test_project" are now exposed to the internet`,
         },
     });
     testCliCommand({

package/help.js

@@ -22,6 +22,14 @@ const formatHelp = (help) => {
             width: 0,
         });
         commandsBlock.forEach((line) => {
+            if (line.match(/^\s{3,}/)) {
+                ui.div({
+                    text: '',
+                    width: SPACE_WIDTH,
+                    padding: [0, 0, 0, 0],
+                }, { text: line.trim(), padding: [0, 0, 0, 0] });
+                return;
+            }
             const [command, description] = splitColumns(line);
             // patch the previous command if it was multiline
             if (!description && ui.rows.length > 1) {
@@ -65,7 +73,7 @@ const formatHelp = (help) => {
     // example command to see: neonctl projects list
     const descritpionBlock = consumeBlockIfMatches(lines, /^(?!.*options:)/i);
     if (descritpionBlock.length > 0) {
-        result.push(descritpionBlock.shift());
+        result.push(...descritpionBlock);
         result.push('');
     }
     while (true) {
@@ -109,11 +117,30 @@ const formatHelp = (help) => {
         });
         result.push('');
     }
+    const exampleBlock = consumeBlockIfMatches(lines, /Examples:/);
+    if (exampleBlock.length > 0) {
+        result.push(exampleBlock.shift());
+        const ui = cliui({
+            width: 0,
+        });
+        for (const line of exampleBlock) {
+            const [command, description] = splitColumns(line);
+            ui.div({
+                text: chalk.bold(command),
+                padding: [0, 0, 0, 0],
+            });
+            ui.div({
+                text: chalk.reset(description),
+                padding: [0, 0, 0, 2],
+            });
+        }
+        result.push(ui.toString());
+    }
     return [...result, ...lines];
 };
 export const showHelp = async (argv) => {
     // add wrap to ensure that there are no line breaks
-    const help = await argv.wrap(500).getHelp();
+    const help = await argv.getHelp();
     process.stderr.write(formatHelp(help).join('\n') + '\n');
     process.exit(0);
 };

package/index.js

@@ -129,6 +129,7 @@ builder = builder
     .completion()
     .scriptName(basename(process.argv[1]) === 'neon' ? 'neon' : 'neonctl')
     .epilog('For more information, visit https://neon.tech/docs/reference/neon-cli')
+    .wrap(null)
     .fail(async (msg, err) => {
     if (process.argv.some((arg) => arg === '--help' || arg === '-h')) {
         await showHelp(builder);
@@ -144,8 +145,10 @@ builder = builder
             log.error('Authentication failed, please run `neonctl auth`');
         }
         else {
-            log.debug('Fail: %d | %s', err.response?.status, err.response?.statusText);
-            log.error(err.response?.data?.message);
+            if (err.response?.data?.message) {
+                log.error(err.response?.data?.message);
+            }
+            log.debug('status: %d %s | path: %s', err.response?.status, err.response?.statusText, err.request?.path);
             sendError(err, 'API_ERROR');
         }
     }

package/package.json

@@ -5,7 +5,7 @@
     "url": "git@github.com:neondatabase/neonctl.git"
   },
   "type": "module",
-  "version": "1.26.2",
+  "version": "1.27.0-beta.1",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",

package/test_utils/mock_server.js

@@ -5,7 +5,9 @@ import { log } from '../log';
 export const runMockServer = async (mockDir) => new Promise((resolve) => {
     const app = express();
     app.use(express.json());
-    app.use('/', emocks(join(process.cwd(), 'mocks', mockDir)));
+    app.use('/', emocks(join(process.cwd(), 'mocks', mockDir), {
+        '404': (req, res) => res.status(404).send({ message: 'Not Found' }),
+    }));
     const server = app.listen(0);
     server.on('listening', () => {
         resolve(server);

package/test_utils/test_cli_command.js

@@ -33,6 +33,7 @@ export const testCliCommand = ({ args, name, expected, before, after, mockDir =
                 'yaml',
                 '--api-key',
                 'test-key',
+                '--no-analytics',
                 ...args,
             ], {
                 stdio: 'pipe',
@@ -53,8 +54,8 @@ export const testCliCommand = ({ args, name, expected, before, after, mockDir =
                 });
                 cp.on('close', (code) => {
                     try {
-                        expect(code).toBe(0);
-                        if (code === 0 && expected) {
+                        expect(code).toBe(expected?.code ?? 0);
+                        if (expected) {
                             if (expected.snapshot) {
                                 expect(output).toMatchSnapshot();
                             }
@@ -62,7 +63,9 @@ export const testCliCommand = ({ args, name, expected, before, after, mockDir =
                                 expect(strip(output)).toEqual(expected.stdout);
                             }
                             if (expected.stderr !== undefined) {
-                                expect(strip(error)).toEqual(expected.stderr);
+                                expect(strip(error).replace(/\s+/g, ' ').trim()).toEqual(typeof expected.stderr === 'string'
+                                    ? expected.stderr.toString().replace(/\s+/g, ' ')
+                                    : expected.stderr);
                             }
                         }
                         resolve();

package/utils/point_in_time.js

@@ -0,0 +1,44 @@
+import { looksLikeLSN, looksLikeTimestamp } from './formats.js';
+import { branchIdResolve } from './enrichers.js';
+export class PointInTimeParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PointInTimeParseError';
+    }
+}
+export const parsePointInTime = async ({ pointInTime, targetBranchId, projectId, api, }) => {
+    const splitIndex = pointInTime.lastIndexOf('@');
+    const sourceBranch = splitIndex === -1 ? pointInTime : pointInTime.slice(0, splitIndex);
+    const exactPIT = splitIndex === -1 ? null : pointInTime.slice(splitIndex + 1);
+    const result = {
+        branchId: '',
+        ...(exactPIT === null
+            ? { tag: 'head' }
+            : looksLikeLSN(exactPIT)
+                ? { tag: 'lsn', lsn: exactPIT }
+                : { tag: 'timestamp', timestamp: exactPIT }),
+    };
+    if (result.tag === 'timestamp' && !looksLikeTimestamp(result.timestamp)) {
+        throw new PointInTimeParseError('Invalid source branch format');
+    }
+    if (sourceBranch === '^self') {
+        return {
+            ...result,
+            branchId: targetBranchId,
+        };
+    }
+    if (sourceBranch === '^parent') {
+        const { data } = await api.getProjectBranch(projectId, targetBranchId);
+        const { parent_id: parentId } = data.branch;
+        if (parentId == null) {
+            throw new PointInTimeParseError('Branch has no parent');
+        }
+        return { ...result, branchId: parentId };
+    }
+    const branchId = await branchIdResolve({
+        branch: sourceBranch,
+        projectId,
+        apiClient: api,
+    });
+    return { ...result, branchId };
+};

package/utils/ui.js

@@ -43,6 +43,9 @@ export const consumeBlockIfMatches = (lines, matcher) => {
 export const splitColumns = (line) => {
     const result = line.trim().split(/\s{2,}/);
     result[1] = result[1] ?? '';
+    if (result.length > 2) {
+        result[1] = result.slice(1).join(' ');
+    }
     return result;
 };
 export const drawPointer = (width) => {