diff --git a/doc/development/database/adding_database_indexes.md b/doc/development/database/adding_database_indexes.md index 6a401c804f5e1c14fb607c22c5fbea8143af0c07..e1d5a7af6d96768c0a0ec76480c6895f77e7e4d9 100644 --- a/doc/development/database/adding_database_indexes.md +++ b/doc/development/database/adding_database_indexes.md @@ -294,16 +294,14 @@ end ### Verify the MR was deployed and the index exists in production -You can verify if the post-deploy migration was executed on GitLab.com by: - -- Executing `/chatops run auto_deploy status <merge_sha>`. If the output returns `db/gprd`, - the post-deploy migration has been executed in the production database. More details in this - [guide](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/post_deploy_migration/readme.md#how-to-determine-if-a-post-deploy-migration-has-been-executed-on-gitlabcom). -- Use a meta-command in #database-lab, such as: `\d <index_name>`. - - Ensure that the index is not [`invalid`](https://www.postgresql.org/docs/12/sql-createindex.html#:~:text=The%20psql%20%5Cd%20command%20will%20report%20such%20an%20index%20as%20INVALID). -- Ask someone in #database to check if the index exists. -- With proper access, you can also verify directly on production or in a - production clone. +1. Verify that the post-deploy migration was executed on GitLab.com using ChatOps with + `/chatops run auto_deploy status <merge_sha>`. If the output returns `db/gprd`, + the post-deploy migration has been executed in the production database. For more information, see + [How to determine if a post-deploy migration has been executed on GitLab.com](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/post_deploy_migration/readme.md#how-to-determine-if-a-post-deploy-migration-has-been-executed-on-gitlabcom). +1. In the case of an [index created asynchronously](#schedule-the-index-to-be-created), wait + until the next week so that the index can be created over a weekend. +1. Use [Database Lab](database_lab.md) to check [if creation was successful](database_lab.md#checking-indexes). + Ensure the output does not indicate the index is `invalid`. ### Add a migration to create the index synchronously @@ -394,15 +392,15 @@ You must test the database index changes locally before creating a merge request ### Verify the MR was deployed and the index no longer exists in production -You can verify if the MR was deployed to GitLab.com with -`/chatops run auto_deploy status <merge_sha>`. To verify the existence of -the index, you can: - -- Use a meta-command in `#database-lab`, for example: `\d <index_name>`. -- Make sure the index no longer exists -- Ask someone in `#database` to check if the index exists. -- If you have access, you can verify directly on production or in a - production clone. +1. Verify that the post-deploy migration was executed on GitLab.com using ChatOps with + `/chatops run auto_deploy status <merge_sha>`. If the output returns `db/gprd`, + the post-deploy migration has been executed in the production database. For more information, see + [How to determine if a post-deploy migration has been executed on GitLab.com](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/post_deploy_migration/readme.md#how-to-determine-if-a-post-deploy-migration-has-been-executed-on-gitlabcom). +1. In the case of an [index removed asynchronously](#schedule-the-index-to-be-removed), wait + until the next week so that the index can be created over a weekend. +1. Use Database Lab [to check if removal was successful](database_lab.md#checking-indexes). + [Database Lab](database_lab.md) + should report an error when trying to find the removed index. If not, the index may still exist. ### Add a migration to destroy the index synchronously diff --git a/doc/development/database/database_lab.md b/doc/development/database/database_lab.md index b60091fa37c35d77736f07bb39cddb87a309c278..162fc597cc4e84b8080ad19057ab9c5ae6ca89a2 100644 --- a/doc/development/database/database_lab.md +++ b/doc/development/database/database_lab.md @@ -75,6 +75,45 @@ the new index. `exec` does not return any results, only the time required to exe After many changes, such as after a destructive query or an ineffective index, you must start over. To reset your designated clone, run `reset`. +#### Checking indexes + +Use Database Lab to check the status of an index with the meta-command `\d <index_name>`. + +Caveats: + +- Indexes are created in both the `main` and `ci` databases, so be sure to use the instance + that matches the table's `gitlab_schema`. For example, if the index is added to + [`ci_builds`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/db/docs/ci_builds.yml#L14), + use `gitlab-production-ci`. +- Database Lab typically has a small delay of a few hours. If more up-to-date information + is required, you can instead request access to a replica [via Teleport](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/Teleport/Connect_to_Database_Console_via_Teleport.md) + +For example: `\d index_design_management_designs_on_project_id` produces: + +```plaintext +Index "public.index_design_management_designs_on_project_id" + Column | Type | Key? | Definition +------------+---------+------+------------ + project_id | integer | yes | project_id +btree, for table "public.design_management_designs" +``` + +In the case of an invalid index, the output ends with `invalid`, like: + +```plaintext +Index "public.index_design_management_designs_on_project_id" + Column | Type | Key? | Definition +------------+---------+------+------------ + project_id | integer | yes | project_id +btree, for table "public.design_management_designs", invalid +``` + +If the index doesn't exist, JoeBot throws an error like: + +```plaintext +ERROR: psql error: psql:/tmp/psql-query-932227396:1: error: Did not find any relation named "no_index". +``` + ### Migration testing For information on testing migrations, review our