Commit 99bdd21e authored by Toon Claes's avatar Toon Claes

Document guidelines on commit schema changes

The piece on schema changes was quite outdated, so I've replaced it
with the new guidelines and the use of `bin/regenerate-schema`.
parent 9615ae8f
......@@ -74,12 +74,12 @@ the following preparations into account.
#### Preparation when adding migrations
- Ensure `db/structure.sql` is updated.
- Ensure `db/structure.sql` is updated as [documented](migration_style_guide.md#schema-changes).
- Make migrations reversible by using the `change` method or include a `down` method when using `up`.
- Include either a rollback procedure or describe how to rollback changes.
- Add the output of both migrating and rolling back for all migrations into the MR description
- Ensure the down method reverts the changes in `db/structure.sql`
- Update the migration output whenever you modify the migrations during the review process
- Add the output of both migrating and rolling back for all migrations into the MR description.
- Ensure the down method reverts the changes in `db/structure.sql`.
- Update the migration output whenever you modify the migrations during the review process.
- Add tests for the migration in `spec/migrations` if necessary. See [Testing Rails migrations at GitLab](testing_guide/testing_migrations_guide.md) for more details.
- When [high-traffic](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/migration_helpers.rb#L12) tables are involved in the migration, use the [`with_lock_retries`](migration_style_guide.md#retry-mechanism-when-acquiring-database-locks) helper method. Review the relevant [examples in our documentation](migration_style_guide.md#examples) for use cases and solutions.
- Ensure RuboCop checks are not disabled unless there's a valid reason to.
......
......@@ -35,9 +35,29 @@ and post-deployment migrations (`db/post_migrate`) are run after the deployment
## Schema Changes
Migrations that make changes to the database schema (e.g. adding a column) can
only be added in the monthly release, patch releases may only contain data
migrations _unless_ schema changes are absolutely required to solve a problem.
Changes to the schema should be commited to `db/structure.sql`. This
file is automatically generated by Rails, so you normally should not
edit this file by hand. If your migration is adding a column to a
table, that column will be added at the bottom. Please do not reorder
columns manually for existing tables as this will cause confusing to
other people using `db/structure.sql` generated by Rails.
When your local database in your GDK is diverging from the schema from
`master` it might be hard to cleanly commit the schema changes to
Git. In that case you can use the `script/regenerate-schema` script to
regenerate a clean `db/structure.sql` for the migrations you're
adding. This script will apply all migrations found in `db/migrate`
or `db/post_migrate`, so if there are any migrations you don't want to
commit to the schema, rename or remove them. If your branch is not
targetting `master` you can set the `TARGET` environment variable.
```sh
# Regenerate schema against `master`
bin/regenerate-schema
# Regenerate schema against `12-9-stable-ee`
TARGET=12-9-stable-ee bin/regenerate-schema
```
## What Requires Downtime?
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment