Merge branch 'Alexand-clarify-db-check-migrations' into 'master'

Extend documentation about db:check-migrations

See merge request gitlab-org/gitlab!78700

doc/development/database/dbcheck-migrations-job.md

+---
+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.

doc/development/database/index.md

@@ -19,6 +19,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 - [Understanding EXPLAIN plans](../understanding_explain_plans.md)
 - [explain.depesz.com](https://explain.depesz.com/) or [explain.dalibo.com](https://explain.dalibo.com/) for visualizing the output of `EXPLAIN`
 - [pgFormatter](https://sqlformat.darold.net/) a PostgreSQL SQL syntax beautifier
+- [db:check-migrations job](dbcheck-migrations-job.md)
 
 ## Migrations
 

doc/development/database_review.md

@@ -49,7 +49,7 @@ If new migrations are introduced, in the MR **you are required to provide**:
 
 Note that we have automated tooling for
 [GitLab](https://gitlab.com/gitlab-org/gitlab) (provided by the
-`db:check-migrations` pipeline job) that provides this output for migrations on
+[`db:check-migrations`](database/dbcheck-migrations-job.md) pipeline job) that provides this output for migrations on
 ~database merge requests. You do not need to provide this information manually
 if the bot can do it for you. The bot also checks that migrations are correctly
 reversible.