feat(db): shared cloud usage queries (M1)
What and why
M1 adds the read side that the customer cloud router (M2) and the admin app's cloud router (A2) share. It is one file, packages/db/src/cloud-usage-query.ts, a sibling of task-list-query.ts. It holds query functions and the plain TypeScript types of what they take and return. It has no zod, no API contract, and no imports from packages/auth or the Autumn client. The admin repo vendors db and shared, not trpc, so these must run whole queries rather than build conditions for a router.
Scope change (agreed with the coordinator): periods are built in each router from cloudBillingPeriod plus queryCloudUsage.
queryCloudUsage(db, scope, { window, filters?, groupBy?, limit, cursor?, overagePerGbHour })returns billed usage (cloud_usage_events,box_gb_minutes, placed bysent_at) and boot counts (placed bystarted_at). It gives a total, and withgroupByone row per user, UTC day or workspace.- A workspace that failed in the window, even with no boot, counts as 1 in
workspacesin every grouping and in the total. Grouped by workspace it has its own row withfailure { reason, at }; by user it falls under its creator, and by day underfailed_at. - Paging by amount reads at each call, so an event sent between pages can move a row across the cursor. The doc line says so. Paging by day and paging boots are stable.
listCloudBoots(db, scope, { window, filters?, endReason?, open?, limit, cursor?, now, overagePerGbHour })returns boot rows, newest first, each with the sum of its sent events. Failed and released boots show zero usage.cloudBillingPeriod(anchor, index)andcloudBillingPeriodIndex(anchor, startDate)hold the month arithmetic for billing periods, shared by both routers and by{ period }ranges. Autumn's data shows it resets on a fixed day of the month, or on the last day of a shorter month.previousResetAtsettles the day whenresetsAtis a short month's last day.- With
scope.userIdset, every result has only that user's rows. - Cursors are typed keyset objects that the router validates, like
task.listPage:CloudUsageCursor.gbMinutesis decimal digits with an optional fraction, cast to numeric in SQL.CloudBootCursoris{ startedAt: Date, id }. It is exact becausecloud_workspace_boots.started_atis always written from a JSDate(millisecond precision, inmeter.ts); the cursor relies on that.
- Results contain
Datevalues (superjson carries them).usageUsdis gbHours × the caller'soveragePerGbHour, rounded to cents once, at output. - There is one plain result type per function (
CloudUsageResult,CloudBootsResult), and it is the shared contract. Each router ties its own zod output schema to it withsatisfies z.ZodType<…>, so drift fails typecheck.
Preparation (own commits):
packages/dbhad test files but notestscript, so CI never ran them; this adds the script, and a test preload with a placeholderDATABASE_URL(as inpackages/trpc), becauseseed-default-statuses.test.tsimports the db client.LEGACY_MACHINE_SIZEin@superset/shared/billingreplaces the inline"large"in the sandbox claim. No change in behaviour.
Tests run on PGlite, an in-process Postgres 17. DDL is built from the drizzle definitions for only the seeded tables and their foreign-key parents. The file runs in about 2 s; about 1.6 s of that is PGlite starting. It needs no server, so the tests run in the CI unit job. The new dev dependency is @electric-sql/pglite, pinned exactly and imported only by the test. There is one test per behaviour: totals, grouping, a failed workspace with no boot, the sent_at window edge, boots, the scope rule, cursors (including a started_at tie), and billing periods through short months.
Not in this PR: an index on cloud_workspace_boots (organization_id, started_at, id). It goes to the next migration.
What breaks and for whom
Nothing. The PR adds one file, one export path, one dev dependency and one constant. It adds no router and changes no procedure. The admin app gets the code on its next deploy.
Links
- Evidence: https://app.superset.sh/page/m1-shared-cloud-usage-schemas-and-queries-sgi9h1 (version 7)
- Design: https://app.superset.sh/page/admin-cloud-workspace-cost-and-health-design-8z3d4d
Summary by CodeRabbit
- New Features
- Added cloud usage reporting with organization and member scoping, filtering, grouping, and pagination.
- Added cloud boot listings with usage, duration, machine details, and overage cost estimates.
- Added billing-period calculations that handle month-end dates.
- Tests
- Added coverage for usage and boot queries, filtering, pagination, and billing-period calculations.