gitlab v18.5.3 업그레이드 후, Background migrations - BackfillPartitionedProjectDailyStatistics: project_daily_statistics 실패 처리

gitlab v18.5.3 이후 버전을 업그레이드하면 background migration 작업 하나가 실패한다.
"BackfillPartitionedProjectDailyStatistics: project_daily_statistics" 작업으로 실패 후
다음 버전으로 업그레이드 시, DB migration 작업에 오류가 발생해서 시스템이 꼬이는 상태가
발생된다. 이에 대한 원인과 해결 방안을 간략하게 정리한다.

gitlab v18.5.3 버전으로 업그레이드를 진행하면 아래와 같은 background migration 오루가 발생되고 원인을 확인하면
아래와 같은 오류 메시지를 확인할 수 있다.

PG::CheckViolation: ERROR:  no partition of relation "project_daily_statistics_b8088ecbd2" found for row
DETAIL:  Partition key of the failing row contains (date) = (2025-08-01).

확인해보면 "project_daily_statistics_b8088ecbd2" 파티션 테이블에 "2025-08-01" 관련된 파티션 키가 없다는 것이다.
아래는 gitlab admin에서 오류를 확인한 화면이다.

서버에 따라서는 파티션 테이블 - "project_daily_statistics_b8088ecbd2" 이름이 다르게 생성될 수 있으니 꼭 기억하자.
디버깅에 써먹어야한다.

디버깅

PGSQL에 접속해서 파티션 테이블을 확인해본다.

# gitlab-psql -d gitlabhq_production

아래 명령어로 파티션 테이블(project_daily_statistics_b8088ecbd2) 상태를 확인해본다.

\d+ project_daily_statistics_b8088ecbd2

gitlabhq_production=# \d+ project_daily_statistics_b8088ecbd2
                      Partitioned table "public.project_daily_statistics_b8088ecbd2"
  Column    |  Type   | Collation | Nullable | Default | Storage | Compression | Stats target | Description
-------------+---------+-----------+----------+---------+---------+-------------+--------------+-------------
id          | bigint  |           | not null |         | plain   |             |              |
project_id  | integer |           | not null |         | plain   |             |              |
fetch_count | integer |           | not null |         | plain   |             |              |
date        | date    |           | not null |         | plain   |             |              |
Partition key: RANGE (date)
Indexes:
   "project_daily_statistics_b8088ecbd2_pkey" PRIMARY KEY, btree (id, date)
   "idx_p_project_daily_statistics_on_date_and_id" btree (date, id)
   "idx_p_project_daily_statistics_on_project_id_and_date" UNIQUE, btree (project_id, date DESC)
Foreign-key constraints:
   "fk_rails_2572a8ecfe" FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
Partitions: gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202509 FOR VALUES FROM ('2025-09-01') TO ('2025-10-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202510 FOR VALUES FROM ('2025-10-01') TO ('2025-11-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202511 FOR VALUES FROM ('2025-11-01') TO ('2025-12-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202512 FOR VALUES FROM ('2025-12-01') TO ('2026-01-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202601 FOR VALUES FROM ('2026-01-01') TO ('2026-02-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202602 FOR VALUES FROM ('2026-02-01') TO ('2026-03-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202603 FOR VALUES FROM ('2026-03-01') TO ('2026-04-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202604 FOR VALUES FROM ('2026-04-01') TO ('2026-05-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202605 FOR VALUES FROM ('2026-05-01') TO ('2026-06-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202606 FOR VALUES FROM ('2026-06-01') TO ('2026-07-01')

슬프게도 "XXX_202508"이라는 연결 안되어 있다.

그러면 파티션 테이블이 "project_daily_statistics_b8088ecbd2"이니 테이블은 "project_daily_statistics_b8088ecbd2_202508" 테이블로 해당 테이블이 있는지
아래 명령어로 확인한다.

\d+ gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202508

슬프게도 테이블이 있는 것이 확인된다면... 테이블이 생성되어 있으나, 파티션 테이블과 연결이 않된 것이다.

아래 명령어로 테이블을 연결한다.

ALTER TABLE project_daily_statistics_b8088ecbd2
ATTACH PARTITION gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202508
FOR VALUES FROM ('2025-08-01') TO ('2025-09-01');

그리고 파티션 테이블이 잘연결되었는지 다시 확인해본다.

\d+ project_daily_statistics_b8088ecbd2

아래 결과와 같이 나온다면 정상이다.

gitlabhq_production=# \d+ project_daily_statistics_b8088ecbd2
                      Partitioned table "public.project_daily_statistics_b8088ecbd2"
  Column    |  Type   | Collation | Nullable | Default | Storage | Compression | Stats target | Description
-------------+---------+-----------+----------+---------+---------+-------------+--------------+-------------
id          | bigint  |           | not null |         | plain   |             |              |
project_id  | integer |           | not null |         | plain   |             |              |
fetch_count | integer |           | not null |         | plain   |             |              |
date        | date    |           | not null |         | plain   |             |              |
Partition key: RANGE (date)
Indexes:
   "project_daily_statistics_b8088ecbd2_pkey" PRIMARY KEY, btree (id, date)
   "idx_p_project_daily_statistics_on_date_and_id" btree (date, id)
   "idx_p_project_daily_statistics_on_project_id_and_date" UNIQUE, btree (project_id, date DESC)
Foreign-key constraints:
   "fk_rails_2572a8ecfe" FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
Partitions: gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202508 FOR VALUES FROM ('2025-08-01') TO ('2025-09-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202509 FOR VALUES FROM ('2025-09-01') TO ('2025-10-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202510 FOR VALUES FROM ('2025-10-01') TO ('2025-11-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202511 FOR VALUES FROM ('2025-11-01') TO ('2025-12-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202512 FOR VALUES FROM ('2025-12-01') TO ('2026-01-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202601 FOR VALUES FROM ('2026-01-01') TO ('2026-02-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202602 FOR VALUES FROM ('2026-02-01') TO ('2026-03-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202603 FOR VALUES FROM ('2026-03-01') TO ('2026-04-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202604 FOR VALUES FROM ('2026-04-01') TO ('2026-05-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202605 FOR VALUES FROM ('2026-05-01') TO ('2026-06-01'),
           gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202606 FOR VALUES FROM ('2026-06-01') TO ('2026-07-01')

이제 gitlab을 reconfigure 해주고 재시작한다. (테이블 파티션 연동 작업 - ALTER만 해줘도 Fail된 작업이 정상 동작한다.)

# gitlab-ctl reconfigure
# gitlab-ctl restart

이제 admin의 Background migration 메뉴에서 실패한 job을 다시 시작해준다..

해보면 금방 끝난다.

gitlab 버그 리포트에 대한 진행사항은 아래 issue로 진행되는 것으로 확인된다.
https://gitlab.com/gitlab-org/gitlab/-/merge_requests/214766

BackfillPartitionedProjectDailyStatistics 작업이 오래 걸리거나, 다음 버전으로 업그레이드 시에도
"gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202508" 테이블에 파티션 테이블에
매핑이 삭제되는 경우가 있다 이런 경우 오류가 발생된다.
2025년 12월 이후 업그레이드하는 경우, "background job"에서 해당 테이블을 파티션에서 삭제하는 job에 cron으로 실행되고 있다.
해당 job을 찾아서 비활성화가 귀찮아서 아래 스크립트를 실행해서 작업 동안 보정해줬다.

while true
do
	date
	if [ $(gitlab-psql -d gitlabhq_production -c '\d+ project_daily_statistics_b8088ecbd2' | grep 2025-08-01 | wcl -l) -eq 1 ]; then
		echo "found table - project_daily_statistics_b8088ecbd2_202508 in partition table"
	else
		echo "Not Found Table in Partition Table"
		gitlab-psql -d gitlabhq_production -c "ALTER TABLE project_daily_statistics_b8088ecbd2 ATTACH PARTITION gitlab_partitions_dynamic.project_daily_statistics_b8088ecbd2_202508 FOR VALUES FROM ('2025-08-01') TO ('2025-09-01');"
	fi
	sleep 60
done

T.T

Search

gitlab v18.5.3 업그레이드 후, Background migrations - BackfillPartitionedProjectDailyStatistics: project_daily_statistics 실패 처리