debian-mirror-gitlab/doc/development/database/database_reviewer_guidelines.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

107 lines
5.6 KiB
Markdown
Raw Normal View History

2021-01-03 14:25:43 +05:30
---
2022-07-23 23:45:48 +05:30
stage: Data Stores
2021-01-03 14:25:43 +05:30
group: Database
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2021-01-03 14:25:43 +05:30
---
2020-07-28 23:09:34 +05:30
# Database Reviewer Guidelines
This page includes introductory material for new database reviewers.
If you are interested in getting an application update reviewed,
check the [database review guidelines](../database_review.md).
## Scope of work done by a database reviewer
Database reviewers are domain experts who have substantial experience with databases,
`SQL`, and query performance optimization.
A database review is required whenever an application update [touches the database](../database_review.md#general-process).
The database reviewer is tasked with reviewing the database specific updates and
2021-11-11 11:23:49 +05:30
making sure that any queries or modifications perform without issues
2020-07-28 23:09:34 +05:30
at the scale of GitLab.com.
For more information on the database review process, check the [database review guidelines](../database_review.md).
## How to apply for becoming a database reviewer
2022-05-07 20:08:51 +05:30
Team members are encouraged to self-identify as database domain experts, and add it to their profile YAML file:
2020-07-28 23:09:34 +05:30
```yaml
2020-11-24 15:15:51 +05:30
projects:
gitlab:
- reviewer database
2020-07-28 23:09:34 +05:30
```
2022-05-07 20:08:51 +05:30
Create the merge request [using the "Database reviewer" template](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/.gitlab/merge_request_templates/Database%20reviewer.md),
adding your expertise your profile YAML file. Assign to a database maintainer or the
[Database Team's Engineering Manager](https://about.gitlab.com/handbook/engineering/development/enablement/database/).
2020-07-28 23:09:34 +05:30
2022-05-07 20:08:51 +05:30
After the `team.yml` update is merged, the [Reviewer roulette](../code_review.md#reviewer-roulette)
2020-07-28 23:09:34 +05:30
may recommend you as a database reviewer.
## Resources for database reviewers
As a database reviewer, join the internal `#database` Slack channel and ask questions or discuss
database related issues with other database reviewers and maintainers.
There is also an optional database office hours call held bi-weekly, alternating between
2022-07-23 23:45:48 +05:30
European/US and Asia-Pacific (APAC) friendly hours. You can join the office hours call and bring topics
2020-07-28 23:09:34 +05:30
that require a more in-depth discussion between the database reviewers and maintainers:
- [Database Office Hours Agenda](https://docs.google.com/document/d/1wgfmVL30F8SdMg-9yY6Y8djPSxWNvKmhR5XmsvYX1EI/edit).
2021-03-11 19:13:27 +05:30
- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [YouTube playlist with past recordings](https://www.youtube.com/playlist?list=PL05JrBw4t0Kp-kqXeiF7fF7cFYaKtdqXM).
2020-07-28 23:09:34 +05:30
2021-09-04 01:27:46 +05:30
You should also join the [#database-lab](../understanding_explain_plans.md#database-lab-engine)
2021-03-11 19:13:27 +05:30
Slack channel and get familiar with how to use Joe, the Slackbot that provides developers
2020-07-28 23:09:34 +05:30
with their own clone of the production database.
Understanding and efficiently using `EXPLAIN` plans is at the core of the database review process.
The following guides provide a quick introduction and links to follow on more advanced topics:
- Guide on [understanding EXPLAIN plans](../understanding_explain_plans.md).
2021-03-11 19:13:27 +05:30
- [Explaining the unexplainable series in `depesz`](https://www.depesz.com/tag/unexplainable/).
2020-07-28 23:09:34 +05:30
2021-09-30 23:02:18 +05:30
We also have licensed access to The Art of PostgreSQL available, if you are interested in getting access please check out the
[issue (confidential)](https://gitlab.com/gitlab-org/database-team/team-tasks/-/issues/23).
2020-07-28 23:09:34 +05:30
Finally, you can find various guides in the [Database guides](index.md) page that cover more specific
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.
2022-06-21 17:19:12 +05:30
- [Avoiding downtime in migrations](avoiding_downtime_in_migrations.md).
2020-07-28 23:09:34 +05:30
- [SQL guidelines](../sql.md) for working with SQL queries.
2021-11-18 22:05:49 +05:30
- [Guidelines for JiHu contributions with database migrations](https://about.gitlab.com/handbook/ceo/chief-of-staff-team/jihu-support/jihu-database-change-process.html)
2020-07-28 23:09:34 +05:30
2021-11-11 11:23:49 +05:30
## How to apply to become a database maintainer
2020-07-28 23:09:34 +05:30
Once a database reviewer feels confident on switching to a database maintainer,
they can update their [team profile](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/team.yml)
to a `trainee_maintainer database`:
```yaml
2020-11-24 15:15:51 +05:30
projects:
gitlab:
- trainee_maintainer database
2020-07-28 23:09:34 +05:30
```
The first step is to a create a [Trainee Database Maintainer Issue](https://gitlab.com/gitlab-com/www-gitlab-com/-/issues/new?issuable_template=trainee-database-maintainer).
Use and follow the process described in the 'Trainee database maintainer' template.
Note that [trainee maintainers](https://about.gitlab.com/handbook/engineering/workflow/code-review/#trainee-maintainer)
are three times as likely to be picked by the [Danger bot](../dangerbot.md) as other reviewers.
## What to do if you feel overwhelmed
Similar to all types of reviews, [unblocking others is always a top priority](https://about.gitlab.com/handbook/values/#global-optimization).
Database reviewers are expected to [review assigned merge requests in a timely manner](../code_review.md#review-turnaround-time)
or let the author know as soon as possible and help them find another reviewer or maintainer.
We are doing reviews to help the rest of the GitLab team and, at the same time, get exposed
to more use cases, get a lot of insights and hone our database and data management skills.
If you are feeling overwhelmed, think you are at capacity, and are unable to accept any more
reviews until some have been completed, communicate this through your GitLab status by setting
the `:red_circle:` emoji and mentioning that you are at capacity in the status text.