postgres always-on: no mode reads the current setting back

[Fermionic-Lyu]

SUP2-41. insta postgres always-on on|off could only set the mode. The one field an agent could check afterwards, always_on on the service row, is compute-only and always reads false for postgres. So "did that take effect?" had no answer short of a 15-minute idle experiment.

insta postgres always-on [service] with no mode now reads scaleToZero from GET /database/instance. It prints always-on on, off, or unknown when the provider doesn't report it, and --json prints the whole instance. This is the same show-or-change shape as postgres limits and postgres volume, using the same fetchDbInstance seam, so a service with no manageable instance gets the same soft message. on|off [service] still sets, unchanged; a mode given after the service is still refused.

Tests:

• the argument split (read vs. set, and the reversed-order refusal);
• the scaleToZero → on/off line, which goes red with the inversion flipped;
• the help-surface usage pin, updated to [mode] [service].

Full suite green (1899).

The service-row field is not rewritten: a branch fork copies always_on onto every child row, but a forked postgres instance starts at the provider default, so the copied value would be wrong on forks.

🤖 Generated with Claude Code

---

Summary by cubic

Gives insta postgres always-on a read mode so the current setting can be verified, fixing SUP2-41 where the only checkable field, always_on on the service row, is compute-only and always reads false for postgres.

always-on [service] with no mode now reads scaleToZero from GET /database/instance and prints always-on on, off, or unknown; --json prints the whole instance. This matches the show-or-change shape of postgres limits and postgres volume via the same fetchDbInstance seam. on|off [service] still sets the mode, and a mode given after a service is still refused.

The service-row always_on field is intentionally left alone: branch forks copy it onto child rows, and forked postgres starts at the provider default, so the copied value would be wrong.

^{Written for commit 492f62b. Summary will update on new commits.}

[agent-zhang-beihai]

Reviewed by Wang Miao

This PR lets insta postgres always-on run with no mode. In that case it reads GET /database/instance and prints the current scaleToZero setting. The read path matches the platform contract: mapInstance reports scaleToZero as !always_on, and the CLI inverts it back correctly. It also reuses the existing fetchDbInstance seam the same way dbLimits does. I approve; the one finding below is minor.

skills/insta/cli-reference.md still lists only the setting form of postgres always-on

minor · defect · conventions · src/index.ts:462

AGENTS.md rule 4 says: "Command/flag changes must be mirrored in skills/insta/cli-reference.md". The mode argument is now optional, and running without it prints the current setting. The skills repo still lists only insta --agent postgres always-on on|off [service] (cli-reference.md:105), and I found no open skills PR for this. What the doc says is still accurate, so nothing breaks. But agents won't learn they can check the current setting before changing it. Please add the no-mode form to that row.

Evidence

read-the-code — AGENTS.md (rule 4), src/index.ts:462, src/commands/postgres.ts:9-47, InsForge/instacloud-skills insta/cli-reference.md:105 at ac3618a. I searched that repo's PRs for "always-on" and found no pending change for this. I also checked the platform side: instacloud-platform src/server.ts:3969-3982 and src/adapters/insta-db.ts:268.

[cubic-dev-ai]

1 issue found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/commands/postgres.ts">

<violation number="1" location="src/commands/postgres.ts:35">
P2: The no-instance branch writes its soft message to stdout even with `--json`, so `insta postgres always-on --json` produces invalid JSON for services without a manageable instance. Emit a JSON null/error result and send the explanatory message to stderr.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The no-instance branch writes its soft message to stdout even with --json, so insta postgres always-on --json produces invalid JSON for services without a manageable instance. Emit a JSON null/error result and send the explanatory message to stderr.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/commands/postgres.ts, line 35:

<comment>The no-instance branch writes its soft message to stdout even with `--json`, so `insta postgres always-on --json` produces invalid JSON for services without a manageable instance. Emit a JSON null/error result and send the explanatory message to stderr.</comment>

<file context>
@@ -6,19 +6,40 @@ import { parseVolumeGib, q, resolveSoleService } from './services.js'
+  if (!mode) {
+    const read = await fetchDbInstance(api, p.projectId, suffix)
+    if (read.kind === 'no-instance') {
+      info(`postgres ${service ?? 'default'}: no manageable instance (this service manages its own resources)`)
+      return
+    }
</file context>

Suggested change

	info(`postgres ${service ?? 'default'}: no manageable instance (this service manages its own resources)`)
	if (opts.json) {
	process.stderr.write(`postgres ${service ?? 'default'}: no manageable instance (this service manages its own resources)\n`)
	return printJson(null)
	}
	info(`postgres ${service ?? 'default'}: no manageable instance (this service manages its own resources)`)

[Fermionic-Lyu]

Declining. dbLimits and dbVolume in this file answer the no-instance case the same way: a soft stdout line, exit 0, and no JSON even with --json. The read path reuses that seam on purpose. Changing only this verb would make the three disagree, and changing all three is a separate contract change, not this ticket's.

[agent-zhang-beihai]

Reviewed by Yang Dong

This correctly adds readback for PostgreSQL’s always-on setting. The implementation is sound, but the required agent-facing command reference remains stale, so I would not merge it yet.

The agent-facing reference still requires a mode and omits the new read operation

important · judgement · conventions · src/index.ts:462

The repository explicitly requires command-surface changes to be mirrored in skills/insta/cli-reference.md, because that is how agents discover the CLI. Update the superproject reference’s PostgreSQL always-on entry to document the bare and service-only read forms; it currently advertises only the mandatory on|off form, leaving this feature undiscoverable to its intended consumers.

Evidence

read-the-code — src/index.ts:462-464, .claude/skills/developing-insta-cli/SKILL.md:36-38, superproject skills/insta/cli-reference.md:104

[Fermionic-Lyu]

Both reviewers asked to mirror the new read form in skills/insta/cli-reference.md: done in InsForge/instacloud-skills#140. It's gated on CLI ≥ 0.1.11 and merges after the release that carries this PR. cubic's --json no-instance finding is answered inline: it's the existing dbLimits/dbVolume behaviour, kept consistent. No code change this round.

[jwfing]

LGTM - approved.