feat(db): insta db url + insta db connect — first-class connection-string access

Merged
TO
3mo ago
+259-8

Why

The postgres DB is publicly dialable, but provider-minted credentials are deliberately absent from the general insta secrets bundle — so no CLI surface yielded the DSN and users/agents concluded the database couldn't be used directly. (MCP is names-only by design and points at the CLI, which had nothing to point at.)

What

  • insta db url [--branch --group --json] — prints the bare DSN on stdout (pipe-friendly: psql "$(insta db url)"). Wraps GET /projects/:id/services/:serviceId/credentials (gated secrets.read; 202 approval → exit 2 as everywhere).
  • insta db connect [--branch --group] — interactive psql on the service; exits with psql's own exit code; missing psql → guidance instead of raw ENOENT.
  • insta services add postgres now prints one connect line right after create, so the path is discoverable at the moment it matters.

Verified

  • npm run typecheck + full vitest suite green (489), incl. new test/db-url.test.ts (resolution, --group, multi-service error, provisioning error, 202 approval, psql spawn/ENOENT).
  • Live on staging: scratch project → services add postgres db (hint prints) → db url returned the DSN → psql "$(insta db url)" -c 'select …' connected to the real instance (PG 16.15, incl. wake-on-connect) → piped db connect ran a query, exit 0 → project deleted.

Skill docs mirrored in InsForge/insta-skills PR (cli-reference + SKILL.md + setup/branching refs), per the AGENTS.md rule.

Note: insta-oss parity for /services/:id/credentials not checked here — tracked with the existing oss contract-parity drift.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DkeyZ12Y9PW2TDNQW4pQCo

Summary by cubic

Adds first-class Postgres connection-string access and safe interactive connects. Previously the CLI exposed no DSN; now insta db url prints the DSN and insta db connect opens psql without leaking credentials.

  • Details
    • db url: prints the bare DSN; supports --json, --branch, and --group; resolves the sole Postgres service or requires --group; errors when DATABASE_URL is not provisioned; gated by secrets.read (202 approval → exit 2).
    • db connect: runs psql via libpq PG* env only (keeps the DSN out of argv), strips ambient PG* vars case-insensitively (Windows-safe) to prevent redirection, inherits stdio, returns psql’s exit code, maps signal deaths to 128+signo, and guides when psql is missing; notes wake-on-connect delay.
    • services add postgres prints a runnable connect hint after create, including --group <name> and --branch when applicable; README clarifies user-defined vs provider-minted secrets and adds the insta db commands row.