neonctl 2.37.1 → 2.38.1

package/dist/commands/branches.js

@@ -1,488 +0,0 @@
-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",
-];
-const BRANCH_FIELDS_RESET = [
-    "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 builder = (argv) => argv
-    .usage("$0 branches <sub-command> [options]")
-    .options({
-    "project-id": {
-        describe: "Project ID",
-        type: "string",
-    },
-})
-    .middleware(fillSingleProject)
-    .middleware((args) => {
-    // 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"],
-    parent: {
-        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",
-        default: true,
-    },
-    type: {
-        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",
-        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",
-    },
-    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)",
-        default: false,
-        hidden: true,
-    },
-    annotation: {
-        type: "string",
-        hidden: true,
-        default: "{}",
-    },
-    "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",
-        requiresArg: true,
-    },
-    protected: {
-        describe: branchCreateRequest["branch.protected"].description,
-        type: "boolean",
-    },
-}), (args) => create(args))
-    .command("reset <id|name>", "Reset a branch", (yargs) => yargs.options({
-    parent: {
-        describe: "Reset to a parent branch",
-        type: "boolean",
-        default: false,
-    },
-    "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
-    // 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.branchId = args.id; // for analytics
-})
-    .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",
-        "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 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",
-    ],
-]), (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({
-    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",
-            requiresArg: false,
-        },
-    }),
-    handler: (args) => setExpiration(args),
-})
-    .command("add-compute <id|name>", "Add a compute to a branch", (yargs) => yargs.options({
-    type: {
-        type: "string",
-        choices: Object.values(EndpointType),
-        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",
-    },
-    name: {
-        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({
-    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(parseSchemaDiffParams)
-            .options({
-            database: {
-                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 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 ^parent",
-                "Compares my-branch to the head of its parent branch",
-            ],
-            [
-                "$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.",
-            ],
-        ]);
-    },
-    handler: (args) => schemaDiff(args),
-});
-export const handler = (args) => {
-    return args;
-};
-const list = async (props) => {
-    const { data: { branches, annotations }, } = await props.apiClient.listProjectBranches({
-        projectId: props.projectId,
-    });
-    // The branch pinned in the local context (.neon), so we can flag it as `[current]` — the
-    // one commands target by default and that `neonctl env pull` would read. The context
-    // stores the branch by name (preferred) or id, so match against either.
-    const currentBranch = contextBranch(readContextFile(props.contextFile));
-    writer(props).end(branches, {
-        fields: BRANCH_FIELDS,
-        renderColumns: {
-            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]");
-                }
-                if (br.protected) {
-                    labels.push("[protected]");
-                }
-                if (isAnon) {
-                    labels.push("[anon]");
-                }
-                if (currentBranch !== undefined &&
-                    (br.id === currentBranch || br.name === currentBranch)) {
-                    labels.push("[current]");
-                }
-                labels.push(br.name);
-                return labels.join(" ");
-            },
-        },
-    });
-};
-const create = async (props) => {
-    const branches = await props.apiClient
-        .listProjectBranches({ projectId: props.projectId })
-        .then(({ data }) => data.branches);
-    const parentProps = (() => {
-        if (!props.parent) {
-            const branch = branches.find((b) => b.default);
-            if (!branch) {
-                throw new Error("No default branch found");
-            }
-            return { parent_id: branch.id };
-        }
-        if (looksLikeLSN(props.parent)) {
-            return { parent_lsn: props.parent };
-        }
-        if (looksLikeTimestamp(props.parent)) {
-            return { parent_timestamp: props.parent };
-        }
-        if (looksLikeBranchId(props.parent)) {
-            return { parent_id: props.parent };
-        }
-        const branch = branches.find((b) => b.name === props.parent);
-        if (!branch) {
-            throw new Error(`Branch ${props.parent} not found`);
-        }
-        return { parent_id: branch.id };
-    })();
-    // Validate schema-only branch requirements
-    if (props.schemaOnly) {
-        if (!props.compute) {
-            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");
-        }
-    }
-    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.protected !== undefined
-                ? { protected: props.protected }
-                : {}),
-        },
-        endpoints: props.compute
-            ? [
-                {
-                    type: props.type,
-                    suspend_timeout_seconds: props.suspendTimeout === 0
-                        ? undefined
-                        : props.suspendTimeout,
-                    ...(props.cu
-                        ? getComputeUnits(props.cu)
-                        : undefined),
-                },
-            ]
-            : [],
-        annotation_value: props.annotation
-            ? JSON.parse(props.annotation)
-            : undefined,
-    }));
-    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.");
-    }
-    const out = writer(props);
-    out.write(data.branch, {
-        fields: BRANCH_FIELDS,
-        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.",
-        });
-    }
-    if (data.connection_uris?.length) {
-        out.write(data.connection_uris, {
-            fields: ["connection_uri"],
-            title: "connection_uris",
-            emptyMessage: "No connection uris have been found",
-        });
-    }
-    out.end();
-    if (props.psql) {
-        if (!data.connection_uris?.length) {
-            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["--"];
-        await psql(connection_uri, psqlArgs, {
-            mode: props.fallback ? "ts" : "auto",
-        });
-    }
-};
-const rename = async (props) => {
-    const branchId = await branchIdFromProps(props);
-    const { data } = await retryOnLock(() => props.apiClient.updateProjectBranch(props.projectId, branchId, {
-        branch: {
-            name: props.newName,
-        },
-    }));
-    writer(props).end(data.branch, {
-        fields: BRANCH_FIELDS,
-    });
-};
-const setDefault = async (props) => {
-    const branchId = await branchIdFromProps(props);
-    const { data } = await retryOnLock(() => props.apiClient.setDefaultProjectBranch(props.projectId, branchId));
-    writer(props).end(data.branch, {
-        fields: BRANCH_FIELDS,
-    });
-};
-const deleteBranch = async (props) => {
-    const branchId = await branchIdFromProps(props);
-    const { data } = await retryOnLock(() => props.apiClient.deleteProjectBranch(props.projectId, branchId));
-    // 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);
-    const { data } = await props.apiClient.getProjectBranch(props.projectId, branchId);
-    writer(props).end(data.branch, {
-        fields: BRANCH_FIELDS,
-    });
-};
-const addCompute = async (props) => {
-    const branchId = await branchIdFromProps(props);
-    const computeName = props.name ? { name: props.name } : null;
-    const { data } = await retryOnLock(() => props.apiClient.createProjectEndpoint(props.projectId, {
-        endpoint: {
-            branch_id: branchId,
-            type: props.type,
-            ...(props.cu ? getComputeUnits(props.cu) : undefined),
-            ...computeName,
-        },
-    }));
-    writer(props).end(data.endpoint, {
-        fields: ["id", "host"],
-    });
-};
-const reset = async (props) => {
-    if (!props.parent) {
-        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");
-    }
-    const { data } = await retryOnLock(() => props.apiClient.restoreProjectBranch(props.projectId, branchId, {
-        source_branch_id: parent_id,
-        preserve_under_name: props.preserveUnderName || undefined,
-    }));
-    writer(props).end(data.branch, {
-        // need to reset types until we expose reset api
-        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.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" && {
-            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.",
-    });
-    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.",
-        });
-    }
-    writeInst.end();
-};
-const setExpiration = async (props) => {
-    // Accept either branch name or id
-    const branchId = await branchIdFromProps({
-        ...props,
-        id: props.branchId,
-    });
-    const expiresAt = typeof props.expiresAt === "string"
-        ? new Date(props.expiresAt).toISOString()
-        : null;
-    const { data } = await retryOnLock(() => props.apiClient.updateProjectBranch(props.projectId, branchId, {
-        branch: {
-            expires_at: expiresAt,
-        },
-    }));
-    writer(props).end(data.branch, {
-        fields: BRANCH_FIELDS,
-    });
-};