feat(db): cloud_usage_events, boot facts and workspace failure columns (M4)
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, withwindow_from,window_to,amount,sent_at,created_atandupdated_at($onUpdate, likecloud_workspace_boots). Indexes on(organization_id, sent_at)and a partial index oncreated_atwheresent_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, likecloud_workspace_statusandautomation_runs.error_code, with zod enums inenums.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. seqis namedlock_seq, the same name as on the boot row and Autumn'slockSeq.updated_atadded, becausesent_atis set after insert.- Partial index for unsent rows, for check 3 and the M5c reconcile.
- Foreign keys.
boot_idhas a foreign key to boots. Organization, workspace and user have none, because they record what was sent.boots.created_by_user_idhas none either, so there is no lock onauth.usersand 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
- Evidence: https://app.superset.sh/page/m4-usage-events-and-boot-facts-migration-4gvft9
- Design: https://app.superset.sh/page/admin-cloud-workspace-cost-and-health-design-8z3d4d
- Replaces #9926
Checks
bunx turbo run typecheck --filter='...@superset/db': 21/21 passpackages/trpcbun test: 1007 passbiome check packages/db: cleandrizzle-kit check: clean; regenerating gives no changes- Applied on a fresh child of production; constraint and
updated_attests 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 surrogateidoncloud_usage_eventssince 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_atwheresent_atis null. - New enums:
cloud_usage_feature,cloud_workspace_boot_end_reason, andcloud_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.