diff options
Diffstat (limited to 'doc/development/database/migrations_for_multiple_databases.md')
-rw-r--r-- | doc/development/database/migrations_for_multiple_databases.md | 35 |
1 files changed, 32 insertions, 3 deletions
diff --git a/doc/development/database/migrations_for_multiple_databases.md b/doc/development/database/migrations_for_multiple_databases.md index 0ec4612e985..ce326a6ce4a 100644 --- a/doc/development/database/migrations_for_multiple_databases.md +++ b/doc/development/database/migrations_for_multiple_databases.md @@ -33,7 +33,7 @@ Depending on the used constructs, we can classify migrations to be either: Migrations cannot mix **DDL** and **DML** changes as the application requires the structure (as described by `db/structure.sql`) to be exactly the same across all decomposed databases. -### Data Definition Language (DDL) +### Data Definition Language (DDL) The DDL migrations are all migrations that: @@ -43,7 +43,7 @@ The DDL migrations are all migrations that: 1. Add or remove a column with or without a default value (for example, `add_column`). 1. Create or drop trigger functions (for example, `create_trigger_function`). 1. Attach or detach triggers from tables (for example, `track_record_deletions`, `untrack_record_deletions`). -1. Prepare or not async indexes (for example, `prepare_async_index`, `unprepare_async_index_by_name`). +1. Prepare or not asynchronous indexes (for example, `prepare_async_index`, `unprepare_async_index_by_name`). As such DDL migrations **CANNOT**: @@ -159,7 +159,7 @@ end ### The special purpose of `gitlab_shared` -As described in [gitlab_schema](multiple_databases.md#the-special-purpose-of-gitlab_shared), +As described in [`gitlab_schema`](multiple_databases.md#the-special-purpose-of-gitlab_shared), the `gitlab_shared` tables are allowed to contain data across all databases. This implies that such migrations should run across all databases to modify structure (DDL) or modify data (DML). @@ -388,3 +388,32 @@ A Potential extension is to limit running DML migration only to specific environ ```ruby restrict_gitlab_migration gitlab_schema: :gitlab_main, gitlab_env: :gitlab_com ``` + +## Background migrations + +When you use: + +- Background migrations with `track_jobs` set to `true` or +- Batched background migrations + +The migration has to write to a jobs table. All of the +jobs tables used by background migrations are marked as `gitlab_shared`. +You can use these migrations when migrating tables in any database. + +However, when queuing the batches, you must set `restrict_gitlab_migration` based on the +table you are iterating over. If you are updating all `projects`, for example, then you would set +`restrict_gitlab_migration gitlab_schema: :gitlab_main`. If, however, you are +updating all `ci_pipelines`, you would set +`restrict_gitlab_migration gitlab_schema: :gitlab_ci`. + +As with all DML migrations, you cannot query another database outside of +`restrict_gitlab_migration` or `gitlab_shared`. If you need to query another database, +you'll likely need to separate these into two migrations somehow. + +Because the actual migration logic (not the queueing step) for background +migrations runs in a Sidekiq worker, the logic can perform DML queries on +tables in any database, just like any ordinary Sidekiq worker can. + +## How to determine `gitlab_schema` for a given table + +See [GitLab Schema](multiple_databases.md#gitlab-schema). |