September 10, 2026
Tuning the Parallelism Knob
Live Wire: A Solo GitLab Upgrade Log — Stations 5 through 8 — A database setting that isn’t even in the official API sped up mid-size migrations noticeably. A 320,000-row table didn’t care.

A rule discovered at Station 5, verified at Station 6, and shown its actual limit at Station 7
This is Part 11 of "Live Wire: A Solo GitLab Upgrade Log" Previous: Station 6: The Bug GitLab Hasn't Fixed Yet | Series overview: Live Wire: A Solo GitLab Upgrade Log — Series Overview | Next: Station 7–8: The Backup That Looked Broken
TL;DR
Each station’s maintenance window happened to land on the quietest hour of the day, when database load sat near zero. Raising a normally-conservative parallelism setting during that window sped up mid-size background migrations noticeably — enough to formalize into a standard, repeatable step. Two stations later, a table with 322,136 rows made it clear this was never a guarantee: 40 minutes at full parallelism cleared 0.9% of it. The rule didn’t fail. It just turned out to have a scale it was never going to help with, and the right response was accepting that rather than pushing harder.
An Empty Hour, and a Question Worth Asking
Every station’s maintenance window happened to fall during the same quiet stretch — the point in the day when database load drops close to zero. An idle resource during a window that’s already reserved for risk is worth asking a simple question about: is there something useful to do with it?
The Fix, in One Sentence
Use the quiet window to safely push a normally-conservative setting higher, formalize it into a repeatable step — and stay honest about the fact that it accelerates work, it doesn’t guarantee completion.
Quick Start: Verifying a Setting Is Actually Tunable Before Trusting It
# Don't assume a setting is reachable via the official API — check first
curl -X PUT "https://<host>/api/v4/application/settings" \
--header "PRIVATE-TOKEN: <token>" \
--data "database_max_running_batched_background_migrations=6"
# response: field silently absent from the accepted whitelist
# The setting exists — it's just Rails-console-only
ApplicationSetting.current.update!(database_max_running_batched_background_migrations: 6)
The first command doesn’t error loudly — it just doesn’t do anything, which is its own kind of trap if you don’t check the response.
Station 5: The Rule Gets Discovered
With the database sitting at zero load during the maintenance window, raising database_max_running_batched_background_migrations from its default of 2 to 4 visibly sped up how fast background migrations cleared. That result got formalized into a standing rule for every subsequent station: raise it to 6 at the start of the noon window, and revert it to 2 at exactly 13:00 — regardless of whether migrations have finished — to avoid holding elevated parallelism longer than the quiet window actually justifies.
A Setting the Official API Won’t Touch
Testing whether this could be automated through GitLab’s own Application Settings REST API turned up a small surprise: PUT /api/v4/application/settings accepted the request without error, but the field simply wasn't in the accepted whitelist — no visible failure, just no effect. The only reliable way to change it turned out to be the Rails console directly, which is why the toggle above is two manual commands rather than one scripted API call.
Station 6: The Rule Works, Until It Meets a Table That Doesn’t Care
12:00 — parallelism 2 → 6
21 migrations clearing steadily...
The rule held up for exactly what it was meant for — mid-size migrations cleared noticeably faster with parallelism raised. Then the queue hit BackfillPushEventPayloadsProjectId, 77,471 rows**, and by 12:40 it still hadn't cleared. Raising parallelism speeds up small-to-medium migrations. A genuinely large table — tens of thousands of rows and up — still needs hours-scale time regardless of how many migrations are allowed to run concurrently. That's the first real edge of this tool, and it showed up on the very first station where the rule got tested for real.

The knob accelerates. It was never going to guarantee.
Station 7: A Bigger Table, an Even Clearer Answer
If Station 6 left any doubt about whether this was a one-off, Station 7 closed it. This station’s background migration queue was noticeably larger in scale than anything before it — 27 migrations, two of them well past a quarter million rows: MoveCiBuildsMetadataSelfManaged at 322,136 rows, BackfillMergeRequestFileDiffsPartitionedTable at 261,577.** Following the same SOP — parallelism raised to 6 for the noon window — MoveCiBuildsMetadataSelfManaged processed 3,039 rows in 40 minutes: 0.9% of the total. There was no ambiguity left about whether this would finish that day.
The Decision: Accept the Deferral, Don’t Force It
The response to both giant-table cases was the same, and deliberate: stop for the day, continue at the next station — don’t reach for a more aggressive lever, like pushing parallelism even higher, to force completion. This follows the same principle established earlier in this series for maintenance windows generally: if the service is stable, don’t fight to finish inside a window that was never going to be long enough. A migration that’s still running isn’t broken. It’s just going to take longer than one lunch hour, and that’s fine.
Under the Hood
+---------------------------+-----------------------------------------------+----------------------------------------------------+
| Station | What Happened | What It Taught |
+---------------------------+-----------------------------------------------+----------------------------------------------------+
| 5 | Parallelism 2 → 4, mid-size migrations | The idle noon window could safely absorb a higher |
| | cleared visibly faster | parallelism setting |
+---------------------------+-----------------------------------------------+----------------------------------------------------+
| — | REST API silently ignored the setting | Verify a setting is actually reachable via API |
| | | before assuming it can be automated that way |
+---------------------------+-----------------------------------------------+----------------------------------------------------+
| 6 | Rule formalized (6 at noon, 2 at 13:00); | Confirmed the rule works for mid-size migrations, |
| | a 77,471-row table still didn't clear by 12:40 | and found its first real edge |
+---------------------------+-----------------------------------------------+----------------------------------------------------+
| 7 | A 322,136-row table processed 0.9% in 40 min | Confirmed the edge wasn't a fluke — accepted |
| | at full parallelism | deferral instead of forcing it |
+---------------------------+-----------------------------------------------+----------------------------------------------------+
What Actually Worked
Formalizing the rule into a strict, time-boxed toggle — 6 at noon, back to 2 at 13:00 no matter what — meant the benefit (faster mid-size migrations) never came with the cost of holding elevated database load longer than the quiet window actually justified. Verifying the setting’s real reachability, rather than assuming the official API would accept it, avoided building an automation step around a field that would have silently done nothing.
Where This Still Falls Short
This isn’t a story about a rule failing — it’s a story about a rule turning out to have a boundary that took two more stations to actually see clearly. It’s worth being honest that this is a correction to understanding, not a dramatic failure: the tool does exactly what it always did, and the only thing that changed was knowing exactly where it stops helping.
Have you ever formalized a rule that worked the first time, only to find its real limit a few uses later?
This is Part 11 of "Live Wire: A Solo GitLab Upgrade Log" Previous: Station 6: The Bug GitLab Hasn't Fixed Yet | Series overview: Live Wire: A Solo GitLab Upgrade Log — Series Overview | Next: Station 7–8: The Backup That Looked Broken
GitHub: jasonChen0604
Portfolio: jason-chen-1cb56.web.app
LinkedIn: jason-cj-chen