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

Closed
SA
1d ago
+36332-0

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 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.
  • 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_amount at reserved_at, then amount - reserved_amount at sent_at for a confirm or release. On expiry it is -reserved_amount at reservation_expired_at, plus a track of amount at sent_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, like cloud_workspace_status and automation_runs.error_code. Their values are in enums.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.
  • seq is named lock_seq, the same name as on the boot row and Autumn's lockSeq.
  • Partial index for unsent rows. Check 3 and the M5c reconcile both read unsent rows.
  • Foreign keys. boot_id has 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_id has none either, so the migration takes no lock on auth.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

Checks

  • bunx turbo run typecheck --filter='...@superset/db': 21/21 pass
  • packages/trpc bun test: 1007 pass (after merging main)
  • biome check packages/db: clean
  • drizzle-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