Database development guidelines

Database Reviews

During the design phase of the feature you're working on, be mindful if you are adding any database-related changes. If you're adding or modifying a query, start looking at the explain plan early to avoid surprises late in the review phase.
If, at any time, you need help optimizing a query or understanding an explain plan, ask for assistance in #database.
If you're creating a database MR for review, check out our Database review guidelines.

It provides an introduction on database-related changes, migrations, and complex SQL queries.
If you're a database reviewer or want to become one, check out our introduction to reviewing database changes.

Tooling

Understanding EXPLAIN plans
explain.depesz.com or explain.dalibo.com for visualizing the output of EXPLAIN
pgFormatter a PostgreSQL SQL syntax beautifier
db:check-migrations job
Database migration pipeline

Migrations

Adding required stops
Avoiding downtime in migrations
Batched background migrations guidelines
Create a regular migration, including creating new models
Deleting migrations
Different types of migrations
Migrations for multiple databases
Migrations style guide for creating safe SQL migrations
Partitioning tables
Post-deployment migrations guidelines and how to create one
Running database migrations
SQL guidelines for working with SQL queries
Swapping tables
Testing Rails migrations guide
When and how to write Rails migrations tests

Debugging

Accessing the database
Resetting the database
Troubleshooting and debugging the database
Tracing the source of an SQL query:
- In Rails console using Verbose Query Logs
- Using query comments with Marginalia

Best practices

Case studies

PostgreSQL information for GitLab administrators

User information for scaling

For GitLab administrators, information about configuring PostgreSQL for scaling is available, including the major methods:

ClickHouse

Miscellaneous