Merge branch '357191-aqualls-move-db-pages' into 'master'

Update inbound links to page

See merge request gitlab-org/gitlab!84530

doc/architecture/blueprints/container_registry_metadata_database/index.md

@@ -150,7 +150,7 @@ Following the GitLab [Go standards and style guidelines](../../../development/go
 
 The design and development of the registry database adhere to the GitLab [database guidelines](../../../development/database/). Being a Go application, the required tooling to support the database will have to be developed, such as for running database migrations.
 
-Running *online* and [*post deployment*](../../../development/post_deployment_migrations.md) migrations is already supported by the registry CLI, as described in the [documentation](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs-gitlab/database-migrations.md).
+Running *online* and [*post deployment*](../../../development/database/post_deployment_migrations.md) migrations is already supported by the registry CLI, as described in the [documentation](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs-gitlab/database-migrations.md).
 
 #### Partitioning
 

doc/development/code_review.md

@@ -615,9 +615,9 @@ Enterprise Edition instance. This has some implications:
       migration on the staging environment if you aren't sure.
    1. Categorized correctly:
       - Regular migrations run before the new code is running on the instance.
-      - [Post-deployment migrations](post_deployment_migrations.md) run _after_
+      - [Post-deployment migrations](database/post_deployment_migrations.md) run _after_
         the new code is deployed, when the instance is configured to do that.
-      - [Background migrations](background_migrations.md) run in Sidekiq, and
+      - [Background migrations](database/background_migrations.md) run in Sidekiq, and
         should only be done for migrations that would take an extreme amount of
         time at GitLab.com scale.
 1. **Sidekiq workers** [cannot change in a backwards-incompatible way](sidekiq/compatibility_across_updates.md):

doc/development/database/add_foreign_key_to_existing_column.md

@@ -123,7 +123,7 @@ end
 Validating the foreign key scans the whole table and makes sure that each relation is correct.
 
 NOTE:
-When using [background migrations](../background_migrations.md), foreign key validation should happen in the next GitLab release.
+When using [background migrations](background_migrations.md), foreign key validation should happen in the next GitLab release.
 
 Migration file for validating the foreign key:
 

doc/development/avoiding_downtime_in_migrations.md → doc/development/database/avoiding_downtime_in_migrations.md

@@ -151,9 +151,9 @@ the whole column type.
 
 You can check the following guides for each specific use case:
 
-- [Adding foreign-key constraints](migration_style_guide.md#adding-foreign-key-constraints)
-- [Adding `NOT NULL` constraints](database/not_null_constraints.md)
-- [Adding limits to text columns](database/strings_and_the_text_data_type.md)
+- [Adding foreign-key constraints](../migration_style_guide.md#adding-foreign-key-constraints)
+- [Adding `NOT NULL` constraints](not_null_constraints.md)
+- [Adding limits to text columns](strings_and_the_text_data_type.md)
 
 ## Changing Column Types
 
@@ -240,7 +240,7 @@ migrations](background_migrations.md#cleaning-up).
 Adding indexes does not require downtime when `add_concurrent_index`
 is used.
 
-See also [Migration Style Guide](migration_style_guide.md#adding-indexes)
+See also [Migration Style Guide](../migration_style_guide.md#adding-indexes)
 for more information.
 
 ## Dropping Indexes
@@ -265,7 +265,7 @@ If the table and the ActiveRecord model is not in use yet, removing the old
 table and creating a new one is the preferred way to "rename" the table.
 
 Renaming a table is possible without downtime by following our multi-release
-[rename table process](database/rename_database_tables.md#rename-table-without-downtime).
+[rename table process](rename_database_tables.md#rename-table-without-downtime).
 
 ## Adding Foreign Keys
 
@@ -355,7 +355,7 @@ Check how the migration is performing while it's running. Multiple ways to do th
 
 #### High-level status of batched background migrations
 
-See how to [check the status of batched background migrations](../update/index.md#checking-for-background-migrations-before-upgrading).
+See how to [check the status of batched background migrations](../../update/index.md#checking-for-background-migrations-before-upgrading).
 
 #### Query the database
 

doc/development/background_migrations.md → doc/development/database/background_migrations.md

@@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # Background migrations
 
 Background migrations should be used to perform data migrations whenever a
-migration exceeds [the time limits in our guidelines](migration_style_guide.md#how-long-a-migration-should-take). For example, you can use background
+migration exceeds [the time limits in our guidelines](../migration_style_guide.md#how-long-a-migration-should-take). For example, you can use background
 migrations to migrate data that's stored in a single JSON column
 to a separate table instead.
 
@@ -17,9 +17,9 @@ migrations automatically reschedule themselves for a later point in time.
 ## When To Use Background Migrations
 
 You should use a background migration when you migrate _data_ in tables that have
-so many rows that the process would exceed [the time limits in our guidelines](migration_style_guide.md#how-long-a-migration-should-take) if performed using a regular Rails migration.
+so many rows that the process would exceed [the time limits in our guidelines](../migration_style_guide.md#how-long-a-migration-should-take) if performed using a regular Rails migration.
 
-- Background migrations should be used when migrating data in [high-traffic tables](migration_style_guide.md#high-traffic-tables).
+- Background migrations should be used when migrating data in [high-traffic tables](../migration_style_guide.md#high-traffic-tables).
 - Background migrations may also be used when executing numerous single-row queries
 for every item on a large dataset. Typically, for single-record patterns, runtime is
 largely dependent on the size of the dataset, hence it should be split accordingly
@@ -63,7 +63,7 @@ integrity is guaranteed.
 
 All the background migration classes for EE-only features should be present in GitLab CE.
 For this purpose, an empty class can be created for GitLab CE, and it can be extended for GitLab EE
-as explained in the [guidelines for implementing Enterprise Edition features](ee_features.md#code-in-libgitlabbackground_migration).
+as explained in the [guidelines for implementing Enterprise Edition features](../ee_features.md#code-in-libgitlabbackground_migration).
 
 ## How It Works
 
@@ -168,7 +168,7 @@ roughly be as follows:
             the `delete_tracking_jobs: false` parameter.
    1. Remove the old column.
 
-This may also require a bump to the [import/export version](../user/project/settings/import_export.md), if
+This may also require a bump to the [import/export version](../../user/project/settings/import_export.md), if
 importing a project from a prior version of GitLab requires the data to be in
 the new format.
 
@@ -298,7 +298,7 @@ It is required to write tests for:
 The `:migration` and `schema: :latest` RSpec tags are automatically set for
 background migration specs.
 See the
-[Testing Rails migrations](testing_guide/testing_migrations_guide.md#testing-a-non-activerecordmigration-class)
+[Testing Rails migrations](../testing_guide/testing_migrations_guide.md#testing-a-non-activerecordmigration-class)
 style guide.
 
 Keep in mind that `before` and `after` RSpec hooks are going
@@ -359,9 +359,9 @@ A strategy to make the migration run faster is to schedule larger batches, and t
 within the background migration to perform multiple statements.
 
 The background migration helpers that queue multiple jobs such as
-`queue_background_migration_jobs_by_range_at_intervals` use [`EachBatch`](iterating_tables_in_batches.md).
+`queue_background_migration_jobs_by_range_at_intervals` use [`EachBatch`](../iterating_tables_in_batches.md).
 The example above has batches of 1000, where each queued job takes two seconds. If the query has been optimized
-to make the time for the delete statement within the [query performance guidelines](query_performance.md),
+to make the time for the delete statement within the [query performance guidelines](../query_performance.md),
 1000 may be the largest number of records that can be deleted in a reasonable amount of time.
 
 The minimum and most common interval for delaying jobs is two minutes. This results in two seconds

doc/development/database/database_reviewer_guidelines.md

@@ -70,7 +70,7 @@ Finally, you can find various guides in the [Database guides](index.md) page tha
 topics and use cases. The most frequently required during database reviewing are the following:
 
 - [Migrations style guide](../migration_style_guide.md) for creating safe SQL migrations.
-- [Avoiding downtime in migrations](../avoiding_downtime_in_migrations.md).
+- [Avoiding downtime in migrations](avoiding_downtime_in_migrations.md).
 - [SQL guidelines](../sql.md) for working with SQL queries.
 - [Guidelines for JiHu contributions with database migrations](https://about.gitlab.com/handbook/ceo/chief-of-staff-team/jihu-support/jihu-database-change-process.html)
 

doc/development/database/index.md

@@ -23,14 +23,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 ## Migrations
 
-- [Avoiding downtime in migrations](../avoiding_downtime_in_migrations.md)
+- [Avoiding downtime in migrations](avoiding_downtime_in_migrations.md)
 - [SQL guidelines](../sql.md) for working with SQL queries
 - [Migrations style guide](../migration_style_guide.md) for creating safe SQL migrations
 - [Testing Rails migrations](../testing_guide/testing_migrations_guide.md) guide
-- [Post deployment migrations](../post_deployment_migrations.md)
-- [Background migrations](../background_migrations.md)
+- [Post deployment migrations](post_deployment_migrations.md)
+- [Background migrations](background_migrations.md)
 - [Swapping tables](../swapping_tables.md)
-- [Deleting migrations](../deleting_migrations.md)
+- [Deleting migrations](deleting_migrations.md)
 - [Partitioning tables](table_partitioning.md)
 
 ## Debugging

doc/development/database/loose_foreign_keys.md

@@ -191,7 +191,7 @@ ci_pipelines:
 ### Track record changes
 
 To know about deletions in the `projects` table, configure a `DELETE` trigger
-using a [post-deployment migration](../post_deployment_migrations.md). The
+using a [post-deployment migration](post_deployment_migrations.md). The
 trigger needs to be configured only once. If the model already has at least one
 `loose_foreign_key` definition, then this step can be skipped:
 
@@ -226,7 +226,7 @@ ON DELETE CASCADE;
 
 The migration must run after the `DELETE` trigger is installed and the loose
 foreign key definition is deployed. As such, it must be a [post-deployment
-migration](../post_deployment_migrations.md) dated after the migration for the
+migration](post_deployment_migrations.md) dated after the migration for the
 trigger. If the foreign key is deleted earlier, there is a good chance of
 introducing data inconsistency which needs manual cleanup:
 

doc/development/database/not_null_constraints.md

@@ -197,7 +197,7 @@ end
 
 If you have to clean up a nullable column for a [high-traffic table](../migration_style_guide.md#high-traffic-tables)
 (for example, the `artifacts` in `ci_builds`), your background migration will go on for a while and
-it will need an additional [background migration cleaning up](../background_migrations.md#cleaning-up)
+it will need an additional [background migration cleaning up](background_migrations.md#cleaning-up)
 in the release after adding the data migration.
 
 In that rare case you will need 3 releases end-to-end:

doc/development/database/rename_database_tables.md

@@ -82,7 +82,7 @@ when naming indexes, so there is a possibility that not all indexes are properly
 the migration locally, check if there are inconsistently named indexes (`db/structure.sql`). Those can be
 renamed manually in a separate migration, which can be also part of the release M.N+1.
 - Foreign key columns might still contain the old table name. For smaller tables, follow our [standard column
-rename process](../avoiding_downtime_in_migrations.md#renaming-columns)
+rename process](avoiding_downtime_in_migrations.md#renaming-columns)
 - Avoid renaming database tables which are using with triggers.
 - Table modifications (add or remove columns) are not allowed during the rename process, please make sure that all changes to the table happen before the rename migration is started (or in the next release).
 - As the index names might change, verify that the model does not use bulk insert

doc/development/database/strings_and_the_text_data_type.md

@@ -229,7 +229,7 @@ end
 
 To keep this guide short, we skipped the definition of the background migration and only
 provided a high level example of the post-deployment migration that is used to schedule the batches.
-You can find more information on the guide about [background migrations](../background_migrations.md)
+You can find more information on the guide about [background migrations](background_migrations.md)
 
 #### Validate the text limit (next release)
 
@@ -277,7 +277,7 @@ end
 
 If you have to clean up a text column for a really [large table](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3)
 (for example, the `artifacts` in `ci_builds`), your background migration will go on for a while and
-it will need an additional [background migration cleaning up](../background_migrations.md#cleaning-up)
+it will need an additional [background migration cleaning up](background_migrations.md#cleaning-up)
 in the release after adding the data migration.
 
 In that rare case you will need 3 releases end-to-end:

doc/development/database/table_partitioning.md

@@ -214,7 +214,7 @@ end
 ```
 
 This step uses the same mechanism as any background migration, so you
-may want to read the [Background Migration](../background_migrations.md)
+may want to read the [Background Migration](background_migrations.md)
 guide for details on that process. Background jobs are scheduled every
 2 minutes and copy `50_000` records at a time, which can be used to
 estimate the timing of the background migration portion of the

doc/development/database_review.md

@@ -125,7 +125,7 @@ the following preparations into account.
 test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slack channel and add the execution time to the MR description:
   - Execution time largely varies between `#database-lab` and GitLab.com, but an elevated execution time from `#database-lab`
     can give a hint that the execution on GitLab.com will also be considerably high.
-  - If the execution from `#database-lab` is longer than `1h`, the index should be moved to a [post-migration](post_deployment_migrations.md).
+  - If the execution from `#database-lab` is longer than `1h`, the index should be moved to a [post-migration](database/post_deployment_migrations.md).
     Keep in mind that in this case you may need to split the migration and the application changes in separate releases to ensure the index
     will be in place when the code that needs it will be deployed.
 - Manually trigger the [database testing](database/database_migration_pipeline.md) job (`db:gitlabcom-database-testing`) in the `test` stage.
@@ -212,7 +212,7 @@ Include in the MR description:
 
 #### Preparation when removing columns, tables, indexes, or other structures
 
-- Follow the [guidelines on dropping columns](avoiding_downtime_in_migrations.md#dropping-columns).
+- Follow the [guidelines on dropping columns](database/avoiding_downtime_in_migrations.md#dropping-columns).
 - Generally it's best practice (but not a hard rule) to remove indexes and foreign keys in a post-deployment migration.
   - Exceptions include removing indexes and foreign keys for small tables.
 - If you're adding a composite index, another index might become redundant, so remove that in the same migration.
@@ -236,8 +236,8 @@ Include in the MR description:
   - Check that the relevant version files under `db/schema_migrations` were added or removed.
   - Check queries timing (If any): In a single transaction, cumulative query time executed in a migration
     needs to fit comfortably within `15s` - preferably much less than that - on GitLab.com.
-  - For column removals, make sure the column has been [ignored in a previous release](avoiding_downtime_in_migrations.md#dropping-columns)
-- Check [background migrations](background_migrations.md):
+  - For column removals, make sure the column has been [ignored in a previous release](database/avoiding_downtime_in_migrations.md#dropping-columns)
+- Check [background migrations](database/background_migrations.md):
   - Establish a time estimate for execution on GitLab.com. For historical purposes,
     it's highly recommended to include this estimation on the merge request description.
   - If a single `update` is below than `1s` the query can be placed
@@ -250,7 +250,7 @@ Include in the MR description:
     it's suggested to treat background migrations as post migrations:
     place them in `db/post_migrate` instead of `db/migrate`. Keep in mind
     that post migrations are executed post-deployment in production.
-  - If a migration [has tracking enabled](background_migrations.md#background-jobs-tracking),
+  - If a migration [has tracking enabled](database/background_migrations.md#background-jobs-tracking),
     ensure `mark_all_as_succeeded` is called even if no work is done.
 - Check [timing guidelines for migrations](migration_style_guide.md#how-long-a-migration-should-take)
 - Check migrations are reversible and implement a `#down` method

doc/development/iterating_tables_in_batches.md

@@ -93,7 +93,7 @@ falling into an endless loop as described in following
 When dealing with data migrations the preferred way to iterate over a large volume of data is using
 `EachBatch`.
 
-A special case of data migration is a [background migration](background_migrations.md#scheduling)
+A special case of data migration is a [background migration](database/background_migrations.md#scheduling)
 where the actual data modification is executed in a background job. The migration code that
 determines the data ranges (slices) and schedules the background jobs uses `each_batch`.
 

doc/development/merge_request_performance_guidelines.md

@@ -16,7 +16,7 @@ with and agreed upon by backend maintainers and performance specialists.
 It's also highly recommended that you read the following guides:
 
 - [Performance Guidelines](performance.md)
-- [Avoiding downtime in migrations](avoiding_downtime_in_migrations.md)
+- [Avoiding downtime in migrations](database/avoiding_downtime_in_migrations.md)
 
 ## Definition
 

doc/development/migration_style_guide.md

@@ -45,14 +45,14 @@ work it needs to perform and how long it takes to complete:
    One exception is a migration that takes longer but is absolutely critical for the application to operate correctly.
    For example, you might have indices that enforce unique tuples, or that are needed for query performance in critical parts of the application. In cases where the migration would be unacceptably slow, however, a better option might be to guard the feature with a [feature flag](feature_flags/index.md)
    and perform a post-deployment migration instead. The feature can then be turned on after the migration finishes.
-1. [**Post-deployment migrations.**](post_deployment_migrations.md) These are Rails migrations in `db/post_migrate` and
+1. [**Post-deployment migrations.**](database/post_deployment_migrations.md) These are Rails migrations in `db/post_migrate` and
    run _after_ new application code has been deployed (for GitLab.com after the production deployment has finished).
    They can be used for schema changes that aren't critical for the application to operate, or data migrations that take at most a few minutes.
    Common examples for schema changes that should run post-deploy include:
      - Clean-ups, like removing unused columns.
      - Adding non-critical indices on high-traffic tables.
      - Adding non-critical indices that take a long time to create.
-1. [**Background migrations.**](background_migrations.md) These aren't regular Rails migrations, but application code that is
+1. [**Background migrations.**](database/background_migrations.md) These aren't regular Rails migrations, but application code that is
    executed via Sidekiq jobs, although a post-deployment migration is used to schedule them. Use them only for data migrations that
    exceed the timing guidelines for post-deploy migrations. Background migrations should _not_ change the schema.
 
@@ -129,13 +129,13 @@ TARGET=12-9-stable-ee scripts/regenerate-schema
 
 ## Avoiding downtime
 
-The document ["Avoiding downtime in migrations"](avoiding_downtime_in_migrations.md) specifies
+The document ["Avoiding downtime in migrations"](database/avoiding_downtime_in_migrations.md) specifies
 various database operations, such as:
 
-- [dropping and renaming columns](avoiding_downtime_in_migrations.md#dropping-columns)
-- [changing column constraints and types](avoiding_downtime_in_migrations.md#changing-column-constraints)
-- [adding and dropping indexes, tables, and foreign keys](avoiding_downtime_in_migrations.md#adding-indexes)
-- [migrating `integer` primary keys to `bigint`](avoiding_downtime_in_migrations.md#migrating-integer-primary-keys-to-bigint)
+- [dropping and renaming columns](database/avoiding_downtime_in_migrations.md#dropping-columns)
+- [changing column constraints and types](database/avoiding_downtime_in_migrations.md#changing-column-constraints)
+- [adding and dropping indexes, tables, and foreign keys](database/avoiding_downtime_in_migrations.md#adding-indexes)
+- [migrating `integer` primary keys to `bigint`](database/avoiding_downtime_in_migrations.md#migrating-integer-primary-keys-to-bigint)
 
 and explains how to perform them without requiring downtime.
 
@@ -219,7 +219,7 @@ in that limit. Singular query timings should fit within the [standard limit](que
 In case you need to insert, update, or delete a significant amount of data, you:
 
 - Must disable the single transaction with `disable_ddl_transaction!`.
-- Should consider doing it in a [Background Migration](background_migrations.md).
+- Should consider doing it in a [Background Migration](database/background_migrations.md).
 
 ## Migration helpers and versioning
 
@@ -1114,7 +1114,7 @@ by an integer. For example: `users` would turn into `users0`
 ## Using models in migrations (discouraged)
 
 The use of models in migrations is generally discouraged. As such models are
-[contraindicated for background migrations](background_migrations.md#isolation),
+[contraindicated for background migrations](database/background_migrations.md#isolation),
 the model needs to be declared in the migration.
 
 If using a model in the migrations, you should first

doc/development/scalability.md

@@ -36,7 +36,7 @@ application starts, Rails queries the database schema, caching the tables and
 column types for the data requested. Because of this schema cache, dropping a
 column or table while the application is running can produce 500 errors to the
 user. This is why we have a [process for dropping columns and other
-no-downtime changes](avoiding_downtime_in_migrations.md).
+no-downtime changes](database/avoiding_downtime_in_migrations.md).
 
 #### Multi-tenancy
 

doc/development/sidekiq/compatibility_across_updates.md

@@ -156,4 +156,4 @@ end
 
 You must rename the queue in a post-deployment migration not in a normal
 migration. Otherwise, it runs too early, before all the workers that
-schedule these jobs have stopped running. See also [other examples](../post_deployment_migrations.md#use-cases).
+schedule these jobs have stopped running. See also [other examples](../database/post_deployment_migrations.md#use-cases).

doc/raketasks/migrate_snippets.md

@@ -18,7 +18,7 @@ For each snippet:
 - A file is created in the repository, using the snippet filename.
 - The snippet is committed to the repository.
 
-GitLab performs this migration through a [Background Migration](../development/background_migrations.md)
+GitLab performs this migration through a [Background Migration](../development/database/background_migrations.md)
 when the GitLab instance is upgraded to 13.0 or a higher version.
 However, if the migration fails for any of the snippets, they must be migrated individually.
 The following Rake tasks help with that process.

doc/update/zero_downtime.md

@@ -13,7 +13,7 @@ there are the following requirements:
 - You can only upgrade one minor release at a time. So from 13.1 to 13.2, not to
    13.3. If you skip releases, database modifications may be run in the wrong
    sequence [and leave the database schema in a broken state](https://gitlab.com/gitlab-org/gitlab/-/issues/321542).
-- You have to use [post-deployment migrations](../development/post_deployment_migrations.md).
+- You have to use [post-deployment migrations](../development/database/post_deployment_migrations.md).
 - You are using PostgreSQL. Starting from GitLab 12.1, MySQL is not supported.
 - Multi-node GitLab instance. Single-node instances may experience brief interruptions
   [as services restart (Puma in particular)](#single-node-deployment).