1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
|
---
stage: Enablement
group: Database
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# db:check-migrations job
This job runs on the test stage of a merge request pipeline. It checks:
1. A schema dump comparison between the author's working branch and the target branch,
after executing a rollback of your new migrations. This check validates that the
schema properly resets to what it was before executing this new migration.
1. A schema dump comparison between the author's working branch and the `db/structure.sql`
file that the author committed. This check validates that it contains all the expected changes
in the migration.
1. A Git diff between the `db/schema_migrations` that the author committed and the
one that the script generated after running migrations. This check validates that everything
was properly committed.
## Troubleshooting
### False positives
This job is allowed to fail, because it can throw some false positives.
For example, when we drop a column and then roll back, this column is always
re-added at the end of the list of columns. If the column was previously in
the middle of the list, the rollback can't return the schema back exactly to
its previous state. The job fails, but it's an acceptable situation.
For a real-life example, refer to
[this failed job](https://gitlab.com/gitlab-org/gitlab/-/jobs/2006544972#L138).
Here, the author dropped the `position` column.
### Schema dump comparison fails after rollback
This failure often happens if your working branch is behind the target branch.
A real scenario:
```mermaid
graph LR
Main((main<br>commit A)) ===> |remove constraint<br>fk_rails_dbebdaa8fe| MainB((main<br>commit B))
Main((main<br>commit A)) --> |checkout<br>dev| DevA((dev<br>commit A)):::dev
DevA((dev<br>commit A)) --> |add column<br>dependency_proxy_size| DevC((dev<br>commit C)):::dev
DevC -.-> |CI pipeline<br>executes| JOB-FAILED((JOB FAILED!)):::error
classDef main fill:#f4f0ff,stroke:#7b58cf
classDef dev fill:#e9f3fc,stroke:#1f75cb
classDef error fill:#f15146,stroke:#d4121a
```
1. You check out the `dev` working branch from the `main` target branch. At this point,
each branch has their `HEAD` at commit A.
1. Someone works on the `main` branch and drops the `fk_rails_dbebdaa8fe` constraint,
thus creating commit B on `main`.
1. You add column `dependency_proxy_size` to your `dev` branch.
1. The `db:check-migrations` job fails for your `dev` branch's CI/CD pipeline, because
the `structure.sql` file did not rollback to its expected state.
This happened because branch `dev` contained commits A and C, not B. Its database schema
did not know about the removal of the `fk_rails_dbebdaa8fe` constraint. When comparing the two
schemas, the `dev` branch contained this constraint while the `main` branch didn't.
This example really happened. Read the [job failure logs](https://gitlab.com/gitlab-org/gitlab/-/jobs/1992050890).
To fix these kind of issues, rebase the working branch onto the target branch to get the latest changes.
|
