@heroku/heroku-cli-util 9.1.3 → 9.2.0

package/README.md

@@ -105,7 +105,6 @@ try {
  * types.pg.AddOnAttachmentWithConfigVarsAndPlan
  * types.pg.AddOnWithRelatedData
  * types.pg.ConnectionDetails
- * types.pg.ConnectionDetailsWithAttachment
  * types.pg.Link
  * types.pg.TunnelConfig
  */

package/dist/errors/ambiguous.d.ts

@@ -1,10 +1,10 @@
-import type { ExtendedAddonAttachment } from '../types/pg/data-api';
+import type { ExtendedAddon, ExtendedAddonAttachment } from '../types/pg/platform-api';
 /**
  * This error is used internally to signal when the `AddonAttachmentResolver` cannot resolve
  * to a single attachment.
  */
 export declare class AmbiguousError extends Error {
-    readonly matches: ExtendedAddonAttachment[];
+    readonly matches: ExtendedAddon[] | ExtendedAddonAttachment[];
     readonly type: string;
     readonly body: {
         id: string;
@@ -12,5 +12,5 @@ export declare class AmbiguousError extends Error {
     };
     readonly message: string;
     readonly statusCode = 422;
-    constructor(matches: ExtendedAddonAttachment[], type: string);
+    constructor(matches: ExtendedAddon[] | ExtendedAddonAttachment[], type: string);
 }

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { APIClient } from '@heroku-cli/command';
 import { AmbiguousError } from './errors/ambiguous';
 import { NotFound } from './errors/not-found';
-import { AddOnWithRelatedData, ExtendedAddonAttachment, Link } from './types/pg/data-api';
-import { ConnectionDetails, ConnectionDetailsWithAttachment, TunnelConfig } from './types/pg/tunnel';
+import { AddOnWithRelatedData, ExtendedAddon, ExtendedAddonAttachment, Link } from './types/pg/platform-api';
+import { ConnectionDetails, TunnelConfig } from './types/pg/tunnel';
+import AddonResolver from './utils/addons/addon-resolver';
 import { getPsqlConfigs, sshTunnel } from './utils/pg/bastion';
 import { getConfigVarNameFromAttachment } from './utils/pg/config-vars';
 import DatabaseResolver from './utils/pg/databases';
@@ -15,20 +15,21 @@ import { styledJSON } from './ux/styled-json';
 import { styledObject } from './ux/styled-object';
 import { table } from './ux/table';
 import { wait } from './ux/wait';
-export type { AddOnWithRelatedData, ExtendedAddonAttachment, Link, } from './types/pg/data-api';
-export type { ConnectionDetails, ConnectionDetailsWithAttachment, TunnelConfig, } from './types/pg/tunnel';
+export type { AddOnWithRelatedData, ExtendedAddon, ExtendedAddonAttachment, Link, } from './types/pg/platform-api';
+export type { ConnectionDetails, TunnelConfig, } from './types/pg/tunnel';
 /** @deprecated Use direct type imports instead */
 export declare const types: {
     pg: {
         AddOnWithRelatedData: AddOnWithRelatedData;
         ConnectionDetails: ConnectionDetails;
-        ConnectionDetailsWithAttachment: ConnectionDetailsWithAttachment;
+        ExtendedAddon: ExtendedAddon;
         ExtendedAddonAttachment: ExtendedAddonAttachment;
         Link: Link;
         TunnelConfig: TunnelConfig;
     };
 };
 export declare const utils: {
+    AddonResolver: typeof AddonResolver;
     errors: {
         AmbiguousError: typeof AmbiguousError;
         NotFound: typeof NotFound;
@@ -36,12 +37,15 @@ export declare const utils: {
     pg: {
         DatabaseResolver: typeof DatabaseResolver;
         PsqlService: typeof PsqlService;
-        fetcher: {
-            database(heroku: APIClient, appId: string, attachmentId?: string, namespace?: string): Promise<ConnectionDetailsWithAttachment>;
-        };
+        addonService: () => string;
         host: typeof getHost;
+        isAdvancedDatabase: (addon: ExtendedAddon | ExtendedAddonAttachment["addon"]) => boolean;
+        isAdvancedPrivateDatabase: (addon: ExtendedAddon | ExtendedAddonAttachment["addon"]) => boolean;
+        isEssentialDatabase: (addon: ExtendedAddon | ExtendedAddonAttachment["addon"]) => boolean;
+        isLegacyDatabase: (addon: ExtendedAddon | ExtendedAddonAttachment["addon"]) => boolean;
+        isLegacyEssentialDatabase: (addon: ExtendedAddon | ExtendedAddonAttachment["addon"]) => boolean;
+        isPostgresAddon: (addon: ExtendedAddon | ExtendedAddonAttachment["addon"]) => boolean;
         psql: {
-            exec(connectionDetails: ConnectionDetailsWithAttachment, query: string, psqlCmdArgs?: string[]): Promise<string>;
             getConfigVarNameFromAttachment: typeof getConfigVarNameFromAttachment;
             getPsqlConfigs: typeof getPsqlConfigs;
             sshTunnel: typeof sshTunnel;

package/dist/index.js

@@ -4,6 +4,8 @@ exports.hux = exports.utils = exports.types = void 0;
 const tslib_1 = require("tslib");
 const ambiguous_1 = require("./errors/ambiguous");
 const not_found_1 = require("./errors/not-found");
+const addon_resolver_1 = tslib_1.__importDefault(require("./utils/addons/addon-resolver"));
+const helpers_1 = require("./utils/addons/helpers");
 const bastion_1 = require("./utils/pg/bastion");
 const config_vars_1 = require("./utils/pg/config-vars");
 const databases_1 = tslib_1.__importDefault(require("./utils/pg/databases"));
@@ -22,13 +24,14 @@ exports.types = {
     pg: {
         AddOnWithRelatedData: {},
         ConnectionDetails: {},
-        ConnectionDetailsWithAttachment: {},
+        ExtendedAddon: {},
         ExtendedAddonAttachment: {},
         Link: {},
         TunnelConfig: {},
     },
 };
 exports.utils = {
+    AddonResolver: addon_resolver_1.default,
     errors: {
         AmbiguousError: ambiguous_1.AmbiguousError,
         NotFound: not_found_1.NotFound, // This should be NotFoundError for consistency, but we're keeping it for backwards compatibility
@@ -36,18 +39,15 @@ exports.utils = {
     pg: {
         DatabaseResolver: databases_1.default,
         PsqlService: psql_1.default,
-        fetcher: {
-            database(heroku, appId, attachmentId, namespace) {
-                const databaseResolver = new databases_1.default(heroku);
-                return databaseResolver.getDatabase(appId, attachmentId, namespace);
-            },
-        },
+        addonService: helpers_1.getAddonService,
         host: host_1.default,
+        isAdvancedDatabase: helpers_1.isAdvancedDatabase,
+        isAdvancedPrivateDatabase: helpers_1.isAdvancedPrivateDatabase,
+        isEssentialDatabase: helpers_1.isEssentialDatabase,
+        isLegacyDatabase: helpers_1.isLegacyDatabase,
+        isLegacyEssentialDatabase: helpers_1.isLegacyEssentialDatabase,
+        isPostgresAddon: helpers_1.isPostgresAddon,
         psql: {
-            exec(connectionDetails, query, psqlCmdArgs = []) {
-                const psqlService = new psql_1.default(connectionDetails);
-                return psqlService.execQuery(query, psqlCmdArgs);
-            },
             getConfigVarNameFromAttachment: config_vars_1.getConfigVarNameFromAttachment,
             getPsqlConfigs: bastion_1.getPsqlConfigs,
             sshTunnel: bastion_1.sshTunnel,

package/dist/types/pg/{data-api.d.ts → platform-api.d.ts}

@@ -31,6 +31,18 @@ type AddonAttachmentWithConfigVarsInclusion = {
 export type ExtendedAddonAttachment = {
     addon: AddonDescriptorWithPlanInclusion;
 } & AddonAttachmentWithConfigVarsInclusion;
+/**
+ * This is the modified type for the `AddOn` we use on these lib functions because all requests made to
+ * Platform API to get add-ons, either through the Add-on List endpoint or the add-on resolver action endpoint,
+ * include the header `Accept-Expansion: addon_service,plan`.
+ */
+export type ExtendedAddon = {
+    addon_service: DeepRequired<Heroku.AddOnService>;
+    plan: DeepRequired<Heroku.Plan>;
+} & DeepRequired<Heroku.AddOn>;
+/**
+ * The next two types need review and cleanup. They're not used anywhere in this codebase yet.
+ */
 export type AddOnWithRelatedData = {
     attachment_names?: string[];
     links?: Link[];

package/dist/types/pg/tunnel.d.ts

@@ -1,7 +1,8 @@
 import { Server } from 'node:net';
-import type { ExtendedAddonAttachment } from './data-api';
+import type { ExtendedAddonAttachment } from './platform-api';
 export type ConnectionDetails = {
     _tunnel?: Server;
+    attachment?: ExtendedAddonAttachment;
     database: string;
     host: string;
     password: string;
@@ -10,9 +11,6 @@ export type ConnectionDetails = {
     url: string;
     user: string;
 } & BastionConfig;
-export type ConnectionDetailsWithAttachment = {
-    attachment: ExtendedAddonAttachment;
-} & ConnectionDetails;
 export interface TunnelConfig {
     dstHost: string;
     dstPort: number;

package/dist/utils/addons/addon-resolver.d.ts

@@ -0,0 +1,8 @@
+import type { APIClient } from '@heroku-cli/command';
+import type { ExtendedAddon } from '../../types/pg/platform-api';
+export default class AddonResolver {
+    private readonly heroku;
+    private readonly addonHeaders;
+    constructor(heroku: APIClient);
+    resolve(addon: string, app?: string, addonService?: string): Promise<ExtendedAddon>;
+}

package/dist/utils/addons/addon-resolver.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ambiguous_1 = require("../../errors/ambiguous");
+class AddonResolver {
+    constructor(heroku) {
+        this.heroku = heroku;
+        this.addonHeaders = {
+            Accept: 'application/vnd.heroku+json; version=3.sdk',
+            'Accept-Expansion': 'addon_service,plan',
+        };
+    }
+    async resolve(addon, app, addonService) {
+        var _a, _b;
+        const [appPart, addonPart] = (_b = (_a = addon.match(/^(.+)::(.+)$/)) === null || _a === void 0 ? void 0 : _a.slice(1)) !== null && _b !== void 0 ? _b : [app, addon];
+        console.log('appPart', appPart);
+        console.log('addonPart', addonPart);
+        const { body: addons } = await this.heroku.post('/actions/addons/resolve', {
+            body: {
+                addon: addonPart,
+                addon_service: addonService,
+                app: appPart,
+            },
+            headers: this.addonHeaders,
+        });
+        if (addons.length === 1) {
+            return addons[0];
+        }
+        throw new ambiguous_1.AmbiguousError(addons, 'addon');
+    }
+}
+exports.default = AddonResolver;

package/dist/utils/addons/{resolve.d.ts → attachment-resolver.d.ts}

@@ -1,5 +1,5 @@
 import type { APIClient } from '@heroku-cli/command';
-import type { ExtendedAddonAttachment } from '../../types/pg/data-api';
+import type { ExtendedAddonAttachment } from '../../types/pg/platform-api';
 export interface AddonAttachmentResolverOptions {
     addonService?: string;
     namespace?: string;

package/dist/utils/addons/helpers.d.ts

@@ -0,0 +1,8 @@
+import { ExtendedAddon, ExtendedAddonAttachment } from '../../types/pg/platform-api';
+export declare const getAddonService: () => string;
+export declare const isPostgresAddon: (addon: ExtendedAddon | ExtendedAddonAttachment["addon"]) => boolean;
+export declare const isAdvancedDatabase: (addon: ExtendedAddon | ExtendedAddonAttachment["addon"]) => boolean;
+export declare const isAdvancedPrivateDatabase: (addon: ExtendedAddon | ExtendedAddonAttachment["addon"]) => boolean;
+export declare const isLegacyDatabase: (addon: ExtendedAddon | ExtendedAddonAttachment["addon"]) => boolean;
+export declare const isLegacyEssentialDatabase: (addon: ExtendedAddon | ExtendedAddonAttachment["addon"]) => boolean;
+export declare const isEssentialDatabase: (addon: ExtendedAddon | ExtendedAddonAttachment["addon"]) => boolean;

package/dist/utils/addons/helpers.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEssentialDatabase = exports.isLegacyEssentialDatabase = exports.isLegacyDatabase = exports.isAdvancedPrivateDatabase = exports.isAdvancedDatabase = exports.isPostgresAddon = exports.getAddonService = void 0;
+const getAddonService = () => process.env.HEROKU_POSTGRESQL_ADDON_NAME || process.env.HEROKU_DATA_SERVICE || 'heroku-postgresql';
+exports.getAddonService = getAddonService;
+const isPostgresAddon = (addon) => addon.plan.name.split(':', 2)[0] === (0, exports.getAddonService)();
+exports.isPostgresAddon = isPostgresAddon;
+const isAdvancedDatabase = (addon) => (0, exports.isPostgresAddon)(addon) && /^(advanced|performance)/.test(addon.plan.name.split(':', 2)[1]);
+exports.isAdvancedDatabase = isAdvancedDatabase;
+const isAdvancedPrivateDatabase = (addon) => (0, exports.isAdvancedDatabase)(addon) && /(private|shield)/.test(addon.plan.name.split(':', 2)[1]);
+exports.isAdvancedPrivateDatabase = isAdvancedPrivateDatabase;
+const isLegacyDatabase = (addon) => (0, exports.isPostgresAddon)(addon) && !(0, exports.isAdvancedDatabase)(addon);
+exports.isLegacyDatabase = isLegacyDatabase;
+const isLegacyEssentialDatabase = (addon) => (0, exports.isLegacyDatabase)(addon) && /^(dev|basic|mini)/.test(addon.plan.name.split(':', 2)[1]);
+exports.isLegacyEssentialDatabase = isLegacyEssentialDatabase;
+const isEssentialDatabase = (addon) => (0, exports.isLegacyDatabase)(addon) && addon.plan.name.split(':', 2)[1].startsWith('essential');
+exports.isEssentialDatabase = isEssentialDatabase;

package/dist/utils/pg/bastion.d.ts

@@ -1,6 +1,6 @@
 import type { APIClient } from '@heroku-cli/command';
 import { Server } from 'node:net';
-import { ExtendedAddonAttachment } from '../../types/pg/data-api';
+import { ExtendedAddonAttachment } from '../../types/pg/platform-api';
 import { BastionConfig, ConnectionDetails, TunnelConfig } from '../../types/pg/tunnel';
 /**
  * Determines whether the attachment belongs to an add-on installed onto a non-shield Private Space.

package/dist/utils/pg/config-vars.d.ts

@@ -1,6 +1,6 @@
 import type { HTTP } from '@heroku/http-call';
 import type { APIClient } from '@heroku-cli/command';
-import type { ExtendedAddonAttachment } from '../../types/pg/data-api';
+import type { ExtendedAddonAttachment } from '../../types/pg/platform-api';
 /**
  * Cache of app config vars.
  */

package/dist/utils/pg/databases.d.ts

@@ -1,6 +1,6 @@
 import { APIClient } from '@heroku-cli/command';
-import type { ExtendedAddonAttachment } from '../../types/pg/data-api';
-import type { ConnectionDetails, ConnectionDetailsWithAttachment } from '../../types/pg/tunnel';
+import type { ExtendedAddon, ExtendedAddonAttachment } from '../../types/pg/platform-api';
+import type { ConnectionDetails } from '../../types/pg/tunnel';
 import { fetchBastionConfig } from './bastion';
 import { getConfig } from './config-vars';
 export default class DatabaseResolver {
@@ -8,8 +8,34 @@ export default class DatabaseResolver {
     private readonly getConfigFn;
     private readonly fetchBastionConfigFn;
     private readonly addonAttachmentResolver;
+    private readonly addonHeaders;
     private readonly attachmentHeaders;
     constructor(heroku: APIClient, getConfigFn?: typeof getConfig, fetchBastionConfigFn?: typeof fetchBastionConfig);
+    /**
+     * Parses a PostgreSQL connection string (or a local database name) into a ConnectionDetails object.
+     *
+     * @param connStringOrDbName - PostgreSQL connection string or local database name
+     * @returns Connection details object with parsed connection information
+     */
+    static parsePostgresConnectionString(connStringOrDbName: string): ConnectionDetails;
+    /**
+     * Return all Heroku Postgres databases on the Legacy tiers for a given app.
+     *
+     * @param app - The name of the app to get the databases for
+     * @returns Promise resolving to all Heroku Postgres databases
+     * @throws {Error} When no legacy database add-on exists on the app
+     */
+    getAllLegacyDatabases(app: string): Promise<Array<{
+        attachment_names?: string[];
+    } & ExtendedAddonAttachment['addon']>>;
+    /**
+     * Resolves an arbitrary legacy database add-on based on the provided app name.
+     *
+     * @param app - The name of the app to get the arbitrary legacy database for
+     * @returns Promise resolving to the arbitrary legacy database add-on
+     * @throws {Error} When no legacy database add-on exists on the app
+     */
+    getArbitraryLegacyDB(app: string): Promise<ExtendedAddon>;
     /**
      * Resolves a database attachment based on the provided database identifier
      * (attachment name, id, or config var name) and namespace (credential).
@@ -22,6 +48,14 @@ export default class DatabaseResolver {
      * @throws {AmbiguousError} When multiple matching attachments are found
      */
     getAttachment(appId: string, attachmentId?: string, namespace?: string): Promise<ExtendedAddonAttachment>;
+    /**
+     * Returns the connection details for a database attachment according to the app config vars.
+     *
+     * @param attachment - The attachment to get the connection details for
+     * @param config - The record of app config vars with their values
+     * @returns Connection details with attachment information
+     */
+    getConnectionDetails(attachment: ExtendedAddonAttachment, config?: Record<string, string>): ConnectionDetails;
     /**
      * Returns the connection details for a database attachment resolved through the identifiers passed as
      * arguments: appId, attachmentId and namespace (credential).
@@ -31,14 +65,14 @@ export default class DatabaseResolver {
      * @param namespace - Optional namespace/credential for the attachment
      * @returns Promise resolving to connection details with attachment information
      */
-    getDatabase(appId: string, attachmentId?: string, namespace?: string): Promise<ConnectionDetailsWithAttachment>;
+    getDatabase(appId: string, attachmentId?: string, namespace?: string): Promise<ConnectionDetails>;
     /**
-     * Parses a PostgreSQL connection string (or a local database name) into a ConnectionDetails object.
+     * Helper function that attempts to find all Heroku Postgres attachments on a given app.
      *
-     * @param connStringOrDbName - PostgreSQL connection string or local database name
-     * @returns Connection details object with parsed connection information
+     * @param app - The name of the app to get the attachments for
+     * @returns Promise resolving to an array of all Heroku Postgres attachments on the app
      */
-    static parsePostgresConnectionString(connStringOrDbName: string): ConnectionDetails;
+    private allLegacyDatabaseAttachments;
     /**
      * Fetches all Heroku PostgreSQL add-on attachments for a given app.
      *
@@ -51,15 +85,29 @@ export default class DatabaseResolver {
      */
     private allPostgresAttachments;
     /**
-     * Returns the connection details for a database attachment according to the app config vars.
+     * Helper function that groups Heroku Postgres attachments by addon.
      *
-     * @param attachment - The attachment to get the connection details for
-     * @param config - The record of app config vars with their values
-     * @returns Connection details with attachment information
+     * @param attachments - The attachments to group by addon
+     * @returns A record of addon IDs with their attachment names
+     */
+    private getAttachmentNamesByAddon;
+    /**
+     * Helper function that attempts to find a single addon attachment matching the given database identifier
+     * by comparing the identifier to the config var names of all attachments on the app
+     * (attachment name, id, or config var name).
+     *
+     * This is used internally by the `getAttachment` function to handle the lookup of addon attachments.
+     * It returns either an array with a single match or an empty array if no matches are found.
+     *
+     * @param attachments - Array of attachments for the specified app ID
+     * @param appId - The ID of the app to search for attachments
+     * @param attachmentId - The database identifier to match
+     * @returns Promise resolving to either a single match or no matches
      */
-    getConnectionDetails(attachment: ExtendedAddonAttachment, config?: Record<string, string>): ConnectionDetailsWithAttachment;
+    private getAttachmentsViaConfigVarNames;
     /**
      * Helper function that attempts to find a single addon attachment matching the given database identifier
+     * via the add-on attachments resolver
      * (attachment name, id, or config var name).
      *
      * This is used internally by the `getAttachment` function to handle the lookup of addon attachments.
@@ -72,5 +120,5 @@ export default class DatabaseResolver {
      * @param namespace - Optional namespace/credential filter
      * @returns Promise resolving to either a single match, multiple matches with error, or no matches with error
      */
-    private matchesHelper;
+    private getAttachmentsViaResolver;
 }

package/dist/utils/pg/databases.js

@@ -5,7 +5,8 @@ const color_1 = require("@heroku-cli/color");
 const api_client_1 = require("@heroku-cli/command/lib/api-client");
 const debug_1 = tslib_1.__importDefault(require("debug"));
 const ambiguous_1 = require("../../errors/ambiguous");
-const resolve_1 = tslib_1.__importDefault(require("../addons/resolve"));
+const attachment_resolver_1 = tslib_1.__importDefault(require("../addons/attachment-resolver"));
+const helpers_1 = require("../addons/helpers");
 const bastion_1 = require("./bastion");
 const config_vars_1 = require("./config-vars");
 const pgDebug = (0, debug_1.default)('pg');
@@ -14,11 +15,73 @@ class DatabaseResolver {
         this.heroku = heroku;
         this.getConfigFn = getConfigFn;
         this.fetchBastionConfigFn = fetchBastionConfigFn;
+        this.addonHeaders = {
+            Accept: 'application/vnd.heroku+json; version=3.sdk',
+            'Accept-Expansion': 'addon_service,plan',
+        };
         this.attachmentHeaders = {
             Accept: 'application/vnd.heroku+json; version=3.sdk',
             'Accept-Inclusion': 'addon:plan,config_vars',
         };
-        this.addonAttachmentResolver = new resolve_1.default(this.heroku);
+        this.addonAttachmentResolver = new attachment_resolver_1.default(this.heroku);
+    }
+    /**
+     * Parses a PostgreSQL connection string (or a local database name) into a ConnectionDetails object.
+     *
+     * @param connStringOrDbName - PostgreSQL connection string or local database name
+     * @returns Connection details object with parsed connection information
+     */
+    static parsePostgresConnectionString(connStringOrDbName) {
+        const dbPath = /:\/\//.test(connStringOrDbName) ? connStringOrDbName : `postgres:///${connStringOrDbName}`;
+        const url = new URL(dbPath);
+        const { hostname, password, pathname, port, username } = url;
+        return {
+            database: pathname.slice(1), // remove the leading slash from the pathname
+            host: hostname,
+            password,
+            pathname,
+            port: port || process.env.PGPORT || (hostname && '5432'),
+            url: dbPath,
+            user: username,
+        };
+    }
+    /**
+     * Return all Heroku Postgres databases on the Legacy tiers for a given app.
+     *
+     * @param app - The name of the app to get the databases for
+     * @returns Promise resolving to all Heroku Postgres databases
+     * @throws {Error} When no legacy database add-on exists on the app
+     */
+    async getAllLegacyDatabases(app) {
+        pgDebug(`fetching all legacy databases on ${app}`);
+        const allAttachments = await this.allLegacyDatabaseAttachments(app);
+        const addons = [];
+        for (const attachment of allAttachments) {
+            if (!addons.some(a => a.id === attachment.addon.id)) {
+                addons.push(attachment.addon);
+            }
+        }
+        const attachmentNamesByAddon = this.getAttachmentNamesByAddon(allAttachments);
+        for (const addon of addons) {
+            // eslint-disable-next-line camelcase
+            addon.attachment_names = attachmentNamesByAddon[addon.id];
+        }
+        return addons;
+    }
+    /**
+     * Resolves an arbitrary legacy database add-on based on the provided app name.
+     *
+     * @param app - The name of the app to get the arbitrary legacy database for
+     * @returns Promise resolving to the arbitrary legacy database add-on
+     * @throws {Error} When no legacy database add-on exists on the app
+     */
+    async getArbitraryLegacyDB(app) {
+        pgDebug(`fetching arbitrary legacy database on ${app}`);
+        const { body: addons } = await this.heroku.get(`/apps/${app}/addons`, { headers: this.addonHeaders });
+        const addon = addons.find(a => a.app.name === app && (0, helpers_1.isLegacyDatabase)(a));
+        if (!addon)
+            throw new Error(`No Heroku Postgres legacy database on ${app}`);
+        return addon;
     }
     /**
      * Resolves a database attachment based on the provided database identifier
@@ -38,20 +101,24 @@ class DatabaseResolver {
             appId = appConfigMatch[1];
             attachmentId = appConfigMatch[2];
         }
-        const { error, matches } = await this.matchesHelper(appId, attachmentId, namespace);
+        let { error, matches } = await this.getAttachmentsViaResolver(appId, attachmentId, namespace);
         // happy path where the resolver matches just one
         if (matches && matches.length === 1) {
             return matches[0];
         }
-        // handle the case where the resolver didn't find any matches for the given database and show valid options.
+        // handle the case where the resolver didn't find any matches for the given database.
         if (!matches) {
             const attachments = await this.allPostgresAttachments(appId);
             if (attachments.length === 0) {
                 throw new Error(`${color_1.color.app(appId)} has no databases`);
             }
-            else {
+            // attempt to find a match using config var names
+            matches = await this.getAttachmentsViaConfigVarNames(attachments, appId, attachmentId);
+            if (matches.length === 0) {
+                const databaseName = attachmentId.endsWith('_URL') ? attachmentId.slice(0, -4) : attachmentId;
                 const validOptions = attachments.map(attachment => (0, config_vars_1.getConfigVarName)(attachment.config_vars));
-                throw new Error(`Unknown database: ${attachmentId}. Valid options are: ${validOptions.join(', ')}`);
+                const validOptionsString = validOptions.map(option => option.endsWith('_URL') ? option.slice(0, -4) : option).join(', ');
+                throw new Error(`Unknown database: ${databaseName}. Valid options are: ${validOptionsString}`);
             }
         }
         // handle the case where the resolver found multiple matches for the given database.
@@ -65,6 +132,36 @@ class DatabaseResolver {
         }
         throw error;
     }
+    /**
+     * Returns the connection details for a database attachment according to the app config vars.
+     *
+     * @param attachment - The attachment to get the connection details for
+     * @param config - The record of app config vars with their values
+     * @returns Connection details with attachment information
+     */
+    getConnectionDetails(attachment, config = {}) {
+        const connStringVar = (0, config_vars_1.getConfigVarNameFromAttachment)(attachment, config);
+        // build the default payload for non-bastion dbs
+        pgDebug(`Using "${connStringVar}" to connect to your database…`);
+        const conn = DatabaseResolver.parsePostgresConnectionString(config[connStringVar]);
+        const payload = {
+            attachment,
+            database: conn.database,
+            host: conn.host,
+            password: conn.password,
+            pathname: conn.pathname,
+            port: conn.port,
+            url: conn.url,
+            user: conn.user,
+        };
+        // This handles injection of bastion creds into the payload if they exist as config vars (Shield-tier databases).
+        const baseName = connStringVar.slice(0, -4);
+        const bastion = (0, bastion_1.getBastionConfig)(config, baseName);
+        if (bastion) {
+            Object.assign(payload, bastion);
+        }
+        return payload;
+    }
     /**
      * Returns the connection details for a database attachment resolved through the identifiers passed as
      * arguments: appId, attachmentId and namespace (credential).
@@ -86,25 +183,14 @@ class DatabaseResolver {
         return database;
     }
     /**
-     * Parses a PostgreSQL connection string (or a local database name) into a ConnectionDetails object.
+     * Helper function that attempts to find all Heroku Postgres attachments on a given app.
      *
-     * @param connStringOrDbName - PostgreSQL connection string or local database name
-     * @returns Connection details object with parsed connection information
+     * @param app - The name of the app to get the attachments for
+     * @returns Promise resolving to an array of all Heroku Postgres attachments on the app
      */
-    // eslint-disable-next-line perfectionist/sort-classes
-    static parsePostgresConnectionString(connStringOrDbName) {
-        const dbPath = /:\/\//.test(connStringOrDbName) ? connStringOrDbName : `postgres:///${connStringOrDbName}`;
-        const url = new URL(dbPath);
-        const { hostname, password, pathname, port, username } = url;
-        return {
-            database: pathname.slice(1), // remove the leading slash from the pathname
-            host: hostname,
-            password,
-            pathname,
-            port: port || process.env.PGPORT || (hostname && '5432'),
-            url: dbPath,
-            user: username,
-        };
+    async allLegacyDatabaseAttachments(app) {
+        const { body: attachments } = await this.heroku.get(`/apps/${app}/addon-attachments`, { headers: this.attachmentHeaders });
+        return attachments.filter(a => (0, helpers_1.isLegacyDatabase)(a.addon));
     }
     /**
      * Fetches all Heroku PostgreSQL add-on attachments for a given app.
@@ -117,45 +203,45 @@ class DatabaseResolver {
      * @returns Promise resolving to array of PostgreSQL add-on attachments
      */
     async allPostgresAttachments(appId) {
-        const addonService = process.env.HEROKU_POSTGRESQL_ADDON_NAME || 'heroku-postgresql';
         const { body: attachments } = await this.heroku.get(`/apps/${appId}/addon-attachments`, {
             headers: this.attachmentHeaders,
         });
-        return attachments.filter(a => a.addon.plan.name.split(':', 2)[0] === addonService);
+        return attachments.filter(a => a.addon.plan.name.split(':', 2)[0] === (0, helpers_1.getAddonService)());
     }
     /**
-     * Returns the connection details for a database attachment according to the app config vars.
+     * Helper function that groups Heroku Postgres attachments by addon.
      *
-     * @param attachment - The attachment to get the connection details for
-     * @param config - The record of app config vars with their values
-     * @returns Connection details with attachment information
+     * @param attachments - The attachments to group by addon
+     * @returns A record of addon IDs with their attachment names
      */
-    // eslint-disable-next-line perfectionist/sort-classes
-    getConnectionDetails(attachment, config = {}) {
-        const connStringVar = (0, config_vars_1.getConfigVarNameFromAttachment)(attachment, config);
-        // build the default payload for non-bastion dbs
-        pgDebug(`Using "${connStringVar}" to connect to your database…`);
-        const conn = DatabaseResolver.parsePostgresConnectionString(config[connStringVar]);
-        const payload = {
-            attachment,
-            database: conn.database,
-            host: conn.host,
-            password: conn.password,
-            pathname: conn.pathname,
-            port: conn.port,
-            url: conn.url,
-            user: conn.user,
-        };
-        // This handles injection of bastion creds into the payload if they exist as config vars (Shield-tier databases).
-        const baseName = connStringVar.slice(0, -4);
-        const bastion = (0, bastion_1.getBastionConfig)(config, baseName);
-        if (bastion) {
-            Object.assign(payload, bastion);
+    getAttachmentNamesByAddon(attachments) {
+        const addons = {};
+        for (const attachment of attachments) {
+            addons[attachment.addon.id] = [...(addons[attachment.addon.id] || []), attachment.name];
         }
-        return payload;
+        return addons;
+    }
+    /**
+     * Helper function that attempts to find a single addon attachment matching the given database identifier
+     * by comparing the identifier to the config var names of all attachments on the app
+     * (attachment name, id, or config var name).
+     *
+     * This is used internally by the `getAttachment` function to handle the lookup of addon attachments.
+     * It returns either an array with a single match or an empty array if no matches are found.
+     *
+     * @param attachments - Array of attachments for the specified app ID
+     * @param appId - The ID of the app to search for attachments
+     * @param attachmentId - The database identifier to match
+     * @returns Promise resolving to either a single match or no matches
+     */
+    async getAttachmentsViaConfigVarNames(attachments, appId, attachmentId) {
+        const targetConfigVarName = attachmentId.endsWith('_URL') ? attachmentId : `${attachmentId}_URL`;
+        const config = await this.getConfigFn(this.heroku, appId);
+        return attachments.filter(attachment => config[targetConfigVarName] && config[targetConfigVarName] === config[(0, config_vars_1.getConfigVarName)(attachment.config_vars)]);
     }
     /**
      * Helper function that attempts to find a single addon attachment matching the given database identifier
+     * via the add-on attachments resolver
      * (attachment name, id, or config var name).
      *
      * This is used internally by the `getAttachment` function to handle the lookup of addon attachments.
@@ -168,9 +254,9 @@ class DatabaseResolver {
      * @param namespace - Optional namespace/credential filter
      * @returns Promise resolving to either a single match, multiple matches with error, or no matches with error
      */
-    async matchesHelper(appId, attachmentId, namespace) {
+    async getAttachmentsViaResolver(appId, attachmentId, namespace) {
         (0, debug_1.default)(`fetching ${attachmentId} on ${appId}`);
-        const addonService = process.env.HEROKU_POSTGRESQL_ADDON_NAME || 'heroku-postgresql';
+        const addonService = (0, helpers_1.getAddonService)();
         (0, debug_1.default)(`addon service: ${addonService}`);
         try {
             const attached = await this.addonAttachmentResolver.resolve(appId, attachmentId, { addonService, namespace });

package/dist/utils/pg/psql.d.ts

@@ -43,6 +43,16 @@ export default class PsqlService {
     private readonly spawnFn;
     private readonly tunnelFn;
     constructor(connectionDetails: ConnectionDetails, getPsqlConfigsFn?: typeof getPsqlConfigs, spawnFn?: typeof spawn, tunnelFn?: typeof sshTunnel);
+    /**
+     * Executes a file containing SQL commands using the instance's database connection details.
+     * It uses the `getPsqlConfigs` function to get the configuration for the database and the tunnel,
+     * and then calls the `runWithTunnel` function to execute the file.
+     *
+     * @param file - The path to the SQL file to execute
+     * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
+     * @returns Promise that resolves to the query result as a string
+     */
+    execFile(file: string, psqlCmdArgs?: string[]): Promise<string>;
     /**
      * Executes a PostgreSQL query using the instance's database connection details.
      * It uses the `getPsqlConfigs` function to get the configuration for the database and the tunnel,
@@ -53,6 +63,29 @@ export default class PsqlService {
      * @returns Promise that resolves to the query result as a string
      */
     execQuery(query: string, psqlCmdArgs?: string[]): Promise<string>;
+    /**
+     * Fetches the PostgreSQL version from the database by executing the `SHOW server_version` query.
+     *
+     * @returns Promise that resolves to the PostgreSQL version as a string (or undefined).
+     */
+    fetchVersion(): Promise<string | undefined>;
+    /**
+     * Executes a PostgreSQL interactive session using the instance's database connection details.
+     * It uses the `getPsqlConfigs` function to get the configuration for the database and the tunnel,
+     * and then calls the `runWithTunnel` function to execute the query.
+     *
+     * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
+     * @returns Promise that resolves to the query result as a string
+     */
+    interactiveSession(psqlCmdArgs?: string[]): Promise<string>;
+    /**
+     * Runs the psql command with tunnel support.
+     *
+     * @param tunnelConfig - The tunnel configuration object
+     * @param options - The options for spawning the psql process
+     * @returns Promise that resolves to the query result as a string
+     */
+    runWithTunnel(tunnelConfig: TunnelConfig, options: Parameters<typeof this.spawnPsql>[0]): Promise<string>;
     /**
      * Consumes a stream and returns its content as a string.
      *
@@ -72,22 +105,32 @@ export default class PsqlService {
      */
     private kill;
     /**
-     * Creates the options for spawning the psql process.
+     * Creates the options for spawning the psql process for a SQL file execution.
      *
-     * @param query - The SQL query to execute
+     * @param file - The path to the SQL file to execute
      * @param dbEnv - The database environment variables
      * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
      * @returns Object containing child process options, database environment, and psql arguments
      */
-    private psqlQueryOptions;
+    private psqlFileOptions;
     /**
-     * Runs the psql command with tunnel support.
+     * Creates the options for spawning the psql process for an interactive psql session.
      *
-     * @param tunnelConfig - The tunnel configuration object
-     * @param options - The options for spawning the psql process
-     * @returns Promise that resolves to the query result as a string
+     * @param prompt - The prompt to use for the interactive psql session
+     * @param dbEnv - The database environment variables
+     * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
+     * @returns Object containing child process options, database environment, and psql arguments
      */
-    runWithTunnel(tunnelConfig: TunnelConfig, options: Parameters<typeof this.spawnPsql>[0]): Promise<string>;
+    private psqlInteractiveOptions;
+    /**
+     * Creates the options for spawning the psql process for a single query execution.
+     *
+     * @param query - The SQL query to execute
+     * @param dbEnv - The database environment variables
+     * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
+     * @returns Object containing child process options, database environment, and psql arguments
+     */
+    private psqlQueryOptions;
     /**
      * Spawns the psql process with the given options.
      *

package/dist/utils/pg/psql.js

@@ -2,9 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Tunnel = void 0;
 const tslib_1 = require("tslib");
+const core_1 = require("@oclif/core");
 const debug_1 = tslib_1.__importDefault(require("debug"));
 const node_child_process_1 = require("node:child_process");
 const node_events_1 = require("node:events");
+const node_fs_1 = tslib_1.__importDefault(require("node:fs"));
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
 const node_stream_1 = require("node:stream");
 const promises_1 = require("node:stream/promises");
 const bastion_1 = require("./bastion");
@@ -82,6 +85,20 @@ class PsqlService {
         this.spawnFn = spawnFn;
         this.tunnelFn = tunnelFn;
     }
+    /**
+     * Executes a file containing SQL commands using the instance's database connection details.
+     * It uses the `getPsqlConfigs` function to get the configuration for the database and the tunnel,
+     * and then calls the `runWithTunnel` function to execute the file.
+     *
+     * @param file - The path to the SQL file to execute
+     * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
+     * @returns Promise that resolves to the query result as a string
+     */
+    async execFile(file, psqlCmdArgs = []) {
+        const configs = this.getPsqlConfigsFn(this.connectionDetails);
+        const options = this.psqlFileOptions(file, configs.dbEnv, psqlCmdArgs);
+        return this.runWithTunnel(configs.dbTunnelConfig, options);
+    }
     /**
      * Executes a PostgreSQL query using the instance's database connection details.
      * It uses the `getPsqlConfigs` function to get the configuration for the database and the tunnel,
@@ -96,6 +113,72 @@ class PsqlService {
         const options = this.psqlQueryOptions(query, configs.dbEnv, psqlCmdArgs);
         return this.runWithTunnel(configs.dbTunnelConfig, options);
     }
+    /**
+     * Fetches the PostgreSQL version from the database by executing the `SHOW server_version` query.
+     *
+     * @returns Promise that resolves to the PostgreSQL version as a string (or undefined).
+     */
+    async fetchVersion() {
+        var _a;
+        const output = await this.execQuery('SHOW server_version', ['-X', '-q']);
+        return (_a = output.match(/\d+\.\d+/)) === null || _a === void 0 ? void 0 : _a[0];
+    }
+    /**
+     * Executes a PostgreSQL interactive session using the instance's database connection details.
+     * It uses the `getPsqlConfigs` function to get the configuration for the database and the tunnel,
+     * and then calls the `runWithTunnel` function to execute the query.
+     *
+     * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
+     * @returns Promise that resolves to the query result as a string
+     */
+    async interactiveSession(psqlCmdArgs = []) {
+        const attachmentName = this.connectionDetails.attachment.name;
+        const prompt = `${this.connectionDetails.attachment.app.name}::${attachmentName}%R%# `;
+        const configs = this.getPsqlConfigsFn(this.connectionDetails);
+        configs.dbEnv.PGAPPNAME = 'psql interactive'; // default was 'psql non-interactive`
+        const options = this.psqlInteractiveOptions(prompt, configs.dbEnv, psqlCmdArgs);
+        return this.runWithTunnel(configs.dbTunnelConfig, options);
+    }
+    /**
+     * Runs the psql command with tunnel support.
+     *
+     * @param tunnelConfig - The tunnel configuration object
+     * @param options - The options for spawning the psql process
+     * @returns Promise that resolves to the query result as a string
+     */
+    async runWithTunnel(tunnelConfig, options) {
+        const tunnel = await Tunnel.connect(this.connectionDetails, tunnelConfig, this.tunnelFn);
+        pgDebug('after create tunnel');
+        const psql = this.spawnPsql(options);
+        // Note: In non-interactive mode, psql.stdout is available for capturing output.
+        // In interactive mode, stdio: 'inherit' would make psql.stdout null.
+        // Return a string for consistency but ideally we should return the child process from this function
+        // and let the caller decide what to do with stdin/stdout/stderr
+        const stdoutPromise = psql.stdout ? this.consumeStream(psql.stdout) : Promise.resolve('');
+        const cleanupSignalTraps = this.trapAndForwardSignalsToChildProcess(psql);
+        try {
+            pgDebug('waiting for psql or tunnel to exit');
+            // wait for either psql or tunnel to exit;
+            // the important bit is that we ensure both processes are
+            // always cleaned up in the `finally` block below
+            await Promise.race([
+                this.waitForPSQLExit(psql),
+                tunnel.waitForClose(),
+            ]);
+        }
+        catch (error) {
+            pgDebug('wait for psql or tunnel error', error);
+            throw error;
+        }
+        finally {
+            pgDebug('begin tunnel cleanup');
+            cleanupSignalTraps();
+            tunnel.close();
+            this.kill(psql, 'SIGKILL');
+            pgDebug('end tunnel cleanup');
+        }
+        return stdoutPromise;
+    }
     /**
      * Consumes a stream and returns its content as a string.
      *
@@ -137,19 +220,19 @@ class PsqlService {
         }
     }
     /**
-     * Creates the options for spawning the psql process.
+     * Creates the options for spawning the psql process for a SQL file execution.
      *
-     * @param query - The SQL query to execute
+     * @param file - The path to the SQL file to execute
      * @param dbEnv - The database environment variables
      * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
      * @returns Object containing child process options, database environment, and psql arguments
      */
-    psqlQueryOptions(query, dbEnv, psqlCmdArgs = []) {
-        pgDebug('Running query: %s', query.trim());
-        const psqlArgs = ['-c', query, '--set', 'sslmode=require', ...psqlCmdArgs];
+    psqlFileOptions(file, dbEnv, psqlCmdArgs = []) {
+        pgDebug('Running SQL file: %s', file.trim());
         const childProcessOptions = {
             stdio: ['ignore', 'pipe', 'inherit'],
         };
+        const psqlArgs = ['-f', file, '--set', 'sslmode=require', ...psqlCmdArgs];
         return {
             childProcessOptions,
             dbEnv,
@@ -157,45 +240,59 @@ class PsqlService {
         };
     }
     /**
-     * Runs the psql command with tunnel support.
+     * Creates the options for spawning the psql process for an interactive psql session.
      *
-     * @param tunnelConfig - The tunnel configuration object
-     * @param options - The options for spawning the psql process
-     * @returns Promise that resolves to the query result as a string
+     * @param prompt - The prompt to use for the interactive psql session
+     * @param dbEnv - The database environment variables
+     * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
+     * @returns Object containing child process options, database environment, and psql arguments
      */
-    // eslint-disable-next-line perfectionist/sort-classes
-    async runWithTunnel(tunnelConfig, options) {
-        const tunnel = await Tunnel.connect(this.connectionDetails, tunnelConfig, this.tunnelFn);
-        pgDebug('after create tunnel');
-        const psql = this.spawnPsql(options);
-        // Note: In non-interactive mode, psql.stdout is available for capturing output.
-        // In interactive mode, stdio: 'inherit' would make psql.stdout null.
-        // Return a string for consistency but ideally we should return the child process from this function
-        // and let the caller decide what to do with stdin/stdout/stderr
-        const stdoutPromise = psql.stdout ? this.consumeStream(psql.stdout) : Promise.resolve('');
-        const cleanupSignalTraps = this.trapAndForwardSignalsToChildProcess(psql);
-        try {
-            pgDebug('waiting for psql or tunnel to exit');
-            // wait for either psql or tunnel to exit;
-            // the important bit is that we ensure both processes are
-            // always cleaned up in the `finally` block below
-            await Promise.race([
-                this.waitForPSQLExit(psql),
-                tunnel.waitForClose(),
-            ]);
-        }
-        catch (error) {
-            pgDebug('wait for psql or tunnel error', error);
-            throw error;
-        }
-        finally {
-            pgDebug('begin tunnel cleanup');
-            cleanupSignalTraps();
-            tunnel.close();
-            this.kill(psql, 'SIGKILL');
-            pgDebug('end tunnel cleanup');
+    psqlInteractiveOptions(prompt, dbEnv, psqlCmdArgs = []) {
+        let psqlArgs = ['--set', `PROMPT1=${prompt}`, '--set', `PROMPT2=${prompt}`];
+        const psqlHistoryPath = process.env.HEROKU_PSQL_HISTORY;
+        if (psqlHistoryPath) {
+            if (node_fs_1.default.existsSync(psqlHistoryPath) && node_fs_1.default.statSync(psqlHistoryPath).isDirectory()) {
+                const appLogFile = `${psqlHistoryPath}/${prompt.split(':')[0]}`;
+                pgDebug('Logging psql history to %s', appLogFile);
+                psqlArgs = [...psqlArgs, '--set', `HISTFILE=${appLogFile}`];
+            }
+            else if (node_fs_1.default.existsSync(node_path_1.default.dirname(psqlHistoryPath))) {
+                pgDebug('Logging psql history to %s', psqlHistoryPath);
+                psqlArgs = [...psqlArgs, '--set', `HISTFILE=${psqlHistoryPath}`];
+            }
+            else {
+                core_1.ux.warn(`HEROKU_PSQL_HISTORY is set but is not a valid path (${psqlHistoryPath})\n`);
+            }
         }
-        return stdoutPromise;
+        psqlArgs = [...psqlArgs, '--set', 'sslmode=require', ...psqlCmdArgs];
+        const childProcessOptions = {
+            stdio: ['inherit', 'inherit', 'inherit'],
+        };
+        return {
+            childProcessOptions,
+            dbEnv,
+            psqlArgs,
+        };
+    }
+    /**
+     * Creates the options for spawning the psql process for a single query execution.
+     *
+     * @param query - The SQL query to execute
+     * @param dbEnv - The database environment variables
+     * @param psqlCmdArgs - Additional command-line arguments for psql (default: [])
+     * @returns Object containing child process options, database environment, and psql arguments
+     */
+    psqlQueryOptions(query, dbEnv, psqlCmdArgs = []) {
+        pgDebug('Running query: %s', query.trim());
+        const psqlArgs = ['-c', query, '--set', 'sslmode=require', ...psqlCmdArgs];
+        const childProcessOptions = {
+            stdio: ['ignore', 'pipe', 'inherit'],
+        };
+        return {
+            childProcessOptions,
+            dbEnv,
+            psqlArgs,
+        };
     }
     /**
      * Spawns the psql process with the given options.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heroku/heroku-cli-util",
-  "version": "9.1.3",
+  "version": "9.2.0",
   "description": "Set of helpful CLI utilities",
   "author": "Heroku",
   "license": "ISC",
@@ -15,6 +15,7 @@
     "@types/chai": "^4.3.13",
     "@types/chai-as-promised": "^8.0.2",
     "@types/debug": "^4.1.12",
+    "@types/tmp": "^0.2.6",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.15.3",
     "@types/sinon": "^17.0.4",
@@ -33,6 +34,7 @@
     "sinon-chai": "^3.7.0",
     "stdout-stderr": "^0.1.13",
     "strip-ansi": "^6",
+    "tmp": "^0.2.5",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
     "tsheredoc": "^1.0.1",