feat(db): insta db query <service> — managed-DB (mysql/redis/mongo) queries via console exec

[CarmenDou]

What

Adds insta db query <service> [args...] — the CLI entry point for the managed-DB console. It runs a query/command against a MANAGED database (mysql / redis / mongodb) through the platform's console exec API (POST /projects/{projectId}/database/console/{serviceId}/exec). The web console already had this; the CLI had nothing. Postgres is deliberately rejected here — it has insta db url / insta db connect and the SQL editor.

Examples (one per engine):

insta db query mydb "select * from products limit 10"
insta db query mymongo "db.users.find().limit(10).toArray()" --database shop
insta db query cache GET mykey

How

• New subcommand query under the existing db command group; the group's .description(...) now covers managed-DB query alongside the postgres controls.
• <service> is resolved by NAME from GET /projects/{projectId}/services?branch=<branch>. A postgres / non-managed service dies with db query is for managed databases (mysql/redis/mongodb); postgres uses the SQL editor / DATABASE_URL; an unknown name dies with service not found: <name>.
• Dispatch by resolved engine:
  • mysql — body { command: <args joined with a space> }; response { columns, rows, rowCount, truncated } rendered as a simple left-aligned table (em-dash for null cells, trailing (<rowCount> rows[, truncated])).
  • mongodb — body { command: <args joined>, ...(database ? { database } : {}) } (--database, mongo only); response { result } pretty-printed as JSON.
  • redis — body { argv: [<trailing args, verbatim>] } (pre-tokenized, not a joined string); response { reply } printed raw for a scalar, pretty JSON otherwise.
• Uses api.rawRequest('POST', …) so a 202 gate is relayed via handleApproval(res, opts.json) before any output; --json prints the raw body. Errors stay plain Error/ApiError for the guard() wrapper to format.
• Flags: --database <db> (mongo only), --branch <branch>, --json.
• All shape logic lives in pure, exported seams in src/commands/db-query.ts (consoleExecPath, execBody, renderMysqlRows, renderRedisReply, renderMongoResult); the dbQuery handler composes them. Tested in test/db-query.test.ts with no network mocking, per this repo's pure-seam convention.

Verify

• npm run typecheck — clean.
• npm test — 45 files, 637 tests pass (incl. the new test/db-query.test.ts, 10 tests).
• npx tsx src/index.ts db query --help — command surface + options render.

CLI reference mirror (companion)

The agent-facing CLI reference lives in InsForge/insta-skills (this repo tracks no cli-reference.md), so the required mirror ships as its companion PR — InsForge/insta-skills#61, which adds the insta db query row to insta/cli-reference.md. Merge alongside this PR.

---

Summary by cubic

Adds insta db query <service> [args...] so the CLI runs queries against managed databases (mysql/redis/mongodb) through the console exec API, matching the web console.

• Resolves a service by name; postgres is rejected and unknown names fail with service not found: <name>.
• mysql/mongodb send the args as a joined command string (mongodb takes an optional --database); redis sends them as a pre-tokenized argv. Empty args and --database on non-mongodb are rejected before any request.
• Per-engine renderers produce a mysql table with row count, a redis raw scalar or pretty JSON, and mongo pretty JSON. Pure seams plus the injected-api handler flow are covered by unit tests with no network mocking; --branch and --json are supported.

CLI reference mirror ships as companion PR InsForge/insta-skills#61 (adds the insta db query row to cli-reference.md).

^{Written for commit 8038dc0. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 3 files

_{You’re at about 90% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

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

Re-trigger cubic</sub>

[jwfing]

Summary
The implementation mostly matches the requested managed-DB console exec behavior, but the PR misses a required command-reference update.

Requirements Context
I used the PR title/description as the feature spec: add insta db query <service> [args...] for mysql/redis/mongodb through POST /projects/{projectId}/database/console/{serviceId}/exec, reject postgres/non-managed services, support --branch, --database for MongoDB, and --json, and render per-engine responses. I also checked repo guidance: AGENTS.md, CONTRIBUTING.md, and .claude/skills/developing-insta-cli/SKILL.md all state that command/flag changes must be mirrored in the agent-facing CLI reference in the same change set. I did not find a separate linked issue or in-repo product spec beyond those sources.

Findings

Critical

• src/index.ts:270-274, AGENTS.md:16-17, CONTRIBUTING.md:41-44, .claude/skills/developing-insta-cli/SKILL.md:36-38 — The PR adds a new public command and flags, but the required skills/insta/cli-reference.md update is absent from the changed files. This is explicitly marked as a non-negotiable/same-change-set requirement, and the PR description calls it a follow-up, so agents will not learn the new CLI surface from the canonical reference.

Suggestion

• src/index.ts:270-274, src/commands/db-query.ts:23-27, src/commands/db-query.ts:80-81 — --database is documented as MongoDB-only, but the handler accepts it for every engine and execBody silently drops it for mysql/redis. Consider rejecting opts.database when the resolved engine is not mongodb; otherwise a user can believe they selected a database while the command executes against the engine default.
• src/commands/db-query.ts:70-89, test/db-query.test.ts:1-95 — Tests cover the pure path/body/render helpers, but not the handler behavior that resolves services, rejects postgres/non-managed services, forwards branch selection, handles 202 approvals, and dispatches --json. A small injected-client seam, similar to nearby command tests, would make those user-visible paths regression-tested without real network calls.

Information

• Software engineering: src/commands/db-query.ts:7-91 follows the repo’s ESM import style, command-module layout, ApiClient/requireProject pattern, and guard()-formatted error flow.
• Functionality: src/commands/db-query.ts:73-89 implements the described service lookup, managed-engine gate, raw POST, approval handling, JSON output, and engine-specific render dispatch.
• Security: src/commands/db-query.ts:23-27 and src/commands/db-query.ts:81-89 send user query text as JSON to the authenticated platform API and do not introduce shell execution, new dependencies, or credential logging beyond the command’s intended database-result output.
• Performance: src/commands/db-query.ts:39-52 renders MySQL results linearly over the returned columns/rows, and the command performs one service-list request plus one exec request; I did not see N+1 behavior or hot-path blocking work.
• Verification: I inspected files only and did not run npm run typecheck or npm test because the review instructions were read-only.

Verdict
request_changes — blocking only on the missing required CLI reference update.

[jwfing]

Summary
The code path looks coherent, but the PR misses a documented non-negotiable for command/flag changes.

Requirements Context
I used the PR description as the feature intent: add insta db query <service> [args...] for mysql/redis/mongodb via POST /projects/{projectId}/database/console/{serviceId}/exec, reject postgres/non-managed services, support --database, --branch, and --json, and render per-engine responses. I also checked repo guidance in AGENTS.md, CONTRIBUTING.md, and .claude/skills/developing-insta-cli/SKILL.md; all state that command/flag changes must be mirrored in skills/insta/cli-reference.md / InsForge/insta-skills in the same change set.

Findings

Critical

• src/index.ts:270-274, AGENTS.md:15-17, CONTRIBUTING.md:41-44: This PR registers a new db query command with new flags, but the required CLI reference mirror is absent from the changed files and the PR description explicitly defers it as follow-up. The repo docs call this “non-negotiable” / “only half done” and say to update it in the same change set, so the command surface would ship without the agent-facing reference that downstream coding agents use.

Suggestion

• (none)

Information

• src/commands/db-query.ts:23-109, test/db-query.test.ts:17-189: Software engineering/functionality review found the main behavior covered through pure helpers and injected API seams: service lookup by branch, managed-engine rejection, mongodb database pass-through, empty-args rejection, approval handling, and JSON passthrough. I did not rerun npm run typecheck or npm test because this checkout does not have dependencies installed and installing them would mutate the read-only workspace.
• src/commands/db-query.ts:101-109: No security-relevant regression found in the CLI layer; user-provided DB commands are sent to the authenticated platform console API and are not executed through a local shell or logged by the CLI.
• src/commands/db-query.ts:87-101: No performance issue found; the handler performs one service-list request and one exec request, with local rendering bounded by the response already returned by the platform.

Verdict
Request changes until the CLI reference mirror is included or the documented requirement is explicitly waived by maintainers.

[jwfing]

Summary
The managed-DB query command is implemented consistently with the repo’s command/API patterns, with no Critical findings.

Requirements Context
I used the PR title/description for InsForge/insta-cli#154 as the feature spec: add insta db query <service> [args...] for mysql/redis/mongodb through POST /projects/{projectId}/database/console/{serviceId}/exec, reject postgres/non-managed services, support --branch, Mongo-only --database, --json, approval handling, and per-engine output. I also checked AGENTS.md, CONTRIBUTING.md, .claude/skills/developing-insta-cli/SKILL.md, and README.md; the command-reference mirror lives in the separate InsForge/insta-skills#61 companion PR. I did not find a separate linked issue or in-repo product spec beyond those sources.

Findings

Critical
(none)

Suggestion

• src/index.ts:353-356 — The new command is approval-gated as db.query, but insta policy set help still lists the known policy actions without db.query. Runtime appears to accept arbitrary action strings, so this is not blocking, but adding it here keeps governance discoverable from the CLI help.

Information

• src/commands/db-query.ts:11-78, test/db-query.test.ts:11-190 — Software engineering: the new module follows the repo’s ESM command-module style, pure helper seams, injected API dependency pattern, and guard()/die() error flow; tests cover body construction, rendering, service resolution, rejection paths, approval handling, and JSON output.
• src/commands/db-query.ts:81-109, src/index.ts:248-274 — Functionality: the implementation matches the described branch-scoped service lookup, managed-engine gate, console exec POST, 202 handling, raw JSON output, and engine-specific rendering.
• src/commands/db-query.ts:23-27, src/commands/db-query.ts:101-109 — Security: the CLI sends the intended user-supplied DB command as JSON to the authenticated platform API; it adds no local shell execution, new dependency, or credential logging beyond the command’s intentional database result output. Authorization and approval enforcement remain server-side.
• src/commands/db-query.ts:39-52, src/commands/db-query.ts:89-101 — Performance: the command does one service-list request plus one exec request, and MySQL rendering is linear in the returned result size; I did not see N+1 behavior, blocking local I/O, or hot-path work.
• Verification: I inspected files statically and ran git diff --check main...HEAD; I did not run npm run typecheck or npm test because the review instructions were read-only and I avoided commands that might write local artifacts.

Verdict
approved — no Critical findings. This is a bot comment verdict only; human approval and the companion CLI-reference PR still need to be handled by the normal merge flow.

[jwfing]

LGTM - approved.