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. It goes first so the schema is live before M5a, M5b and M7 write to it.
- New table
cloud_usage_events: one row for each amount billed to Autumn for a boot. Primary key(boot_id, lock_seq, feature). 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.- Reservation columns (migration 0197):
reserved_amount,reserved_at,reservation_expired_at, and a CHECK that the first two are set together and that an expiry needs a reservation. With them a row reproduces Autumn's events for its lock:+reserved_amountatreserved_at, thenamount - reserved_amountatsent_atfor a confirm or release. On expiry it is-reserved_amountatreservation_expired_at, plus a track ofamountatsent_at. So a lock that crosses a day or period edge splits the same way it does in Autumn. These columns are in a new file, 0197, so the pushed 0196 is unchanged. - Enum types
cloud_usage_feature,cloud_workspace_boot_end_reason,cloud_workspace_failure_reason. They are Postgres enums, likecloud_workspace_statusandautomation_runs.error_code. Their values are inenums.ts, with zod enums for M1.
Where this differs from the design
- No surrogate
id. The primary key is the natural key. It is also the idempotency key that M5c will send, and its prefix covers the per-boot read. seqis namedlock_seq, the same name as on the boot row and Autumn'slockSeq.- Partial index for unsent rows. Check 3 and the M5c reconcile both read unsent rows.
- Foreign keys.
boot_idhas a foreign key to boots. Organization, workspace and user have none: the row records what was sent to Autumn, and a later delete must not change it.boots.created_by_user_idhas none either, so the migration takes no lock onauth.users.
Found in Autumn
Autumn stores one lock as several events: the reservation, then a confirm or release adjustment, or on expiry a separate refund plus a track. Our ten derived events matched Autumn on value and UTC day, including three locks that cross midnight. The evidence page has:
- the case counts,
- the comparison on real locks,
- a table that maps our rows to Autumn's events for both features, covering the 2026-10-21 legacy correction behind the 32 "duplicate" CPU events and the 223 events with no bootId.
It also lists 17 locks that one row cannot reproduce and check 3 must flag: 4 double charges, 2 exact duplicate events, and 11 locks with many events.
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 (6,710 and 13,323 rows) and neither is on the hot list. The whole migration ran in about 130 ms on a 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 when no hot table is locked and no large table is rewritten or scanned.
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
Checks
bunx turbo run typecheck --filter='...@superset/db': 21/21 passpackages/trpcbun test: 1007 pass (after merging main)biome check packages/db: cleandrizzle-kit check: clean- Both migrations applied on the workspace Neon branch; the rows-to-Autumn rules were tested there on real locks and rolled back