feat(peek): table size, and the orphan-FK query behind "Peek orphans"

[huyplb]

Second of the three mockup slices. Stacked on #387 (ux/professional-polish), since it uses StatCard.

Size

Peek Insight showed rows, nulls and distinct counts but not size — second of the four cards in the mockup. Size is a catalog fact like the others, so it rides the same probe: one extra column, aliased size_bytes.

Three factories cover nine of the fourteen dialects, so the expression is a factory parameter. That is not tidiness — it is the only reason two wrong numbers did not ship:

• Redshift shares the Postgres factory and has no pg_total_relation_size (size lives in SVV_TABLE_INFO). The redshift service in this repo is a real Postgres, so baking the expression in would have passed every test here and failed on an actual warehouse.
• CockroachDB accepts the call and always answers NULL — a compatibility stub. Measured on v26.3.0: SELECT pg_total_relation_size('demo_a.orders'::regclass) → NULL.

Both pass 'NULL' instead.

Verified live, running the probe SQL as written:

engine	rows	size_bytes
postgres	5000	1441792 → 1.4 MB
mysql	4838 est.	1736704 → 1.7 MB

Not verified: sqlserver/azuresql — the container will not start here (/docker-init/entrypoint.sh missing) — and yugabytedb, not accepting connections. Yugabyte keeps the Postgres expression: if the function is stubbed there too, the column returns null and the card reads "Not reported", the same graceful answer as opting out.

Oracle, Db2, SQLite, DuckDB and ClickHouse stay null on purpose. Oracle and Db2 expose only a page count whose page size varies per tablespace, and a plausible wrong size is worse than a dash for a figure people act on.

Orphan foreign keys

NOT EXISTS, not NOT IN — measured, not received wisdom. With a NULL in the parent's key column, on live Postgres over the same rows:

NOT EXISTS (ours)   2
NOT IN              0

NOT IN silently reports a table full of orphans as clean.

Worth recording: my first attempt at demonstrating this proved nothing — the parent key was a PRIMARY KEY, so the NULL was rejected and both forms agreed on 2. It only appears against a nullable key column, which is exactly what a foreign key may reference.

Other decisions:

• Rows with a NULL foreign key are excluded — a NULL FK is an absent relationship, not a broken one.
• Both sides aliased, so a self-referencing table stays apart from itself.
• The parent resolves through its own schema; a cross-schema FK that loses it resolves a bare name wherever the connection points — a different table with the same name.

Generated SQL run verbatim on live engines over five rows holding two orphans and one NULL: postgres 2, mysql 2.

Why this is not in the insight probe

The probe is catalog-only and answers in constant time whatever the table's size. Counting orphans is a scan. So it is offered as something the reader asks for once, not something a 2.4M-row table pays for because a tab was opened — the mockup's own footer says "Profile from pg_stats + TABLESAMPLE 1%", and a sampled profile cannot report exactly 14 orphans. The two claims needed separating.

Tests

Nine for the orphan queries, five more for formatBytes, six for the size probes. buildOrphanPeek is asserted to ask the same question as the count — the test compares the predicates directly, so the button and the number cannot drift apart.

Suite: 3646 passed, 0 failed. Typecheck clean.

Still to come

Slice 3 — Account stage inline alterations. The UI affordance for "Peek orphans" is not wired yet; this PR lands the query and the size card.

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds on-demand table scans and changes catalog insight SQL across multiple dialects; orphan detection must stay semantically correct (NOT EXISTS, NULL FKs) to avoid misleading integrity signals.

Overview
Data Peek Insight gains a catalog Size stat (sizeBytes on the table-insight probe, with dialect-specific SQL and explicit opt-outs for engines that cannot report bytes reliably) plus human-readable formatBytes. Orphan foreign keys are detected only on user action: per-FK NOT EXISTS count queries, summary cards, and Peek orphans opening a new Data Peek via openDataPeekOrphans and buildOrphanPeek.

Access → Account now surfaces engine-supported alteration chips and drop safety warnings by reusing logic moved into accountAlterations (shared with User Management).

Tests cover orphan SQL shape, size normalization, formatBytes, and alteration/drop-note rules.

^{Reviewed by Cursor Bugbot for commit 4fd1280. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_8ec9f1ba-7244-4ded-9a00-61abe477f1de)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_5ce1f801-8463-458a-9ffc-8bbbd85e1050)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_ff5b8d8a-ce23-4da5-8dcf-d8110154f8d8)