Database Review Guidelines · Gitlab 中文文檔

# Database Review Guidelines > 原文：[https://docs.gitlab.com/ee/development/database_review.html](https://docs.gitlab.com/ee/development/database_review.html) * [General process](#general-process) * [Roles and process](#roles-and-process) * [Distributing review workload](#distributing-review-workload) * [How to prepare the merge request for a database review](#how-to-prepare-the-merge-request-for-a-database-review) * [Preparation when adding migrations](#preparation-when-adding-migrations) * [Preparation when adding or modifying queries](#preparation-when-adding-or-modifying-queries) * [Preparation when adding foreign keys to existing tables](#preparation-when-adding-foreign-keys-to-existing-tables) * [Preparation when adding tables](#preparation-when-adding-tables) * [Preparation when removing columns, tables, indexes, or other structures](#preparation-when-removing-columns-tables-indexes-or-other-structures) * [How to review for database](#how-to-review-for-database) * [Timing guidelines for migrations](#timing-guidelines-for-migrations) # Database Review Guidelines[](#database-review-guidelines "Permalink") 此頁面特定于數據庫評論. 請參閱我們的[代碼審查指南](code_review.html) ，以獲取有關[代碼審查](code_review.html)的更廣泛建議和最佳實踐. ## General process[](#general-process "Permalink") A database review is required for: * 涉及數據庫架構或執行數據遷移的更改，包括以下文件： * `db/` * `lib/gitlab/background_migration/` * 對數據庫工具的更改. 例如： * `lib/gitlab/database/`遷移或 ActiveRecord 助手 * 負載均衡 * 產生 SQL 查詢的更改超出了顯而易見的范圍. 通常由合并請求的作者決定是否引入復雜查詢以及是否需要數據庫審查. 期望數據庫審閱者在更改中查找明顯復雜的查詢，并仔細檢查那些查詢. 如果作者沒有指出要審核的特定查詢，并且沒有明顯復雜的查詢，那么僅專注于審核遷移就足夠了. 最好以 SQL 形式復審查詢，并且通常要求作者翻譯 SQL 形式的任何 ActiveRecord 查詢以復審. ### Roles and process[](#roles-and-process "Permalink") 合并請求**作者**的角色是： * 確定是否需要數據庫審查. * 如果需要數據庫檢查，請添加?database 標簽. * [Prepare the merge request for a database review](#how-to-prepare-the-merge-request-for-a-database-review). 數據庫**審閱者**的角色是： * 對 MR 進行一次初審，并向作者提出改進建議. * 一旦滿意，請用?" database :: reviewed"重新標記 MR，批準，然后將 MR 重新分配給 Reviewer Roulette 建議的數據庫**維護者** . 數據庫**維護者**的作用是： * 在 MR 上執行最終數據庫審查. * 與數據庫審閱者和 MR 作者討論進一步的改進或其他相關更改. * 最后批準 MR，并使用?" database :: approved"重新標記 MR * 如果沒有其他待批準的批準，則合并 MR，或根據需要將其傳遞給其他維護者（前端，后端，文檔）. ### Distributing review workload[](#distributing-review-workload "Permalink") 使用[審閱者輪盤](code_review.html#reviewer-roulette) （ [示例](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25181#note_147551725) ）分配[審閱](code_review.html#reviewer-roulette)工作量. 然后，MR 作者應共同指派建議的數據庫**審閱者** . 當他們批準時，他們將移交給建議的數據庫**維護者** . 如果審閱者輪盤賭沒有建議數據庫審閱者和維護者，請確保已應用?database 標簽并重新運行`danger-review` CI 作業，或從[`@gl-database`團隊中](https://gitlab.com/groups/gl-database/-/group_members)選擇某人. ### How to prepare the merge request for a database review[](#how-to-prepare-the-merge-request-for-a-database-review "Permalink") 為了使審核更加輕松快捷，請考慮以下準備工作. #### Preparation when adding migrations[](#preparation-when-adding-migrations "Permalink") * 確保`db/structure.sql`已按照[記錄進行](migration_style_guide.html#schema-changes)更新. * 通過使用`change`方法使遷移可逆，或者在使用`up`時包括`down`方法. * 包括回滾過程或描述如何回滾更改. * 將所有遷移的遷移和回滾的輸出添加到 MR 描述中. * 確保 down 方法還原`db/structure.sql`的更改. * 在查看過程中，只要您修改遷移，就更新遷移輸出. * 如有必要，在`spec/migrations`添加遷移測試. 有關更多詳細信息，請參見[在 GitLab 上測試 Rails 遷移](testing_guide/testing_migrations_guide.html) . * 當遷移中涉及[高流量](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3)表時，請使用[`with_lock_retries`](migration_style_guide.html#retry-mechanism-when-acquiring-database-locks)幫助程序方法. 請查看[我們文檔中](migration_style_guide.html#examples)的相關[示例以](migration_style_guide.html#examples)獲取用例和解決方案. * Ensure RuboCop checks are not disabled unless there’s a valid reason to. * 將索引添加到[大表時](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3) ，請在`#database-lab` Slack 通道中使用`CREATE INDEX CONCURRENTLY`測試其執行，并將執行時間添加到 MR 描述中： * `#database-lab`和 GitLab.com 之間的執行時間差異很大，但是`#database-lab`執行時間增加，可能暗示 GitLab.com 上的執行量也很高. * 如果`#database-lab`的執行時間超過`1h` ，則應將索引移至[遷移后](post_deployment_migrations.html) . 請記住，在這種情況下，您可能需要將遷移和應用程序更改分為不同的版本，以確保在部署需要索引的代碼時索引就位. #### Preparation when adding or modifying queries[](#preparation-when-adding-or-modifying-queries "Permalink") * 在 MR 說明中編寫原始 SQL. 最好用[pgFormatter](https://sqlformat.darold.net)或[paste.depesz.com](https://paste.depesz.com)很好地格式化. * 在描述中包括相關查詢的`EXPLAIN (ANALYZE, BUFFERS)`輸出. 如果輸出太長，請將其包裝在`<details>`塊中，將其粘貼到 GitLab 代碼片段中，或在以下位置提供指向計劃的鏈接： [explain.depesz.com](https://explain.depesz.com) . * 提供查詢計劃時，請確保其命中足夠的數據： * 您可以通過`#database-lab` Slack 通道或[chatops](understanding_explain_plans.html#chatops)使用 GitLab 生產副本大規模測試查詢. * 通常， `gitlab-org`命名空間（ `namespace_id = 9970` ）和`gitlab-org/gitlab-foss` （ `project_id = 13083` ）或`gitlab-org/gitlab` （ `project_id = 278964` ）項目提供了足夠的數據作為一個很好的例子. * 對于查詢的變化，最好是與*前*和變更*后*的方案一起提供的 SQL 查詢. 這有助于快速發現差異. * 包括顯示性能改善的數據，最好以基準形式顯示. #### Preparation when adding foreign keys to existing tables[](#preparation-when-adding-foreign-keys-to-existing-tables "Permalink") * **在**添加外鍵**之前，**進行遷移以刪除源表中的孤立行. * 刪除所有`dependent: ...`實例`dependent: ...`可能不再需要. #### Preparation when adding tables[](#preparation-when-adding-tables "Permalink") * 根據" [訂購表列"](ordering_table_columns.html)準則[訂購列](ordering_table_columns.html) . * 將外鍵添加到指向其他表中數據的任何列，包括[index](migration_style_guide.html#adding-foreign-key-constraints) . * 為在諸如`WHERE` ， `ORDER BY` ， `GROUP BY`和`JOIN`的語句中使用的字段添加索引. #### Preparation when removing columns, tables, indexes, or other structures[](#preparation-when-removing-columns-tables-indexes-or-other-structures "Permalink") * 遵循[有關刪除列](what_requires_downtime.html#dropping-columns)的[準則](what_requires_downtime.html#dropping-columns) . * 通常，最佳實踐（但不是硬性規定）是在部署后遷移中刪除索引和外鍵. * 例外包括刪除小型表的索引和外鍵. * 如果要添加復合索引，則另一個索引可能會變得多余，因此請在同一遷移中將其刪除. 例如，添加`index(column_A, column_B, column_C)`會使索引`index(column_A, column_B)`和`index(column_A)`冗余. ### How to review for database[](#how-to-review-for-database "Permalink") * 檢查遷移 * 審查關系建模和設計選擇 * 查看遷移遵循[數據庫遷移樣式指南](migration_style_guide.html) ，例如 * [檢查列的順序](ordering_table_columns.html) * [檢查索引是否存在外鍵](migration_style_guide.html#adding-foreign-key-constraints) * 確保遷移在事務中執行，或僅包含并發索引/外鍵助手（已禁用事務） * 如果在`#database-lab`上添加了指向大表的索引，并且其執行時間增加了（超過 1h）： * 確保在遷移后將其添加. * 維護者：合并請求合并后，在`#f_upcoming_release` Slack 頻道`#f_upcoming_release`其通知發布管理器. * 檢查與`db/structure.sql`一致性，并且遷移是[可逆的](migration_style_guide.html#reversibility) * 檢查查詢時間（如果有的話）：在遷移中執行的查詢需要在 GitLab.com 上適應`15s`以內（最好比`15s`少）. * 對于列刪除，請確保[在先前版本中](what_requires_downtime.html#dropping-columns)已[忽略](what_requires_downtime.html#dropping-columns)該列 * Check [background migrations](background_migrations.html): * 建立在 GitLab.com 上執行的時間估計. 出于歷史目的，強烈建議在合并請求描述中包括此估計. * 如果單個`update`低于`1s` ，則可以將查詢直接放入常規遷移中（在`db/migrate`內部）. * 通常使用后臺遷移，但不限于： * 在較大的表中遷移數據. * 對數據集中的每條記錄進行大量 SQL 查詢. * 查看查詢（例如，確保批次大小合適） * 因為執行時間可能比常規遷移要長，所以建議將后臺遷移視為后期遷移：將它們放在`db/post_migrate`而不是`db/migrate` . 請記住，后遷移是在生產中的部署后執行的. * Check [timing guidelines for migrations](#timing-guidelines-for-migrations) * 檢查遷移是可逆的，并實現`#down`方法 * 檢查數據遷移： * 建立在 GitLab.com 上執行的時間估計. * 根據時間的不同，可以將數據遷移放在常規，部署后或后臺遷移上. * 數據遷移也應該是可逆的，或者在可能的情況下附帶有關如何逆向的描述. 這適用于所有類型的遷移（常規，部署后，后臺）. * 查詢效果 * 檢查是否有任何明顯復雜的查詢，以及作者特別指出要進行審查的查詢（如果有） * 如果尚不存在，請要求作者提供 SQL 查詢和查詢計劃（例如，通過使用[chatops](understanding_explain_plans.html#chatops)或直接數據庫訪問） * 對于給定的查詢，請查看有關數據分配的參數 * [檢查查詢計劃](understanding_explain_plans.html)并提出對查詢的改進建議（更改查詢，架構或添加索引等） * 一般準則是查詢執行時間少于 100 毫秒 * 如果查詢依賴于尚未在生產環境中進行的先前遷移（例如，索引，列），則可以使用[還原管道](https://ops.gitlab.net/gitlab-com/gl-infra/gitlab-restore/postgres-gprd)中[的一次性實例](https://ops.gitlab.net/gitlab-com/gl-infra/gitlab-restore/postgres-gprd)來建立適當的測試環境. 如果您無權訪問此項目，請訪問 Slack 上的#database 以獲取有關如何進行的建議. * 避免 N + 1 問題并最大程度地減少[查詢數](merge_request_performance_guidelines.html#query-counts) . ### Timing guidelines for migrations[](#timing-guidelines-for-migrations "Permalink") 通常，對于單個部署，GitLab.com 的遷移時間不應超過 1 個小時. 以下準則不是硬性規定，據估計，這些準則可將遷移時間降到最低. **注意：**請記住，所有運行時均應根據 GitLab.com 進行測量. | 遷移類型 | 建議執行時間 | Notes | | --- | --- | --- | | 定期遷移`db/migrate` | `3 minutes` | 一個有效的例外是創建索引，因為這可能需要很長時間. | | 在`db/post_migrate`上發布遷移 | `10 minutes` | ? | | 后臺遷移 | ?— | 由于它們適用于較大的表，因此無法設置精確的時序準則，但是，任何單個查詢的冷緩存都必須保持在`1 second`以下的執行時間. |