postgresai 0.14.0-beta.1 → 0.14.0-beta.3

package/README.md

@@ -15,6 +15,8 @@ Or install the latest beta release explicitly:
 npm install -g postgresai@beta
 ```
 
+Note: in this repository, `cli/package.json` uses a placeholder version (`0.0.0-dev.0`). The real published version is set by the git tag in CI when publishing to npm.
+
 ### From Homebrew (macOS)
 
 ```bash
@@ -27,11 +29,24 @@ brew install postgresai
 
 ## Usage
 
-The CLI provides three command aliases:
+The `postgresai` package provides two command aliases (prefer `postgresai`):
 ```bash
 postgres-ai --help
 postgresai --help
-pgai --help  # short alias
+```
+
+You can also run it without installing via `npx`:
+
+```bash
+npx postgresai --help
+```
+
+### Optional shorthand: `pgai`
+
+If you want `npx pgai ...` as a shorthand for `npx postgresai ...`, install the separate `pgai` wrapper package:
+
+```bash
+npx pgai --help
 ```
 
 ## init (create monitoring user in Postgres)
@@ -98,7 +113,7 @@ npx postgresai init postgresql://admin@host:5432/dbname --reset-password --passw
 
 Authenticate via browser to obtain API key:
 ```bash
-pgai auth
+postgresai auth
 ```
 
 This will:
@@ -180,7 +195,7 @@ postgres-ai mon shell <service>                # Open shell to monitoring servic
 ### MCP server (`mcp` group)
 
 ```bash
-pgai mcp start                 # Start MCP stdio server exposing tools
+postgresai mcp start                 # Start MCP stdio server exposing tools
 ```
 
 Cursor configuration example (Settings → MCP):
@@ -189,7 +204,7 @@ Cursor configuration example (Settings → MCP):
 {
   "mcpServers": {
     "PostgresAI": {
-      "command": "pgai",
+      "command": "postgresai",
       "args": ["mcp", "start"],
       "env": {
         "PGAI_API_BASE_URL": "https://postgres.ai/api/general/"
@@ -200,16 +215,16 @@ Cursor configuration example (Settings → MCP):
 ```
 
 Tools exposed:
-- list_issues: returns the same JSON as `pgai issues list`.
+- list_issues: returns the same JSON as `postgresai issues list`.
 - view_issue: view a single issue with its comments (args: { issue_id, debug? })
 - post_issue_comment: post a comment (args: { issue_id, content, parent_comment_id?, debug? })
 
 ### Issues management (`issues` group)
 
 ```bash
-pgai issues list                                  # List issues (shows: id, title, status, created_at)
-pgai issues view <issueId>                        # View issue details and comments
-pgai issues post_comment <issueId> <content>      # Post a comment to an issue
+postgresai issues list                                  # List issues (shows: id, title, status, created_at)
+postgresai issues view <issueId>                        # View issue details and comments
+postgresai issues post_comment <issueId> <content>      # Post a comment to an issue
 # Options:
 #   --parent <uuid>  Parent comment ID (for replies)
 #   --debug          Enable debug output
@@ -223,13 +238,13 @@ By default, issues commands print human-friendly YAML when writing to a terminal
 - Use `--json` to force JSON output:
 
 ```bash
-pgai issues list --json | jq '.[] | {id, title}'
+postgresai issues list --json | jq '.[] | {id, title}'
 ```
 
 - Rely on auto-detection: when stdout is not a TTY (e.g., piped or redirected), output is JSON automatically:
 
 ```bash
-pgai issues view <issueId> > issue.json
+postgresai issues view <issueId> > issue.json
 ```
 
 #### Grafana management
@@ -293,7 +308,7 @@ Linux/macOS (bash/zsh):
 ```bash
 export PGAI_API_BASE_URL=https://v2.postgres.ai/api/general/
 export PGAI_UI_BASE_URL=https://console-dev.postgres.ai
-pgai auth --debug
+postgresai auth --debug
 ```
 
 Windows PowerShell:
@@ -301,13 +316,13 @@ Windows PowerShell:
 ```powershell
 $env:PGAI_API_BASE_URL = "https://v2.postgres.ai/api/general/"
 $env:PGAI_UI_BASE_URL = "https://console-dev.postgres.ai"
-pgai auth --debug
+postgresai auth --debug
 ```
 
 Via CLI options (overrides env):
 
 ```bash
-pgai auth --debug \
+postgresai auth --debug \
   --api-base-url https://v2.postgres.ai/api/general/ \
   --ui-base-url https://console-dev.postgres.ai
 ```

package/bin/postgres-ai.ts

@@ -16,7 +16,7 @@ import { Client } from "pg";
 import { startMcpServer } from "../lib/mcp-server";
 import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue } from "../lib/issues";
 import { resolveBaseUrls } from "../lib/util";
-import { applyInitPlan, buildInitPlan, resolveAdminConnection, resolveMonitoringPassword, verifyInitSetup } from "../lib/init";
+import { applyInitPlan, buildInitPlan, DEFAULT_MONITORING_USER, redactPasswordsInSql, resolveAdminConnection, resolveMonitoringPassword, verifyInitSetup } from "../lib/init";
 
 const execPromise = promisify(exec);
 const execFilePromise = promisify(execFile);
@@ -127,13 +127,12 @@ program
   .option("-U, --username <username>", "PostgreSQL user (psql-like)")
   .option("-d, --dbname <dbname>", "PostgreSQL database name (psql-like)")
   .option("--admin-password <password>", "Admin connection password (otherwise uses PGPASSWORD if set)")
-  .option("--monitoring-user <name>", "Monitoring role name to create/update", "postgres_ai_mon")
+  .option("--monitoring-user <name>", "Monitoring role name to create/update", DEFAULT_MONITORING_USER)
   .option("--password <password>", "Monitoring role password (overrides PGAI_MON_PASSWORD)")
   .option("--skip-optional-permissions", "Skip optional permissions (RDS/self-managed extras)", false)
   .option("--verify", "Verify that monitoring role/permissions are in place (no changes)", false)
   .option("--reset-password", "Reset monitoring role password only (no other changes)", false)
   .option("--print-sql", "Print SQL plan and exit (no changes applied)", false)
-  .option("--show-secrets", "When printing SQL, do not redact secrets (DANGEROUS)", false)
   .option("--print-password", "Print generated monitoring password (DANGEROUS in CI logs)", false)
   .addHelpText(
     "after",
@@ -152,6 +151,11 @@ program
       "  If auto-generated, it is printed only on TTY by default.",
       "  To print it in non-interactive mode: --print-password",
       "",
+      "Environment variables (libpq standard):",
+      "  PGHOST, PGPORT, PGUSER, PGDATABASE  — connection defaults",
+      "  PGPASSWORD                          — admin password",
+      "  PGAI_MON_PASSWORD                   — monitoring password",
+      "",
       "Inspect SQL without applying changes:",
       "  postgresai init <conn> --print-sql",
       "",
@@ -162,7 +166,7 @@ program
       "  postgresai init <conn> --reset-password --password '...'",
       "",
       "Offline SQL plan (no DB connection):",
-      "  postgresai init --print-sql -d dbname --password '...' --show-secrets",
+      "  postgresai init --print-sql",
     ].join("\n")
   )
   .action(async (conn: string | undefined, opts: {
@@ -178,7 +182,6 @@ program
     verify?: boolean;
     resetPassword?: boolean;
     printSql?: boolean;
-    showSecrets?: boolean;
     printPassword?: boolean;
   }, cmd: Command) => {
     if (opts.verify && opts.resetPassword) {
@@ -193,30 +196,25 @@ program
     }
 
     const shouldPrintSql = !!opts.printSql;
-    const shouldRedactSecrets = !opts.showSecrets;
-    const redactPasswords = (sql: string): string => {
-      if (!shouldRedactSecrets) return sql;
-      // Replace PASSWORD '<literal>' (handles doubled quotes inside).
-      return sql.replace(/password\s+'(?:''|[^'])*'/gi, "password '<redacted>'");
-    };
+    const redactPasswords = (sql: string): string => redactPasswordsInSql(sql);
 
     // Offline mode: allow printing SQL without providing/using an admin connection.
-    // Useful for audits/reviews; caller can provide -d/PGDATABASE and an explicit monitoring password.
+    // Useful for audits/reviews; caller can provide -d/PGDATABASE.
     if (!conn && !opts.dbUrl && !opts.host && !opts.port && !opts.username && !opts.adminPassword) {
       if (shouldPrintSql) {
         const database = (opts.dbname ?? process.env.PGDATABASE ?? "postgres").trim();
         const includeOptionalPermissions = !opts.skipOptionalPermissions;
 
-        // Use explicit password/env if provided; otherwise use a placeholder (will be redacted unless --show-secrets).
+        // Use explicit password/env if provided; otherwise use a placeholder.
+        // Printed SQL always redacts secrets.
         const monPassword =
-          (opts.password ?? process.env.PGAI_MON_PASSWORD ?? "CHANGE_ME").toString();
+          (opts.password ?? process.env.PGAI_MON_PASSWORD ?? "<redacted>").toString();
 
         const plan = await buildInitPlan({
           database,
           monitoringUser: opts.monitoringUser,
           monitoringPassword: monPassword,
           includeOptionalPermissions,
-          roleExists: undefined,
         });
 
         console.log("\n--- SQL plan (offline; not connected) ---");
@@ -228,9 +226,7 @@ program
           console.log(redactPasswords(step.sql));
         }
         console.log("\n--- end SQL plan ---\n");
-        if (shouldRedactSecrets) {
-          console.log("Note: passwords are redacted in the printed SQL (use --show-secrets to print them).");
-        }
+        console.log("Note: passwords are redacted in the printed SQL output.");
         return;
       }
     }
@@ -250,7 +246,7 @@ program
       });
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
-      console.error(`✗ ${msg}`);
+      console.error(`Error: init: ${msg}`);
       // When connection details are missing, show full init help (options + examples).
       if (typeof msg === "string" && msg.startsWith("Connection is required.")) {
         console.error("");
@@ -267,16 +263,11 @@ program
     console.log(`Optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
 
     // Use native pg client instead of requiring psql to be installed
-    const client = new Client(adminConn.clientConfig);
-
+    let client: Client | undefined;
     try {
+      client = new Client(adminConn.clientConfig);
       await client.connect();
 
-      const roleRes = await client.query("select 1 from pg_catalog.pg_roles where rolname = $1", [
-        opts.monitoringUser,
-      ]);
-      const roleExists = (roleRes.rowCount ?? 0) > 0;
-
       const dbRes = await client.query("select current_database() as db");
       const database = dbRes.rows?.[0]?.db;
       if (typeof database !== "string" || !database) {
@@ -319,10 +310,13 @@ program
         if (resolved.generated) {
           const canPrint = process.stdout.isTTY || !!opts.printPassword;
           if (canPrint) {
-            console.log("");
-            console.log(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
-            console.log(`PGAI_MON_PASSWORD=${monPassword}`);
-            console.log("");
+            // Print secrets to stderr to reduce the chance they end up in piped stdout logs.
+            const shellSafe = monPassword.replace(/'/g, "'\\''");
+            console.error("");
+            console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
+            // Quote for shell copy/paste safety.
+            console.error(`PGAI_MON_PASSWORD='${shellSafe}'`);
+            console.error("");
             console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
           } else {
             console.error(
@@ -352,7 +346,6 @@ program
         monitoringUser: opts.monitoringUser,
         monitoringPassword: monPassword,
         includeOptionalPermissions,
-        roleExists,
       });
 
       const effectivePlan = opts.resetPassword
@@ -366,9 +359,7 @@ program
           console.log(redactPasswords(step.sql));
         }
         console.log("\n--- end SQL plan ---\n");
-        if (shouldRedactSecrets) {
-          console.log("Note: passwords are redacted in the printed SQL (use --show-secrets to print them).");
-        }
+              console.log("Note: passwords are redacted in the printed SQL output.");
         return;
       }
 
@@ -396,57 +387,54 @@ program
       if (!message || message === "[object Object]") {
         message = "Unknown error";
       }
-      console.error(`✗ init failed: ${message}`);
+      console.error(`Error: init: ${message}`);
       // If this was a plan step failure, surface the step name explicitly to help users diagnose quickly.
       const stepMatch =
         typeof message === "string" ? message.match(/Failed at step "([^"]+)":/i) : null;
       const failedStep = stepMatch?.[1];
       if (failedStep) {
-        console.error(`Step: ${failedStep}`);
+        console.error(`  Step: ${failedStep}`);
       }
       if (errAny && typeof errAny === "object") {
         if (typeof errAny.code === "string" && errAny.code) {
-          console.error(`Error code: ${errAny.code}`);
+          console.error(`  Code: ${errAny.code}`);
         }
         if (typeof errAny.detail === "string" && errAny.detail) {
-          console.error(`Detail: ${errAny.detail}`);
+          console.error(`  Detail: ${errAny.detail}`);
         }
         if (typeof errAny.hint === "string" && errAny.hint) {
-          console.error(`Hint: ${errAny.hint}`);
+          console.error(`  Hint: ${errAny.hint}`);
         }
       }
       if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
         if (errAny.code === "42501") {
-          console.error("");
-          console.error("Permission error: your admin connection is not allowed to complete the setup.");
           if (failedStep === "01.role") {
-            console.error("What failed: create/update the monitoring role (needs CREATEROLE or superuser).");
+            console.error("  Context: role creation/update requires CREATEROLE or superuser");
           } else if (failedStep === "02.permissions") {
-            console.error("What failed: grant required permissions / create view / set role search_path.");
+            console.error("  Context: grants/view/search_path require sufficient GRANT/DDL privileges");
           }
-          console.error("How to fix:");
-          console.error("- Connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges).");
-          console.error("- On managed Postgres, use the provider's admin/master user.");
-          console.error("Tip: run with --print-sql to review the exact SQL plan.");
-          console.error("");
-          console.error("Hint: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges).");
+          console.error("  Fix: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges)");
+          console.error("  Fix: on managed Postgres, use the provider's admin/master user");
+          console.error("  Tip: run with --print-sql to review the exact SQL plan");
         }
         if (errAny.code === "ECONNREFUSED") {
-          console.error("Hint: check host/port and ensure Postgres is reachable from this machine.");
+          console.error("  Hint: check host/port and ensure Postgres is reachable from this machine");
         }
         if (errAny.code === "ENOTFOUND") {
-          console.error("Hint: DNS resolution failed; double-check the host name.");
+          console.error("  Hint: DNS resolution failed; double-check the host name");
         }
         if (errAny.code === "ETIMEDOUT") {
-          console.error("Hint: connection timed out; check network/firewall rules.");
+          console.error("  Hint: connection timed out; check network/firewall rules");
         }
       }
       process.exitCode = 1;
     } finally {
-      try {
-        await client.end();
-      } catch {
-        // ignore
+      if (client) {
+        try {
+          await client.end();
+        } catch {
+          // ignore
+        }
       }
     }
   });

package/dist/bin/postgres-ai.js

@@ -109,13 +109,12 @@ program
     .option("-U, --username <username>", "PostgreSQL user (psql-like)")
     .option("-d, --dbname <dbname>", "PostgreSQL database name (psql-like)")
     .option("--admin-password <password>", "Admin connection password (otherwise uses PGPASSWORD if set)")
-    .option("--monitoring-user <name>", "Monitoring role name to create/update", "postgres_ai_mon")
+    .option("--monitoring-user <name>", "Monitoring role name to create/update", init_1.DEFAULT_MONITORING_USER)
     .option("--password <password>", "Monitoring role password (overrides PGAI_MON_PASSWORD)")
     .option("--skip-optional-permissions", "Skip optional permissions (RDS/self-managed extras)", false)
     .option("--verify", "Verify that monitoring role/permissions are in place (no changes)", false)
     .option("--reset-password", "Reset monitoring role password only (no other changes)", false)
     .option("--print-sql", "Print SQL plan and exit (no changes applied)", false)
-    .option("--show-secrets", "When printing SQL, do not redact secrets (DANGEROUS)", false)
     .option("--print-password", "Print generated monitoring password (DANGEROUS in CI logs)", false)
     .addHelpText("after", [
     "",
@@ -132,6 +131,11 @@ program
     "  If auto-generated, it is printed only on TTY by default.",
     "  To print it in non-interactive mode: --print-password",
     "",
+    "Environment variables (libpq standard):",
+    "  PGHOST, PGPORT, PGUSER, PGDATABASE  — connection defaults",
+    "  PGPASSWORD                          — admin password",
+    "  PGAI_MON_PASSWORD                   — monitoring password",
+    "",
     "Inspect SQL without applying changes:",
     "  postgresai init <conn> --print-sql",
     "",
@@ -142,7 +146,7 @@ program
     "  postgresai init <conn> --reset-password --password '...'",
     "",
     "Offline SQL plan (no DB connection):",
-    "  postgresai init --print-sql -d dbname --password '...' --show-secrets",
+    "  postgresai init --print-sql",
 ].join("\n"))
     .action(async (conn, opts, cmd) => {
     if (opts.verify && opts.resetPassword) {
@@ -156,27 +160,21 @@ program
         return;
     }
     const shouldPrintSql = !!opts.printSql;
-    const shouldRedactSecrets = !opts.showSecrets;
-    const redactPasswords = (sql) => {
-        if (!shouldRedactSecrets)
-            return sql;
-        // Replace PASSWORD '<literal>' (handles doubled quotes inside).
-        return sql.replace(/password\s+'(?:''|[^'])*'/gi, "password '<redacted>'");
-    };
+    const redactPasswords = (sql) => (0, init_1.redactPasswordsInSql)(sql);
     // Offline mode: allow printing SQL without providing/using an admin connection.
-    // Useful for audits/reviews; caller can provide -d/PGDATABASE and an explicit monitoring password.
+    // Useful for audits/reviews; caller can provide -d/PGDATABASE.
     if (!conn && !opts.dbUrl && !opts.host && !opts.port && !opts.username && !opts.adminPassword) {
         if (shouldPrintSql) {
             const database = (opts.dbname ?? process.env.PGDATABASE ?? "postgres").trim();
             const includeOptionalPermissions = !opts.skipOptionalPermissions;
-            // Use explicit password/env if provided; otherwise use a placeholder (will be redacted unless --show-secrets).
-            const monPassword = (opts.password ?? process.env.PGAI_MON_PASSWORD ?? "CHANGE_ME").toString();
+            // Use explicit password/env if provided; otherwise use a placeholder.
+            // Printed SQL always redacts secrets.
+            const monPassword = (opts.password ?? process.env.PGAI_MON_PASSWORD ?? "<redacted>").toString();
             const plan = await (0, init_1.buildInitPlan)({
                 database,
                 monitoringUser: opts.monitoringUser,
                 monitoringPassword: monPassword,
                 includeOptionalPermissions,
-                roleExists: undefined,
             });
             console.log("\n--- SQL plan (offline; not connected) ---");
             console.log(`-- database: ${database}`);
@@ -187,9 +185,7 @@ program
                 console.log(redactPasswords(step.sql));
             }
             console.log("\n--- end SQL plan ---\n");
-            if (shouldRedactSecrets) {
-                console.log("Note: passwords are redacted in the printed SQL (use --show-secrets to print them).");
-            }
+            console.log("Note: passwords are redacted in the printed SQL output.");
             return;
         }
     }
@@ -209,7 +205,7 @@ program
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
-        console.error(`✗ ${msg}`);
+        console.error(`Error: init: ${msg}`);
         // When connection details are missing, show full init help (options + examples).
         if (typeof msg === "string" && msg.startsWith("Connection is required.")) {
             console.error("");
@@ -223,13 +219,10 @@ program
     console.log(`Monitoring user: ${opts.monitoringUser}`);
     console.log(`Optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
     // Use native pg client instead of requiring psql to be installed
-    const client = new pg_1.Client(adminConn.clientConfig);
+    let client;
     try {
+        client = new pg_1.Client(adminConn.clientConfig);
         await client.connect();
-        const roleRes = await client.query("select 1 from pg_catalog.pg_roles where rolname = $1", [
-            opts.monitoringUser,
-        ]);
-        const roleExists = (roleRes.rowCount ?? 0) > 0;
         const dbRes = await client.query("select current_database() as db");
         const database = dbRes.rows?.[0]?.db;
         if (typeof database !== "string" || !database) {
@@ -273,10 +266,13 @@ program
             if (resolved.generated) {
                 const canPrint = process.stdout.isTTY || !!opts.printPassword;
                 if (canPrint) {
-                    console.log("");
-                    console.log(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
-                    console.log(`PGAI_MON_PASSWORD=${monPassword}`);
-                    console.log("");
+                    // Print secrets to stderr to reduce the chance they end up in piped stdout logs.
+                    const shellSafe = monPassword.replace(/'/g, "'\\''");
+                    console.error("");
+                    console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
+                    // Quote for shell copy/paste safety.
+                    console.error(`PGAI_MON_PASSWORD='${shellSafe}'`);
+                    console.error("");
                     console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
                 }
                 else {
@@ -305,7 +301,6 @@ program
             monitoringUser: opts.monitoringUser,
             monitoringPassword: monPassword,
             includeOptionalPermissions,
-            roleExists,
         });
         const effectivePlan = opts.resetPassword
             ? { ...plan, steps: plan.steps.filter((s) => s.name === "01.role") }
@@ -317,9 +312,7 @@ program
                 console.log(redactPasswords(step.sql));
             }
             console.log("\n--- end SQL plan ---\n");
-            if (shouldRedactSecrets) {
-                console.log("Note: passwords are redacted in the printed SQL (use --show-secrets to print them).");
-            }
+            console.log("Note: passwords are redacted in the printed SQL output.");
             return;
         }
         const { applied, skippedOptional } = await (0, init_1.applyInitPlan)({ client, plan: effectivePlan });
@@ -349,59 +342,56 @@ program
         if (!message || message === "[object Object]") {
             message = "Unknown error";
         }
-        console.error(`✗ init failed: ${message}`);
+        console.error(`Error: init: ${message}`);
         // If this was a plan step failure, surface the step name explicitly to help users diagnose quickly.
         const stepMatch = typeof message === "string" ? message.match(/Failed at step "([^"]+)":/i) : null;
         const failedStep = stepMatch?.[1];
         if (failedStep) {
-            console.error(`Step: ${failedStep}`);
+            console.error(`  Step: ${failedStep}`);
         }
         if (errAny && typeof errAny === "object") {
             if (typeof errAny.code === "string" && errAny.code) {
-                console.error(`Error code: ${errAny.code}`);
+                console.error(`  Code: ${errAny.code}`);
             }
             if (typeof errAny.detail === "string" && errAny.detail) {
-                console.error(`Detail: ${errAny.detail}`);
+                console.error(`  Detail: ${errAny.detail}`);
             }
             if (typeof errAny.hint === "string" && errAny.hint) {
-                console.error(`Hint: ${errAny.hint}`);
+                console.error(`  Hint: ${errAny.hint}`);
             }
         }
         if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
             if (errAny.code === "42501") {
-                console.error("");
-                console.error("Permission error: your admin connection is not allowed to complete the setup.");
                 if (failedStep === "01.role") {
-                    console.error("What failed: create/update the monitoring role (needs CREATEROLE or superuser).");
+                    console.error("  Context: role creation/update requires CREATEROLE or superuser");
                 }
                 else if (failedStep === "02.permissions") {
-                    console.error("What failed: grant required permissions / create view / set role search_path.");
+                    console.error("  Context: grants/view/search_path require sufficient GRANT/DDL privileges");
                 }
-                console.error("How to fix:");
-                console.error("- Connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges).");
-                console.error("- On managed Postgres, use the provider's admin/master user.");
-                console.error("Tip: run with --print-sql to review the exact SQL plan.");
-                console.error("");
-                console.error("Hint: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges).");
+                console.error("  Fix: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges)");
+                console.error("  Fix: on managed Postgres, use the provider's admin/master user");
+                console.error("  Tip: run with --print-sql to review the exact SQL plan");
             }
             if (errAny.code === "ECONNREFUSED") {
-                console.error("Hint: check host/port and ensure Postgres is reachable from this machine.");
+                console.error("  Hint: check host/port and ensure Postgres is reachable from this machine");
             }
             if (errAny.code === "ENOTFOUND") {
-                console.error("Hint: DNS resolution failed; double-check the host name.");
+                console.error("  Hint: DNS resolution failed; double-check the host name");
             }
             if (errAny.code === "ETIMEDOUT") {
-                console.error("Hint: connection timed out; check network/firewall rules.");
+                console.error("  Hint: connection timed out; check network/firewall rules");
             }
         }
         process.exitCode = 1;
     }
     finally {
-        try {
-            await client.end();
-        }
-        catch {
-            // ignore
+        if (client) {
+            try {
+                await client.end();
+            }
+            catch {
+                // ignore
+            }
         }
     }
 });