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
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2021-01-03 14:25:43 +05:30
---
2023-05-27 22:25:52 +05:30
# Database development guidelines
2020-06-23 00:09:42 +05:30
2020-07-28 23:09:34 +05:30
## Database Reviews
- If you're creating a database MR for review, check out our [Database review guidelines ](../database_review.md ).
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 ](database_reviewer_guidelines.md ).
2020-06-23 00:09:42 +05:30
## Tooling
2022-08-27 11:52:29 +05:30
- [Understanding EXPLAIN plans ](understanding_explain_plans.md )
2020-06-23 00:09:42 +05:30
- [explain.depesz.com ](https://explain.depesz.com/ ) or [explain.dalibo.com ](https://explain.dalibo.com/ ) for visualizing the output of `EXPLAIN`
2021-04-29 21:17:54 +05:30
- [pgFormatter ](https://sqlformat.darold.net/ ) a PostgreSQL SQL syntax beautifier
2022-04-04 11:22:00 +05:30
- [db:check-migrations job ](dbcheck-migrations-job.md )
2023-04-23 21:23:45 +05:30
- [Database migration pipeline ](database_migration_pipeline.md )
2020-06-23 00:09:42 +05:30
## Migrations
2023-03-17 16:20:25 +05:30
- [Adding required stops ](required_stops.md )
- [Avoiding downtime in migrations ](avoiding_downtime_in_migrations.md )
2022-08-27 11:52:29 +05:30
- [Batched background migrations guidelines ](batched_background_migrations.md )
2023-03-17 16:20:25 +05:30
- [Create a regular migration ](../migration_style_guide.md#create-a-regular-schema-migration ), including creating new models
2022-08-27 11:52:29 +05:30
- [Deleting migrations ](deleting_migrations.md )
2023-03-17 16:20:25 +05:30
- [Different types of migrations ](../migration_style_guide.md#choose-an-appropriate-migration-type )
- [Legacy background migrations guidelines ](background_migrations.md )
2022-06-21 17:19:12 +05:30
- [Migrations for multiple databases ](migrations_for_multiple_databases.md )
2020-06-23 00:09:42 +05:30
- [Migrations style guide ](../migration_style_guide.md ) for creating safe SQL migrations
2021-01-03 14:25:43 +05:30
- [Partitioning tables ](table_partitioning.md )
2023-03-17 16:20:25 +05:30
- [Post-deployment migrations guidelines ](post_deployment_migrations.md ) and [how to create one ](post_deployment_migrations.md#creating-migrations )
- [Running database migrations ](database_debugging.md#migration-wrangling )
- [SQL guidelines ](../sql.md ) for working with SQL queries
- [Swapping tables ](swapping_tables.md )
- [Testing Rails migrations ](../testing_guide/testing_migrations_guide.md ) guide
- [When and how to write Rails migrations tests ](../testing_guide/testing_migrations_guide.md )
2020-06-23 00:09:42 +05:30
## Debugging
2022-08-27 11:52:29 +05:30
- [Accessing the database ](database_debugging.md#manually-access-the-database )
2023-03-17 16:20:25 +05:30
- [Resetting the database ](database_debugging.md#delete-everything-and-start-over )
2022-08-27 11:52:29 +05:30
- [Troubleshooting and debugging the database ](database_debugging.md )
2023-03-17 16:20:25 +05:30
- Tracing the source of an SQL query:
- In Rails console using [Verbose Query Logs ](https://guides.rubyonrails.org/debugging_rails_applications.html#verbose-query-logs )
- Using query comments with [Marginalia ](database_query_comments.md )
2020-06-23 00:09:42 +05:30
## Best practices
2022-08-27 11:52:29 +05:30
- [Adding database indexes ](adding_database_indexes.md )
2020-06-23 00:09:42 +05:30
- [Adding a foreign key constraint to an existing column ](add_foreign_key_to_existing_column.md )
2023-03-17 16:20:25 +05:30
- [Check for background migrations before upgrading ](../../update/background_migrations.md )
- [Client-side connection-pool ](client_side_connection_pool.md )
- [Constraints naming conventions ](constraint_naming_convention.md )
- [Creating enums ](creating_enums.md )
- [Data layout and access patterns ](layout_and_access_patterns.md )
- [Efficient `IN` operator queries ](efficient_in_operator_queries.md )
- [Foreign keys & associations ](foreign_keys.md )
2022-08-27 11:52:29 +05:30
- [Hash indexes ](hash_indexes.md )
- [Insert into tables in batches ](insert_into_tables_in_batches.md )
2023-03-17 16:20:25 +05:30
- [Iterating tables in batches ](iterating_tables_in_batches.md )
2023-06-20 00:43:36 +05:30
- [Load balancing ](load_balancing.md )
2023-03-17 16:20:25 +05:30
- [`NOT NULL` constraints ](not_null_constraints.md )
2022-08-27 11:52:29 +05:30
- [Ordering table columns ](ordering_table_columns.md )
2021-06-08 01:23:25 +05:30
- [Pagination guidelines ](pagination_guidelines.md )
- [Pagination performance guidelines ](pagination_performance_guidelines.md )
2023-03-17 16:20:25 +05:30
- [Polymorphic associations ](polymorphic_associations.md )
- [Query count limits ](query_count_limits.md )
- [Query performance guidelines ](query_performance.md )
- [Serializing data ](serializing_data.md )
- [Single table inheritance ](single_table_inheritance.md )
- [Storing SHA1 hashes as binary ](sha1_as_binary.md )
- [Strings and the Text data type ](strings_and_the_text_data_type.md )
- [Updating multiple values ](setting_multiple_values.md )
- [Verifying database capabilities ](verifying_database_capabilities.md )
2020-06-23 00:09:42 +05:30
## Case studies
2022-08-27 11:52:29 +05:30
- [Database case study: Filtering by label ](filtering_by_label.md )
- [Database case study: Namespaces storage statistics ](namespaces_storage_statistics.md )
2021-01-29 00:20:46 +05:30
2023-03-04 22:38:38 +05:30
## PostgreSQL information for GitLab administrators
- [Configure GitLab using an external PostgreSQL service ](../../administration/postgresql/external.md )
- [Configuring PostgreSQL for scaling ](../../administration/postgresql/index.md )
- [Database Load Balancing ](../../administration/postgresql/database_load_balancing.md )
- [Moving GitLab databases to a different PostgreSQL instance ](../../administration/postgresql/moving.md )
- [Replication and failover with Omnibus GitLab ](../../administration/postgresql/replication_and_failover.md )
- [Standalone PostgreSQL using Omnibus GitLab ](../../administration/postgresql/standalone.md )
- [Troubleshooting PostgreSQL ](../../administration/troubleshooting/postgresql.md )
- [Working with the bundled PgBouncer service ](../../administration/postgresql/pgbouncer.md )
2023-04-23 21:23:45 +05:30
## User information for scaling
For GitLab administrators, information about
[configuring PostgreSQL for scaling ](../../administration/postgresql/index.md ) is available,
including the major methods:
- [Standalone PostgreSQL ](../../administration/postgresql/standalone.md )
- [External PostgreSQL instances ](../../administration/postgresql/external.md )
- [Replication and failover ](../../administration/postgresql/replication_and_failover.md )
## ClickHouse
- [Introduction ](clickhouse/index.md )
- [Optimizing query execution ](clickhouse/optimization.md )
- [Rebuild GitLab features using ClickHouse 1: Activity data ](clickhouse/gitlab_activity_data.md )
2023-05-27 22:25:52 +05:30
- [Rebuild GitLab features using ClickHouse 2: Merge Request analytics ](clickhouse/merge_request_analytics.md )
- [Tiered Storage in ClickHouse ](clickhouse/tiered_storage.md )
2023-04-23 21:23:45 +05:30
2021-01-29 00:20:46 +05:30
## Miscellaneous
- [Maintenance operations ](maintenance_operations.md )
2021-04-17 20:07:23 +05:30
- [Update multiple database objects ](setting_multiple_values.md )
