neonctl 2.4.0 → 2.5.0

package/commands/bootstrap/index.js

@@ -135,7 +135,9 @@ function applyMigrations({ options, appName, connectionString, }) {
     }
 }
 async function deployApp({ props, options, devBranchName, project, appName, environmentVariables, }) {
-    let { data: { branches }, } = await props.apiClient.listProjectBranches(project.id);
+    let { data: { branches }, } = await props.apiClient.listProjectBranches({
+        projectId: project.id,
+    });
     branches = branches.filter((branch) => branch.name !== devBranchName);
     let branchId;
     if (branches.length === 0) {

package/commands/branches.js

@@ -179,14 +179,16 @@ export const handler = (args) => {
     return args;
 };
 const list = async (props) => {
-    const { data } = await props.apiClient.listProjectBranches(props.projectId);
+    const { data } = await props.apiClient.listProjectBranches({
+        projectId: props.projectId,
+    });
     writer(props).end(data.branches, {
         fields: BRANCH_FIELDS,
     });
 };
 const create = async (props) => {
     const branches = await props.apiClient
-        .listProjectBranches(props.projectId)
+        .listProjectBranches({ projectId: props.projectId })
         .then(({ data }) => data.branches);
     const parentProps = (() => {
         if (!props.parent) {

package/commands/index.js

@@ -1,6 +1,7 @@
 import * as auth from './auth.js';
 import * as projects from './projects.js';
 import * as ipAllow from './ip_allow.js';
+import * as vpcEndpoints from './vpc_endpoints.js';
 import * as users from './user.js';
 import * as orgs from './orgs.js';
 import * as branches from './branches.js';
@@ -16,6 +17,7 @@ export default [
     orgs,
     projects,
     ipAllow,
+    vpcEndpoints,
     branches,
     databases,
     roles,

package/commands/projects.js

@@ -10,7 +10,7 @@ export const PROJECT_FIELDS = [
     'region_id',
     'created_at',
 ];
-const REGIONS = [
+export const REGIONS = [
     'aws-us-west-2',
     'aws-ap-southeast-1',
     'aws-ap-southeast-2',

package/commands/schema_diff.js

@@ -64,7 +64,6 @@ const fetchSchema = async (pointInTime, database, props) => {
             projectId: props.projectId,
             branchId: pointInTime.branchId,
             db_name: database.name,
-            role: database.owner_name,
             ...pointInTimeParams(pointInTime),
         })
             .then((response) => response.data.sql ?? '');
@@ -128,7 +127,9 @@ export const parseSchemaDiffParams = async (props) => {
             props.baseBranch = props.branch;
         }
         else if (props.branch) {
-            const { data } = await props.apiClient.listProjectBranches(props.projectId);
+            const { data } = await props.apiClient.listProjectBranches({
+                projectId: props.projectId,
+            });
             const contextBranch = data.branches.find((b) => b.id === props.branch || b.name === props.branch);
             if (contextBranch?.parent_id == undefined) {
                 throw new Error(`No branch specified. Your context branch (${props.branch}) has no parent, so no comparison is possible.`);
@@ -137,7 +138,9 @@ export const parseSchemaDiffParams = async (props) => {
             props.compareSource = '^parent';
         }
         else {
-            const { data } = await props.apiClient.listProjectBranches(props.projectId);
+            const { data } = await props.apiClient.listProjectBranches({
+                projectId: props.projectId,
+            });
             const defaultBranch = data.branches.find((b) => b.default);
             if (defaultBranch?.parent_id == undefined) {
                 throw new Error('No branch specified. Include a base branch or add a set-context branch to continue. Your default branch has no parent, so no comparison is possible.');

package/commands/vpc_endpoints.js

@@ -0,0 +1,134 @@
+import { writer } from '../writer.js';
+import { fillSingleProject, fillSingleOrg } from '../utils/enrichers.js';
+import { REGIONS } from './projects.js';
+import { log } from '../log.js';
+const VPC_ENDPOINT_FIELDS = ['vpc_endpoint_id', 'label'];
+const VPC_ENDPOINT_DETAILS_FIELDS = [
+    'vpc_endpoint_id',
+    'label',
+    'state',
+    'num_restricted_projects',
+    'example_restricted_projects',
+];
+export const command = 'vpc';
+export const describe = 'Manage VPC endpoints and project VPC restrictions';
+export const builder = (argv) => {
+    return argv
+        .usage('$0 vpc <sub-command> [options]')
+        .command('endpoint', 'Manage VPC endpoints.\n' +
+        'See: https://neon.tech/docs/guides/neon-private-networking\n' +
+        'After adding an endpoint to an organization, client connections will be accepted\n' +
+        'from the corresponding VPC for all projects in the organization, unless overridden\n' +
+        'by a project-level VPC endpoint restriction.', (yargs) => {
+        return yargs
+            .options({
+            'org-id': {
+                describe: 'Organization ID',
+                type: 'string',
+            },
+            'region-id': {
+                describe: `The region ID. Possible values: ${REGIONS.join(', ')}`,
+                type: 'string',
+                demandOption: true,
+            },
+        })
+            .middleware(fillSingleOrg)
+            .command('list', 'List configured VPC endpoints for this organization.', (yargs) => yargs, async (args) => {
+            await listOrg(args);
+        })
+            .command({
+            command: 'assign <id>',
+            aliases: ['update <id>', 'add <id>'],
+            describe: 'Add or update a VPC endpoint for this organization.\n' +
+                'Note: Azure regions are not yet supported.',
+            builder: (yargs) => yargs.options({
+                label: {
+                    describe: 'An optional descriptive label for the VPC endpoint',
+                    type: 'string',
+                },
+            }),
+            handler: async (args) => {
+                await assignOrg(args);
+            },
+        })
+            .command('remove <id>', 'Remove a VPC endpoint from this organization.', (yargs) => yargs, async (args) => {
+            await removeOrg(args);
+        })
+            .command('status <id>', 'Get the status of a VPC endpoint for this organization.', (yargs) => yargs, async (args) => {
+            await statusOrg(args);
+        });
+    })
+        .command('project', 'Manage project-level VPC endpoint restrictions.\n' +
+        'By default, connections are accepted from any VPC configured at the organization level.\n' +
+        'A project-level VPC endpoint restriction can be used to restrict connections to a specific VPC.', (yargs) => {
+        return yargs
+            .options({
+            'project-id': {
+                describe: 'Project ID',
+                type: 'string',
+            },
+        })
+            .middleware(fillSingleProject)
+            .command('list', 'List VPC endpoint restrictions for this project.', (yargs) => yargs, async (args) => {
+            await listProject(args);
+        })
+            .command({
+            command: 'restrict <id>',
+            aliases: ['update <id>'],
+            describe: 'Configure or update a VPC endpoint restriction for this project.',
+            builder: (yargs) => yargs.options({
+                label: {
+                    describe: 'An optional descriptive label for the VPC endpoint restriction',
+                    type: 'string',
+                },
+            }),
+            handler: async (args) => {
+                await assignProject(args);
+            },
+        })
+            .command('remove <id>', 'Remove a VPC endpoint restriction from this project.', (yargs) => yargs, async (args) => {
+            await removeProject(args);
+        });
+    });
+};
+const listOrg = async (props) => {
+    const { data } = await props.apiClient.listOrganizationVpcEndpoints(props.orgId, props.regionId);
+    writer(props).end(data.endpoints, {
+        fields: VPC_ENDPOINT_FIELDS,
+    });
+};
+const assignOrg = async (props) => {
+    const vpcEndpointAssignment = {
+        label: props.label || '',
+    };
+    const { data } = await props.apiClient.assignOrganizationVpcEndpoint(props.orgId, props.regionId, props.id, vpcEndpointAssignment);
+    writer(props).end(data, { fields: [] });
+    if (props.regionId.startsWith('azure')) {
+        log.info('VPC endpoint configuration is not supported for Azure regions');
+    }
+};
+const removeOrg = async (props) => {
+    const { data } = await props.apiClient.deleteOrganizationVpcEndpoint(props.orgId, props.regionId, props.id);
+    writer(props).end(data, { fields: [] });
+};
+const statusOrg = async (props) => {
+    const { data } = await props.apiClient.getOrganizationVpcEndpointDetails(props.orgId, props.regionId, props.id);
+    writer(props).end(data, { fields: VPC_ENDPOINT_DETAILS_FIELDS });
+};
+const listProject = async (props) => {
+    const { data } = await props.apiClient.listProjectVpcEndpoints(props.projectId);
+    writer(props).end(data.endpoints, {
+        fields: VPC_ENDPOINT_FIELDS,
+    });
+};
+const assignProject = async (props) => {
+    const vpcEndpointAssignment = {
+        label: props.label || '',
+    };
+    const { data } = await props.apiClient.assignProjectVpcEndpoint(props.projectId, props.id, vpcEndpointAssignment);
+    writer(props).end(data, { fields: [] });
+};
+const removeProject = async (props) => {
+    const { data } = await props.apiClient.deleteProjectVpcEndpoint(props.projectId, props.id);
+    writer(props).end(data, { fields: [] });
+};

package/commands/vpc_endpoints.test.js

@@ -0,0 +1,69 @@
+import { describe } from 'vitest';
+import { test } from '../test_utils/fixtures';
+describe('vpc-endpoints', () => {
+    test('list org VPC endpoints', async ({ testCliCommand }) => {
+        await testCliCommand(['vpc', 'endpoint', 'list', '--org-id', '1', '--region-id', 'test'], { mockDir: 'single_org' });
+    });
+    test('list org VPC endpoints implicit org', async ({ testCliCommand }) => {
+        await testCliCommand(['vpc', 'endpoint', 'list', '--region-id', 'test'], {
+            mockDir: 'single_org',
+        });
+    });
+    test('update org VPC endpoint', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'vpc',
+            'endpoint',
+            'update',
+            'vpc-test',
+            '--label',
+            'newlabel',
+            '--region-id',
+            'test',
+        ], { mockDir: 'single_org' });
+    });
+    test('delete org VPC endpoint', async ({ testCliCommand }) => {
+        await testCliCommand(['vpc', 'endpoint', 'remove', 'vpc-test', '--region-id', 'test'], { mockDir: 'single_org' });
+    });
+    test('get org VPC endpoint status', async ({ testCliCommand }) => {
+        await testCliCommand(['vpc', 'endpoint', 'status', 'vpc-test', '--region-id', 'test'], { mockDir: 'single_org' });
+    });
+    test('set org VPC endpoint in azure', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'vpc',
+            'endpoint',
+            'update',
+            'vpc-test',
+            '--label',
+            'newlabel',
+            '--region-id',
+            'azure-test',
+        ], {
+            mockDir: 'single_org',
+            stderr: 'INFO: VPC endpoint configuration is not supported for Azure regions',
+        });
+    });
+    test('list project VPC endpoint restrictions', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'vpc',
+            'project',
+            'list',
+            '--region-id',
+            'test',
+            '--project-id',
+            'test-project-123456',
+        ], { mockDir: 'single_org' });
+    });
+    test('list project VPC endpoint restrictions with implicit project', async ({ testCliCommand, }) => {
+        await testCliCommand(['vpc', 'project', 'list', '--region-id', 'test'], {
+            mockDir: 'single_org',
+        });
+    });
+    test('set project VPC endpoint restrictions', async ({ testCliCommand }) => {
+        await testCliCommand(['vpc', 'project', 'update', 'vpc-test', '--label', 'newlabel'], { mockDir: 'single_org' });
+    });
+    test('delete project VPC endpoint restrictions', async ({ testCliCommand, }) => {
+        await testCliCommand(['vpc', 'project', 'remove', 'vpc-test'], {
+            mockDir: 'single_org',
+        });
+    });
+});

package/package.json

@@ -5,7 +5,7 @@
     "url": "git+ssh://git@github.com/neondatabase/neonctl.git"
   },
   "type": "module",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",
@@ -54,7 +54,7 @@
     "vitest": "^1.6.0"
   },
   "dependencies": {
-    "@neondatabase/api-client": "^1.10.0",
+    "@neondatabase/api-client": "1.11.2",
     "@segment/analytics-node": "^1.0.0-beta.26",
     "axios": "^1.4.0",
     "axios-debug-log": "^1.0.0",

package/parameters.gen.js

@@ -35,14 +35,34 @@ export const projectCreateRequest = {
         description: "If true, the list will be applied only to protected branches.",
         demandOption: false,
     },
-    'project.settings.allowed_ips.primary_branch_only': {
+    'project.settings.enable_logical_replication': {
         type: "boolean",
-        description: "DEPRECATED: Use `protected_branches_only`.\nIf true, the list will be applied only to the default branch.\n",
+        description: "Sets wal_level=logical for all compute endpoints in this project.\nAll active endpoints will be suspended.\nOnce enabled, logical replication cannot be disabled.\n",
         demandOption: false,
     },
-    'project.settings.enable_logical_replication': {
+    'project.settings.maintenance_window.weekdays': {
+        type: "array",
+        description: "A list of weekdays when the maintenance window is active.\nEncoded as ints, where 1 - Monday, and 7 - Sunday.\n",
+        demandOption: true,
+    },
+    'project.settings.maintenance_window.start_time': {
+        type: "string",
+        description: "Start time of the maintenance window, in the format of \"HH:MM\". Uses UTC.\n",
+        demandOption: true,
+    },
+    'project.settings.maintenance_window.end_time': {
+        type: "string",
+        description: "End time of the maintenance window, in the format of \"HH:MM\". Uses UTC.\n",
+        demandOption: true,
+    },
+    'project.settings.block_public_connections': {
         type: "boolean",
-        description: "Sets wal_level=logical for all compute endpoints in this project.\nAll active endpoints will be suspended.\nOnce enabled, logical replication cannot be disabled.\n",
+        description: "When set, connections from the public internet\nare disallowed. This supersedes the AllowedIPs list.\nThis parameter is under active development and its semantics may change in the future.\n",
+        demandOption: false,
+    },
+    'project.settings.block_vpc_connections': {
+        type: "boolean",
+        description: "When set, connections using VPC endpoints are disallowed.\nThis parameter is under active development and its semantics may change in the future.\n",
         demandOption: false,
     },
     'project.name': {
@@ -52,24 +72,23 @@ export const projectCreateRequest = {
     },
     'project.branch.name': {
         type: "string",
-        description: "The branch name. If not specified, the default branch name will be used.\n",
+        description: "The default branch name. If not specified, the default branch name, `main`, will be used.\n",
         demandOption: false,
     },
     'project.branch.role_name': {
         type: "string",
-        description: "The role name. If not specified, the default role name will be used.\n",
+        description: "The role name. If not specified, the default role name, `{database_name}_owner`, will be used.\n",
         demandOption: false,
     },
     'project.branch.database_name': {
         type: "string",
-        description: "The database name. If not specified, the default database name will be used.\n",
+        description: "The database name. If not specified, the default database name, `neondb`, will be used.\n",
         demandOption: false,
     },
     'project.provisioner': {
         type: "string",
-        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n",
+        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n",
         demandOption: false,
-        choices: ["k8s-pod", "k8s-neonvm"],
     },
     'project.region_id': {
         type: "string",
@@ -83,7 +102,7 @@ export const projectCreateRequest = {
     },
     'project.pg_version': {
         type: "number",
-        description: "The major Postgres version number. Currently supported versions are `14`, `15`, and `16`.",
+        description: "The major Postgres version number. Currently supported versions are `14`, `15`, `16`, and `17`.",
         demandOption: false,
     },
     'project.store_passwords': {
@@ -93,7 +112,7 @@ export const projectCreateRequest = {
     },
     'project.history_retention_seconds': {
         type: "number",
-        description: "The number of seconds to retain the point-in-time restore (PITR) backup history for this project.\nThe default is 604800 seconds (7 days).\n",
+        description: "The number of seconds to retain the shared history for all branches in this project.\nThe default is 1 day (86400 seconds).\n",
         demandOption: false,
     },
     'project.org_id': {
@@ -138,14 +157,34 @@ export const projectUpdateRequest = {
         description: "If true, the list will be applied only to protected branches.",
         demandOption: false,
     },
-    'project.settings.allowed_ips.primary_branch_only': {
+    'project.settings.enable_logical_replication': {
         type: "boolean",
-        description: "DEPRECATED: Use `protected_branches_only`.\nIf true, the list will be applied only to the default branch.\n",
+        description: "Sets wal_level=logical for all compute endpoints in this project.\nAll active endpoints will be suspended.\nOnce enabled, logical replication cannot be disabled.\n",
         demandOption: false,
     },
-    'project.settings.enable_logical_replication': {
+    'project.settings.maintenance_window.weekdays': {
+        type: "array",
+        description: "A list of weekdays when the maintenance window is active.\nEncoded as ints, where 1 - Monday, and 7 - Sunday.\n",
+        demandOption: true,
+    },
+    'project.settings.maintenance_window.start_time': {
+        type: "string",
+        description: "Start time of the maintenance window, in the format of \"HH:MM\". Uses UTC.\n",
+        demandOption: true,
+    },
+    'project.settings.maintenance_window.end_time': {
+        type: "string",
+        description: "End time of the maintenance window, in the format of \"HH:MM\". Uses UTC.\n",
+        demandOption: true,
+    },
+    'project.settings.block_public_connections': {
         type: "boolean",
-        description: "Sets wal_level=logical for all compute endpoints in this project.\nAll active endpoints will be suspended.\nOnce enabled, logical replication cannot be disabled.\n",
+        description: "When set, connections from the public internet\nare disallowed. This supersedes the AllowedIPs list.\nThis parameter is under active development and its semantics may change in the future.\n",
+        demandOption: false,
+    },
+    'project.settings.block_vpc_connections': {
+        type: "boolean",
+        description: "When set, connections using VPC endpoints are disallowed.\nThis parameter is under active development and its semantics may change in the future.\n",
         demandOption: false,
     },
     'project.name': {
@@ -160,7 +199,7 @@ export const projectUpdateRequest = {
     },
     'project.history_retention_seconds': {
         type: "number",
-        description: "The number of seconds to retain the point-in-time restore (PITR) backup history for this project.\nThe default is 604800 seconds (7 days).\n",
+        description: "The number of seconds to retain the shared history for all branches in this project.\nThe default is 1 day (604800 seconds).\n",
         demandOption: false,
     },
 };
@@ -195,6 +234,17 @@ export const branchCreateRequest = {
         description: "Whether the branch is protected\n",
         demandOption: false,
     },
+    'branch.archived': {
+        type: "boolean",
+        description: "Whether to create the branch as archived\n",
+        demandOption: false,
+    },
+    'branch.schema_initialization_type': {
+        type: "string",
+        description: "The type of schema initialization. Defines how the schema is initialized, currently only empty is supported. This parameter is under\nactive development and may change its semantics in the future.\n",
+        demandOption: false,
+        choices: ["empty"],
+    },
 };
 export const branchCreateRequestEndpointOptions = {
     'type': {
@@ -205,9 +255,8 @@ export const branchCreateRequestEndpointOptions = {
     },
     'provisioner': {
         type: "string",
-        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n",
+        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n",
         demandOption: false,
-        choices: ["k8s-pod", "k8s-neonvm"],
     },
     'suspend_timeout_seconds': {
         type: "number",
@@ -246,9 +295,8 @@ export const endpointCreateRequest = {
     },
     'endpoint.provisioner': {
         type: "string",
-        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n",
+        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n",
         demandOption: false,
-        choices: ["k8s-pod", "k8s-neonvm"],
     },
     'endpoint.pooler_enabled': {
         type: "boolean",
@@ -280,14 +328,13 @@ export const endpointCreateRequest = {
 export const endpointUpdateRequest = {
     'endpoint.branch_id': {
         type: "string",
-        description: "The destination branch ID. The destination branch must not have an exsiting read-write endpoint.\n",
+        description: "DEPRECATED: This field will be removed in a future release.\nThe destination branch ID. The destination branch must not have an exsiting read-write endpoint.\n",
         demandOption: false,
     },
     'endpoint.provisioner': {
         type: "string",
-        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n",
+        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n",
         demandOption: false,
-        choices: ["k8s-pod", "k8s-neonvm"],
     },
     'endpoint.pooler_enabled': {
         type: "boolean",

package/utils/enrichers.js

@@ -4,7 +4,9 @@ export const branchIdResolve = async ({ branch, apiClient, projectId, }) => {
     if (looksLikeBranchId(branch)) {
         return branch;
     }
-    const { data } = await apiClient.listProjectBranches(projectId);
+    const { data } = await apiClient.listProjectBranches({
+        projectId,
+    });
     const branchData = data.branches.find((b) => b.name === branch);
     if (!branchData) {
         throw new Error(`Branch ${branch} not found.\nAvailable branches: ${data.branches
@@ -24,7 +26,9 @@ export const branchIdFromProps = async (props) => {
             projectId: props.projectId,
         });
     }
-    const { data } = await props.apiClient.listProjectBranches(props.projectId);
+    const { data } = await props.apiClient.listProjectBranches({
+        projectId: props.projectId,
+    });
     const defaultBranch = data.branches.find((b) => b.default);
     if (defaultBranch) {
         return defaultBranch.id;
@@ -47,3 +51,16 @@ export const fillSingleProject = async (props) => {
         projectId: data.projects[0].id,
     };
 };
+export const fillSingleOrg = async (props) => {
+    if (props.orgId) {
+        return props;
+    }
+    const { data } = await props.apiClient.getCurrentUserOrganizations();
+    if (data.organizations.length === 0) {
+        throw new Error('No organizations found');
+    }
+    if (data.organizations.length > 1) {
+        throw new Error(`Multiple organizations found, please provide one with the --org-id option`);
+    }
+    return { ...props, orgId: data.organizations[0].id };
+};