Add worker capturing trial usage before an Ultimate trial ends
What does this MR do and why?
MR 2 of 5 for https://gitlab.com/gitlab-org/gitlab/-/work_items/625030, which adds a post-trial usage card to the group Billing page. MR 1 (!257608 (merged), merged) added the trial_usages table. Nothing reads it yet, the card itself is MR 3.
We capture usage before the trial ends because compute minutes only exist per calendar month, and CustomersDot only returns trial credits while a trial is active. Trial length is 30 or 60 days, CustomersDot decides which, so the job targets trials ending in the next 2 days. Each nightly run in that window re-saves the row: the last day wins, and a failed CustomersDot read gets a second try.
What's added:
- Daily cron worker
GitlabSubscriptions::Trials::ScheduleUsageCaptureWorker(SaaS only, 01:00 UTC, behind feature flagtrial_usage_capture, default off, rollout issue #630782): finds Ultimate trials ending in the next 2 days, oneeach_batchloop per day in batches of 100, and enqueues oneGitlabSubscriptions::Trials::CaptureUsageWorkerper trial (urgency low, idempotent, deduplicated, at most 10 running at once). - The child worker runs
GitlabSubscriptions::Trials::CaptureUsageService, which upserts one row on(namespace_id, trial_ends_on): max seats used, compute minutes as a 30-day rate, trial type, and credits used from CustomersDot. A CustomersDot failure still writes the row, just withcredits_usednil; on a refresh it keeps the credits already stored instead. Compute minutes are stored as a 30-day rate extrapolated from the trial's end month, or from the month before it when the trial covers fewer than 7 days of the end month.compute_minutes_monthrecords which month was used. - A post-deployment migration adds the partial index
index_gitlab_subscriptions_on_trial_ends_on_and_id_where_trialongitlab_subscriptions (trial_ends_on, id) WHERE trial = true, usingadd_concurrent_index. On the production clone it built in 12.8 s and takes 60 MiB.
Database
The scheduler queries one day at a time, so each batch query and each each_batch boundary query is a range on a single trial_ends_on value with the (trial_ends_on, id) index. Plans below are from a Database Lab clone (state 2026-10-08 12:24 UTC) with the index created on the clone, for trial_ends_on = '2026-10-10' (7761 Ultimate trials end that day). 2384644 is the real lowest id for that day and 21331386 the boundary the OFFSET 100 query returns.
First id of the day:
SELECT "gitlab_subscriptions"."id" FROM "gitlab_subscriptions" WHERE "gitlab_subscriptions"."hosted_plan_name_uid" IN (8, 10) AND "gitlab_subscriptions"."trial" = TRUE AND "gitlab_subscriptions"."trial_ends_on" = '2026-10-10' ORDER BY "gitlab_subscriptions"."id" ASC LIMIT 1Limit over an Index Scan on index_gitlab_subscriptions_on_trial_ends_on_and_id_where_trial, 4 buffers, 3.6 ms cold. Plan: https://postgres.ai/console/gitlab/gitlab-production-main/sessions/62656/commands/167786
Next batch boundary:
SELECT "gitlab_subscriptions"."id" FROM "gitlab_subscriptions" WHERE "gitlab_subscriptions"."hosted_plan_name_uid" IN (8, 10) AND "gitlab_subscriptions"."trial" = TRUE AND "gitlab_subscriptions"."trial_ends_on" = '2026-10-10' AND "gitlab_subscriptions"."id" >= 2384644 ORDER BY "gitlab_subscriptions"."id" ASC LIMIT 1 OFFSET 100Limit over an Index Scan on the same index, 101 index rows, 108 buffers, 1.2 ms. Plan: https://postgres.ai/console/gitlab/gitlab-production-main/sessions/62656/commands/167838
Batch load:
SELECT "gitlab_subscriptions".* FROM "gitlab_subscriptions" WHERE "gitlab_subscriptions"."hosted_plan_name_uid" IN (8, 10) AND "gitlab_subscriptions"."trial" = TRUE AND "gitlab_subscriptions"."trial_ends_on" = '2026-10-10' AND "gitlab_subscriptions"."id" >= 2384644 AND "gitlab_subscriptions"."id" < 21331386Index Scan on the same index, 100 rows, 107 buffers, 1.4 ms. Plan: https://postgres.ai/console/gitlab/gitlab-production-main/sessions/62656/commands/167842
For reference, the same day without id bounds reads all 7761 rows through the index in 1.6 s cold (https://postgres.ai/console/gitlab/gitlab-production-main/sessions/62656/commands/167787), and without any index on trial_ends_on the old plan scanned every active Ultimate trial (158,483 rows, 8.47 s cold): https://postgres.ai/console/gitlab/gitlab-production-main/sessions/58559/commands/163494. The planner estimates 7 rows per day against thousands actual, which is why the work stays batched.
The index covers the 1,954,558 rows with trial = true: 60.27 MiB, built in 12.8 s on the production clone.
The production trial_usages table is still empty because the worker is not deployed, so a plan taken there would only show the empty-table Seq Scan on trial_usages_202610 with 0 rows. I populated a Database Lab clone of gitlab-production-main (state 2026-10-27 12:19 UTC, Joe session 73081) with INSERT INTO trial_usages ... SELECT ... FROM gitlab_subscriptions for every Ultimate trial (hosted_plan_name_uid IN (8, 10), trial = true) ending between 2026-10-01 and 2026-11-30 whose namespace exists, then ran ANALYZE trial_usages. That wrote 97,403 rows: 17,366 into trial_usages_202610 and 80,037 into trial_usages_202611, roughly what one monthly partition will hold in production.
Lookup before the write:
SELECT "trial_usages".* FROM "trial_usages" WHERE "trial_usages"."namespace_id" = 2944903 AND "trial_usages"."trial_ends_on" = '2026-10-29' LIMIT 1Limit over an Index Scan using trial_usages_202610_namespace_id_trial_ends_on_idx on gitlab_partitions_dynamic.trial_usages_202610, 1 row, 6 buffers, 1.0 ms (plan).
Upsert, second capture (row exists):
INSERT INTO "trial_usages" ("namespace_id","trial_starts_on","trial_ends_on","trial_type","max_seats_used","compute_minutes_used","compute_minutes_month","credits_used","created_at","updated_at") VALUES (2944903, '2026-09-29', '2026-10-29', 'ultimate_with_dap', 4, 250, '2026-10-01', 12.5, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP) ON CONFLICT ("namespace_id","trial_ends_on") DO UPDATE SET updated_at=(CASE WHEN ("trial_usages"."trial_starts_on" IS NOT DISTINCT FROM excluded."trial_starts_on" AND "trial_usages"."trial_type" IS NOT DISTINCT FROM excluded."trial_type" AND "trial_usages"."max_seats_used" IS NOT DISTINCT FROM excluded."max_seats_used" AND "trial_usages"."compute_minutes_used" IS NOT DISTINCT FROM excluded."compute_minutes_used" AND "trial_usages"."compute_minutes_month" IS NOT DISTINCT FROM excluded."compute_minutes_month" AND "trial_usages"."credits_used" IS NOT DISTINCT FROM excluded."credits_used") THEN "trial_usages".updated_at ELSE CURRENT_TIMESTAMP END),"trial_starts_on"=excluded."trial_starts_on","trial_type"=excluded."trial_type","max_seats_used"=excluded."max_seats_used","compute_minutes_used"=excluded."compute_minutes_used","compute_minutes_month"=excluded."compute_minutes_month","credits_used"=excluded."credits_used" RETURNING "id","trial_ends_on"Conflict Resolution UPDATE with arbiter index index_trial_usages_on_namespace_id_and_trial_ends_on, 0 tuples inserted, 1 conflicting tuple, 183 buffers, 5 WAL records (403 bytes), 1.1 ms; the lock list shows only the trial_usages_202610 partition, the parent table, the unique index, the primary key and the id sequence (plan).
Upsert, first capture (no row yet):
Same statement with namespace 6543: same arbiter index, 1 tuple inserted, 0 conflicting tuples, 147 buffers, 4 WAL records (324 bytes), 5.4 ms of which 4.4 ms is the namespaces foreign key trigger (plan).
Both statements prune to a single monthly partition, and the write is resolved through the unique index.
Volume: about 3100 trials end on an average day (7761 on the sampled day), each captured on its last two days, so roughly twice that many child jobs and CustomersDot calls per day, writing one new row per trial (the second run updates the row in place).
References
- Issue: https://gitlab.com/gitlab-org/gitlab/-/work_items/625030
- MR 1 (
trial_usagestable, merged): !257608 (merged) - Feature flag rollout issue: #630782
Screenshots or screen recordings
No user-facing change; the card comes in MR 3.
How to set up and validate locally
- Check out this branch and run
bin/rails db:migrate. - In a rails console, give a group an active Ultimate trial ending tomorrow:
group.gitlab_subscription.update!(hosted_plan: Plan.find_by(name: 'ultimate_trial'), trial: true, trial_starts_on: 29.days.ago.to_date, trial_ends_on: 1.day.from_now.to_date, max_seats_used: 3) - Enable the flag:
Feature.enable(:trial_usage_capture). - Run
GitlabSubscriptions::Trials::ScheduleUsageCaptureWorker.new.perform. - Check
GitlabSubscriptions::TrialUsage.last. Without a local CustomersDot,credits_usedcomes back nil.
MR acceptance checklist
- I have evaluated the MR acceptance checklist for this MR.