neonctl 2.21.2 → 2.22.2

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/data_api.test.js

@@ -0,0 +1,169 @@
+import { describe } from 'vitest';
+import { test } from '../test_utils/fixtures';
+describe('data-api', () => {
+    test('delete', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'data-api',
+            'delete',
+            '--project-id',
+            'test-project-123456',
+            '--branch',
+            'main',
+            '--database',
+            'db1',
+        ], {
+            mockDir: 'single_org',
+            stderr: 'INFO: Data API deleted for db1 on branch br-main-branch-123456',
+        });
+    });
+    test('get', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'data-api',
+            'get',
+            '--project-id',
+            'test-project-123456',
+            '--branch',
+            'main',
+            '--database',
+            'db1',
+        ], { mockDir: 'single_org' });
+    });
+    test('get with table output', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'data-api',
+            'get',
+            '--project-id',
+            'test-project-123456',
+            '--branch',
+            'main',
+            '--database',
+            'db1',
+        ], { mockDir: 'single_org', outputTable: true });
+    });
+    test('create', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'data-api',
+            'create',
+            '--project-id',
+            'test-project-123456',
+            '--branch',
+            'main',
+            '--database',
+            'db1',
+            '--auth-provider',
+            'neon_auth',
+            '--add-default-grants',
+            '--db-schemas',
+            'public,analytics',
+            '--db-max-rows',
+            '500',
+        ], { mockDir: 'single_org' });
+    });
+    test('update --replace', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'data-api',
+            'update',
+            '--project-id',
+            'test-project-123456',
+            '--branch',
+            'main',
+            '--database',
+            'db1',
+            '--replace',
+            '--db-max-rows',
+            '250',
+        ], {
+            mockDir: 'single_org',
+            stderr: 'INFO: Data API settings updated for db1 on branch br-main-branch-123456',
+        });
+    });
+    test('update merges with existing settings', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'data-api',
+            'update',
+            '--project-id',
+            'test-project-123456',
+            '--branch',
+            'main',
+            '--database',
+            'db1',
+            '--db-max-rows',
+            '9999',
+        ], {
+            mockDir: 'single_org',
+            stderr: 'INFO: Data API settings updated for db1 on branch br-main-branch-123456',
+        });
+    });
+    test('update fails when no settings flags are passed', async ({ testCliCommand, }) => {
+        await testCliCommand([
+            'data-api',
+            'update',
+            '--project-id',
+            'test-project-123456',
+            '--branch',
+            'main',
+            '--database',
+            'db1',
+            '--replace',
+        ], {
+            mockDir: 'single_org',
+            code: 1,
+            stderr: '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.',
+        });
+    });
+    test('refresh-schema sends empty PATCH', async ({ testCliCommand }) => {
+        await testCliCommand([
+            'data-api',
+            'refresh-schema',
+            '--project-id',
+            'test-project-123456',
+            '--branch',
+            'main',
+            '--database',
+            'db1',
+        ], {
+            mockDir: 'single_org',
+            stderr: 'INFO: Data API schema cache refreshed for db1 on branch br-main-branch-123456',
+        });
+    });
+    test('delete with implicit database', async ({ testCliCommand }) => {
+        // The single_org fixture has exactly one database (db1) on the main branch,
+        // so omitting --database should resolve it automatically.
+        await testCliCommand([
+            'data-api',
+            'delete',
+            '--project-id',
+            'test-project-123456',
+            '--branch',
+            'main',
+        ], {
+            mockDir: 'single_org',
+            stderr: 'INFO: Data API deleted for db1 on branch br-main-branch-123456',
+        });
+    });
+    test('get with fully implicit resolution', async ({ testCliCommand }) => {
+        // single_org has one org, one project, one default branch (main), one
+        // database (db1) — all three should be auto-resolved when omitted.
+        await testCliCommand(['data-api', 'get'], { mockDir: 'single_org' });
+    });
+    test('update with fully implicit resolution', async ({ testCliCommand }) => {
+        await testCliCommand(['data-api', 'update', '--db-max-rows', '9999'], {
+            mockDir: 'single_org',
+            stderr: 'INFO: Data API settings updated for db1 on branch br-main-branch-123456',
+        });
+    });
+    test('delete fails with helpful error when multiple databases', async ({ testCliCommand, }) => {
+        await testCliCommand([
+            'data-api',
+            'delete',
+            '--project-id',
+            'test-project-123456',
+            '--branch',
+            'main',
+        ], {
+            mockDir: 'single_org_multidb',
+            code: 1,
+            stderr: 'ERROR: Multiple databases found for the branch, please provide one with the --database option: db1, db2',
+        });
+    });
+});

package/commands/index.js

@@ -9,8 +9,12 @@ 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';
 export default [
     auth,
     users,
@@ -23,6 +27,10 @@ export default [
     roles,
     operations,
     cs,
+    psql,
     setContext,
+    checkout,
+    link,
     init,
+    dataApi,
 ];