feat(db): cloud_usage_events, boot facts and workspace failure columns (M4)

Merged
SA
1d ago
+18226-0

What and why

Schema only: the migration for data plan items 1, 8 and 10 of the cloud workspace cost and health design, in one migration (0196_cloud_usage_events_and_boot_facts). It goes first so the schema is live before M5a, M5b and M7 write to it. It replaces #9926.

  • New table cloud_usage_events: what we sent to Autumn. One row per (boot_id, lock_seq, feature), the primary key, with window_from, window_to, amount, sent_at, created_at and updated_at ($onUpdate, like cloud_workspace_boots). Indexes on (organization_id, sent_at) and a partial index on created_at where sent_at is null.
  • cloud_workspace_boots: end_reason, active_cpu_ms, egress_bytes, phases (jsonb), trace_id, created_by_user_id. All nullable.
  • cloud_workspaces: failure_reason, failed_at. Nullable.
  • Enum types cloud_usage_feature, cloud_workspace_boot_end_reason, cloud_workspace_failure_reason. They are Postgres enums, like cloud_workspace_status and automation_runs.error_code, with zod enums in enums.ts.

Where this differs from the design

  • No surrogate id. The natural key is the primary key. It is also M5c's idempotency key, and its prefix covers the per-boot read.
  • seq is named lock_seq, the same name as on the boot row and Autumn's lockSeq.
  • updated_at added, because sent_at is set after insert.
  • Partial index for unsent rows, for check 3 and the M5c reconcile.
  • Foreign keys. boot_id has a foreign key to boots. Organization, workspace and user have none, because they record what was sent. boots.created_by_user_id has none either, so there is no lock on auth.users and the attribution stays after a user is deleted.
  • No reservation columns. The rules for matching a row to Autumn's internal events belong to the check. They are on the evidence page under "For M5a and check 3".

What breaks, for whom

Nothing. The change is additive and every new column is nullable. No code reads or writes the new columns, and tRPC does not change, so released desktop, mobile and CLI builds are unaffected.

Migration safety: both tables are small in production (about 6.7k and 13.3k rows) and neither is on the hot list. The whole migration took 95 ms on a fresh child of production. It locks the child table first (boots), then cloud_workspaces, and takes no lock on the auth tables. I did not run a pgbench rehearsal; the skill does not require one here. This new PR gets its own preview database.

Links

Checks

  • bunx turbo run typecheck --filter='...@superset/db': 21/21 pass
  • packages/trpc bun test: 1007 pass
  • biome check packages/db: clean
  • drizzle-kit check: clean; regenerating gives no changes
  • Applied on a fresh child of production; constraint and updated_at tests passed (rolled back)

Summary by cubic

Adds the schema for tracking cloud workspace usage and health: a new cloud_usage_events table records what was sent to Autumn, and cloud_workspace_boots and cloud_workspaces gain nullable columns for boot facts and failure details. This is schema only—no code writes or reads these yet—so the change is fully additive and doesn't affect released builds.

Migration

  • One migration (0196_cloud_usage_events_and_boot_facts) covers all the changes; no surrogate id on cloud_usage_events since the natural key (boot_id, lock_seq, feature) also serves as M5c's idempotency key.
  • Indexes support sent-time lookups and unsent row reconciliation via a partial index on created_at where sent_at is null.
  • New enums: cloud_usage_feature, cloud_workspace_boot_end_reason, and cloud_workspace_failure_reason, with matching zod enums.
  • Attribution columns (organization_id, user_id, created_by_user_id) intentionally have no foreign keys so billed history stays intact after a user is deleted.