neon 2.1.2 → 2.29.0

package/dist/commands/connection_string.js

@@ -0,0 +1,172 @@
+import { EndpointType } from "../utils/api_enums.js";
+import { branchIdFromProps, fillSingleProject } from "../utils/enrichers.js";
+import { parsePITBranch } from "../utils/point_in_time.js";
+import { psql } from "../utils/psql.js";
+import { writer } from "../writer.js";
+export const SSL_MODES = [
+    "require",
+    "verify-ca",
+    "verify-full",
+    "omit",
+];
+export const command = "connection-string [branch]";
+export const aliases = ["cs"];
+export const describe = "Get connection string";
+export const builder = (argv) => {
+    return argv
+        .usage("$0 connection-string [branch] [options]")
+        .example("$0 cs main", "Get connection string for the main branch")
+        .example("$0 cs main@2024-01-01T00:00:00Z", "Get connection string for the main branch at a specific point in time")
+        .example("$0 cs main@0/234235", "Get connection string for the main branch at a specific LSN")
+        .positional("branch", {
+        describe: `Branch name or id. Defaults to the default branch if omitted. Can be written in the point-in-time format: "branch@timestamp" or "branch@lsn"`,
+        type: "string",
+    })
+        .options({
+        "project-id": {
+            type: "string",
+            describe: "Project ID",
+        },
+        "role-name": {
+            type: "string",
+            describe: "Role name",
+        },
+        "database-name": {
+            type: "string",
+            describe: "Database name",
+        },
+        pooled: {
+            type: "boolean",
+            describe: "Use pooled connection",
+            default: false,
+        },
+        prisma: {
+            type: "boolean",
+            describe: "Use connection string for Prisma setup",
+            default: false,
+        },
+        "endpoint-type": {
+            type: "string",
+            choices: Object.values(EndpointType),
+            describe: "Endpoint type",
+        },
+        extended: {
+            type: "boolean",
+            describe: "Show extended information",
+        },
+        psql: {
+            type: "boolean",
+            describe: "Connect to a database via psql using connection string",
+            default: false,
+        },
+        fallback: {
+            type: "boolean",
+            describe: "Force the embedded TypeScript psql fallback (for testing)",
+            default: false,
+            hidden: true,
+        },
+        ssl: {
+            type: "string",
+            choices: SSL_MODES,
+            default: "require",
+            describe: "SSL mode",
+        },
+    })
+        .middleware(fillSingleProject);
+};
+export const handler = async (props) => {
+    const projectId = props.projectId;
+    const parsedPIT = props.branch
+        ? parsePITBranch(props.branch)
+        : { tag: "head", branch: "" };
+    if (props.branch) {
+        props.branch = parsedPIT.branch;
+    }
+    const branchId = await branchIdFromProps(props);
+    const { data: { endpoints }, } = await props.apiClient.listProjectBranchEndpoints(projectId, branchId);
+    const matchEndpointType = props.endpointType ?? EndpointType.ReadWrite;
+    let endpoint = endpoints.find((e) => e.type === matchEndpointType);
+    if (!endpoint && props.endpointType == null) {
+        endpoint = endpoints[0];
+    }
+    if (!endpoint) {
+        throw new Error(`No ${props.endpointType ?? ""} endpoint found for the branch: ${branchId}`);
+    }
+    const role = props.roleName ||
+        (await props.apiClient
+            .listProjectBranchRoles(projectId, branchId)
+            .then(({ data }) => {
+            if (data.roles.length === 0) {
+                throw new Error(`No roles found for the branch: ${branchId}`);
+            }
+            if (data.roles.length === 1) {
+                return data.roles[0].name;
+            }
+            throw new Error(`Multiple roles found for the branch, please provide one with the --role-name option: ${data.roles
+                .map((r) => r.name)
+                .join(", ")}`);
+        }));
+    const { data: { databases: branchDatabases }, } = await props.apiClient.listProjectBranchDatabases(projectId, branchId);
+    const database = props.databaseName ||
+        (() => {
+            if (branchDatabases.length === 0) {
+                throw new Error(`No databases found for the branch: ${branchId}`);
+            }
+            if (branchDatabases.length === 1) {
+                return branchDatabases[0].name;
+            }
+            throw new Error(`Multiple databases found for the branch, please provide one with the --database-name option: ${branchDatabases
+                .map((d) => d.name)
+                .join(", ")}`);
+        })();
+    if (!branchDatabases.find((d) => d.name === database)) {
+        throw new Error(`Database not found: ${database}`);
+    }
+    const { data: { password }, } = await props.apiClient.getProjectBranchRolePassword(props.projectId, endpoint.branch_id, role);
+    let host = props.pooled
+        ? endpoint.host.replace(endpoint.id, `${endpoint.id}-pooler`)
+        : endpoint.host;
+    if (parsedPIT.tag !== "head") {
+        host = endpoint.host.replace(endpoint.id, endpoint.branch_id);
+    }
+    const connectionString = new URL(`postgresql://${host}`);
+    connectionString.pathname = database;
+    connectionString.username = role;
+    connectionString.password = password;
+    if (props.prisma) {
+        connectionString.searchParams.set("connect_timeout", "30");
+        if (props.pooled) {
+            connectionString.searchParams.set("pool_timeout", "30");
+            connectionString.searchParams.set("pgbouncer", "true");
+        }
+    }
+    if (props.ssl !== "omit") {
+        connectionString.searchParams.set("sslmode", props.ssl);
+        connectionString.searchParams.set("channel_binding", "require");
+    }
+    if (parsedPIT.tag === "lsn") {
+        connectionString.searchParams.set("options", `neon_lsn:${parsedPIT.lsn}`);
+    }
+    else if (parsedPIT.tag === "timestamp") {
+        connectionString.searchParams.set("options", `neon_timestamp:${parsedPIT.timestamp}`);
+    }
+    if (props.psql) {
+        const psqlArgs = props["--"];
+        await psql(connectionString.toString(), psqlArgs, {
+            mode: props.fallback ? "ts" : "auto",
+        });
+    }
+    else if (props.extended) {
+        writer(props).end({
+            connection_string: connectionString.toString(),
+            host,
+            role,
+            password,
+            database,
+            options: connectionString.searchParams.toString(),
+        }, { fields: ["host", "role", "password", "database"] });
+    }
+    else {
+        process.stdout.write(connectionString.toString() + "\n");
+    }
+};

package/dist/commands/data_api.js

@@ -0,0 +1,285 @@
+import { isNeonApiError, retryOnLock } from "../api.js";
+import { log } from "../log.js";
+import { branchIdFromProps, fillSingleProject, resolveSingleDatabase, } from "../utils/enrichers.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 (isNeonApiError(err) && err.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 (isNeonApiError(err) && err.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 (isNeonApiError(err) && err.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 (isNeonApiError(err) && err.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/dist/commands/databases.js

@@ -0,0 +1,82 @@
+import { retryOnLock } from "../api.js";
+import { branchIdFromProps, fillSingleProject } from "../utils/enrichers.js";
+import { writer } from "../writer.js";
+export const DATABASE_FIELDS = ["name", "owner_name", "created_at"];
+export const command = "databases";
+export const describe = "Manage databases";
+export const aliases = ["database", "db"];
+export const builder = (argv) => argv
+    .usage("$0 databases <sub-command> [options]")
+    .options({
+    "project-id": {
+        describe: "Project ID",
+        type: "string",
+    },
+    branch: {
+        describe: "Branch ID or name",
+        type: "string",
+    },
+})
+    .middleware(fillSingleProject)
+    .command("list", "List databases", (yargs) => yargs, (args) => list(args))
+    .command("create", "Create a database", (yargs) => yargs.options({
+    name: {
+        describe: "Database name",
+        type: "string",
+        demandOption: true,
+    },
+    "owner-name": {
+        describe: "Owner name",
+        type: "string",
+    },
+}), (args) => create(args))
+    .command("delete <database>", "Delete a database", (yargs) => yargs, (args) => deleteDb(args));
+export const handler = (args) => {
+    return args;
+};
+export const list = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { data } = await props.apiClient.listProjectBranchDatabases(props.projectId, branchId);
+    writer(props).end(data.databases, {
+        fields: DATABASE_FIELDS,
+    });
+};
+export const create = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const owner = props.ownerName ??
+        (await props.apiClient
+            .listProjectBranchRoles(props.projectId, branchId)
+            .then(({ data }) => {
+            if (data.roles.length === 0) {
+                throw new Error(`No roles found in branch ${branchId}`);
+            }
+            if (data.roles.length > 1) {
+                throw new Error(`More than one role found in branch ${branchId}. Please specify the owner name. Roles: ${data.roles
+                    .map((r) => r.name)
+                    .join(", ")}`);
+            }
+            return data.roles[0].name;
+        }));
+    if (!owner) {
+        throw new Error("No owner found");
+    }
+    const { data } = await retryOnLock(() => props.apiClient.createProjectBranchDatabase(props.projectId, branchId, {
+        database: {
+            name: props.name,
+            owner_name: owner,
+        },
+    }));
+    writer(props).end(data.database, {
+        fields: DATABASE_FIELDS,
+    });
+};
+export const deleteDb = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { data } = await retryOnLock(() => props.apiClient.deleteProjectBranchDatabase(props.projectId, branchId, props.database));
+    // A 204 (database already gone) carries no body; only a 200 returns it.
+    if (data) {
+        writer(props).end(data.database, {
+            fields: DATABASE_FIELDS,
+        });
+    }
+};

package/dist/commands/deploy.js

@@ -0,0 +1,26 @@
+import { fillSingleProject } from "../utils/enrichers.js";
+import { applyCmd, applyFlags, envFlag, envPullFlag, } from "./config.js";
+export const command = "deploy";
+export const describe = "Apply a neon.ts policy to a branch (alias for `config apply`)";
+export const builder = (argv) => argv
+    .usage("$0 deploy [options]")
+    .options({
+    "project-id": {
+        describe: "Project ID",
+        type: "string",
+    },
+    branch: {
+        describe: "Branch ID or name",
+        type: "string",
+    },
+    config: {
+        describe: "Path to a neon.ts policy (defaults to walking up from cwd)",
+        type: "string",
+    },
+    ...envFlag,
+    ...applyFlags,
+    ...envPullFlag,
+})
+    .middleware(fillSingleProject)
+    .strict();
+export const handler = (props) => applyCmd(props);