Backfill NULL organization_id on oauth_applications before constraint validation

Shilpa Kundapurrequested to merge
600899-backfill-null-org-id-oauth-applications-master into master

What does this MR do and why?

Adds a NOT NULL constraint to oauth_applications.organization_id, with a backfill of any remaining NULL rows first.

The 20260417155126 migration (19.0) added the constraint but assumed all rows had already been backfilled by the batched background migration in 18.9. That holds on GitLab.com, but not on GitLab Dedicated and self-managed instances, where oauth_applications rows (e.g. GitLab Pages, Mattermost) can be created via gitlab-ctl reconfigure or CNG's custom-instance-setup without an organization_id. The constraint validation then fails with PG::CheckViolation on those instances.

Why a no-op + reintroduce, and not an in-place fix

The backfill cannot be added inside 20260417155126:

  • We do not backdate or modify already-merged migrations.
  • A single migration cannot mix the DML backfill (UPDATE) with the DDL constraint (ALTER TABLE). The migration query analyzer runs in one mode and rejects whichever statement does not match it (DMLNotAllowedError / DDLNotAllowedError).

So 20260417155126 is converted to a no-op, and the work is reintroduced as two single-mode post-deployment migrations:

Migration Type Action
20260417155126_..._organization_id — converted to a no-op
20260625131308_backfill_null_organization_id_on_oauth_applications DML backfills NULL organization_id to the default (root) organization, in batches
20260625131309_..._oauth_applications_org_id DDL adds the NOT NULL constraint

The backfill has the earlier timestamp, so it runs before the constraint is validated. On GitLab.com the backfill matches zero rows (already backfilled in 18.9); the constraint add is idempotent where it already exists.

Database queries

Backfill (20260625131308)

each_batch iterates by primary key and filters organization_id IS NULL within each batch. Per batch it issues a boundary lookup and an update:

SELECT id FROM oauth_applications
WHERE organization_id IS NULL AND id >= :start
ORDER BY id ASC LIMIT 1 OFFSET 1000;

UPDATE oauth_applications SET organization_id = 1
WHERE organization_id IS NULL AND id >= :start AND id < :next_start;

The final batch has no upper bound: UPDATE ... WHERE organization_id IS NULL AND id >= :start.

** Limit  (cost=1.96..1.97 rows=1 width=4) (actual time=0.050..0.051 rows=0 loops=1)
   Buffers: shared hit=6
   ->  Sort  (cost=1.96..1.96 rows=1 width=4) (actual time=0.049..0.050 rows=0 loops=1)
         Sort Key: oauth_applications.id
         Sort Method: quicksort  Memory: 25kB
         Buffers: shared hit=6
         ->  Index Scan using idx_oauth_applications_organization_id on public.oauth_applications  (cost=0.43..1.95 rows=1 width=4) (actual time=0.011..0.012 rows=0 loops=1)
               Index Cond: (oauth_applications.organization_id IS NULL)
               Filter: (oauth_applications.id >= 1000)
               Rows Removed by Filter: 0
               Buffers: shared hit=3
Settings: work_mem = '230MB', seq_page_cost = '4', effective_cache_size = '472585MB', jit = 'off', random_page_cost = '1.5'**

https://console.postgres.ai/gitlab/projects/gitlab-production-main/sessions/53189/commands/155139

 ModifyTable on public.oauth_applications  (cost=0.43..1.95 rows=0 width=0) (actual time=0.007..0.007 rows=0 loops=1)
   Buffers: shared hit=3
   ->  Index Scan using idx_oauth_applications_organization_id on public.oauth_applications  (cost=0.43..1.95 rows=1 width=14) (actual time=0.006..0.006 rows=0 loops=1)
         Index Cond: (oauth_applications.organization_id IS NULL)
         Filter: ((oauth_applications.id >= 1000) AND (oauth_applications.id < 2000))
         Rows Removed by Filter: 0
         Buffers: shared hit=3
Settings: effective_cache_size = '472585MB', jit = 'off', random_page_cost = '1.5', work_mem = '230MB', seq_page_cost = '4'

https://console.postgres.ai/gitlab/projects/gitlab-production-main/sessions/53189/commands/155140

Constraint (20260625131309)

ALTER TABLE oauth_applications ADD CONSTRAINT check_77eda6baaa CHECK (organization_id IS NOT NULL) NOT VALID;
ALTER TABLE oauth_applications VALIDATE CONSTRAINT check_77eda6baaa;

References

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Shilpa Kundapur

Merge request reports