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

144 lines
7.1 KiB
Markdown
Raw Normal View History

2022-08-27 11:52:29 +05:30
---
stage: Data Stores
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
2022-08-27 11:52:29 +05:30
---
# Database Dictionary
This page documents the database schema for GitLab, so data analysts and other groups can
locate the feature categories responsible for specific database tables.
## Location
2023-03-04 22:38:38 +05:30
Database dictionary metadata files are stored in the `gitlab` project under `db/docs/` for the `main` and `ci` databases.
2023-07-09 08:55:56 +05:30
For the `embedding` database, the dictionary files are stored under `ee/db/embedding/docs/`.
For the `geo` database, the dictionary files are stored under `ee/db/geo/docs/`.
2022-08-27 11:52:29 +05:30
## Example dictionary file
```yaml
2023-03-17 16:20:25 +05:30
----
2022-08-27 11:52:29 +05:30
table_name: terraform_states
classes:
- Terraform::State
feature_categories:
- infrastructure_as_code
description: Represents a Terraform state backend
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26619
milestone: '13.0'
2023-05-27 22:25:52 +05:30
gitlab_schema: gitlab_main
2022-08-27 11:52:29 +05:30
```
2023-03-17 16:20:25 +05:30
## Adding tables
2022-08-27 11:52:29 +05:30
2023-03-17 16:20:25 +05:30
### Schema
2022-08-27 11:52:29 +05:30
2023-03-17 16:20:25 +05:30
| Attribute | Type | Required | Description |
|----------------------------|---------------|----------|-------------|
| `table_name` | String | yes | Database table name. |
| `classes` | Array(String) | no | List of classes that are associated to this table. |
| `feature_categories` | Array(String) | yes | List of feature categories using this table. |
| `description` | String | no | Text description of the information stored in the table, and its purpose. |
| `introduced_by_url` | URL | no | URL to the merge request or commit which introduced this table. |
| `milestone` | String | no | The milestone that introduced this table. |
| `gitlab_schema` | String | yes | GitLab schema name. |
2022-08-27 11:52:29 +05:30
2023-03-17 16:20:25 +05:30
### Process
2022-08-27 11:52:29 +05:30
2023-03-17 16:20:25 +05:30
When adding a table, you should:
1. Create a new file for this table in the appropriate directory:
- `gitlab_main` table: `db/docs/`
- `gitlab_ci` table: `db/docs/`
- `gitlab_shared` table: `db/docs/`
2023-07-09 08:55:56 +05:30
- `gitlab_embedding` table: `ee/db/embedding/docs/`
- `gitlab_geo` table: `ee/db/geo/docs/`
2023-03-17 16:20:25 +05:30
1. Name the file `<table_name>.yml`, and include as much information as you know about the table.
1. Include this file in the commit with the migration that creates the table.
2022-08-27 11:52:29 +05:30
## Dropping tables
2023-03-17 16:20:25 +05:30
### Schema
| Attribute | Type | Required | Description |
|----------------------------|---------------|----------|-------------|
| `table_name` | String | yes | Database table name. |
| `classes` | Array(String) | no | List of classes that are associated to this table. |
| `feature_categories` | Array(String) | yes | List of feature categories using this table. |
| `description` | String | no | Text description of the information stored in the table, and its purpose. |
| `introduced_by_url` | URL | no | URL to the merge request or commit which introduced this table. |
| `milestone` | String | no | The milestone that introduced this table. |
| `gitlab_schema` | String | yes | GitLab schema name. |
| `removed_by_url` | String | yes | URL to the merge request or commit which removed this table. |
| `removed_in_milestone` | String | yes | The milestone that removes this table. |
### Process
When dropping a table, you should:
1. Move the dictionary file for this table to the `deleted_tables` directory:
- `gitlab_main` table: `db/docs/deleted_tables/`
- `gitlab_ci` table: `db/docs/deleted_tables/`
- `gitlab_shared` table: `db/docs/deleted_tables/`
2023-07-09 08:55:56 +05:30
- `gitlab_embedding` table: `ee/db/embedding/docs/deleted_tables/`
- `gitlab_geo` table: `ee/db/geo/docs/deleted_tables/`
2023-03-17 16:20:25 +05:30
1. Add the fields `removed_by_url` and `removed_in_milestone` to the dictionary file.
1. Include this change in the commit with the migration that drops the table.
2023-03-04 22:38:38 +05:30
## Adding views
2023-03-17 16:20:25 +05:30
### Schema
| Attribute | Type | Required | Description |
|----------------------------|---------------|----------|-------------|
| `table_name` | String | yes | Database view name. |
| `classes` | Array(String) | no | List of classes that are associated to this view. |
| `feature_categories` | Array(String) | yes | List of feature categories using this view. |
| `description` | String | no | Text description of the information stored in the view, and its purpose. |
| `introduced_by_url` | URL | no | URL to the merge request or commit which introduced this view. |
| `milestone` | String | no | The milestone that introduced this view. |
| `gitlab_schema` | String | yes | GitLab schema name. |
### Process
2023-03-04 22:38:38 +05:30
When adding a new view, you should:
1. Create a new file for this view in the appropriate directory:
2023-03-17 16:20:25 +05:30
- `gitlab_main` view: `db/docs/views/`
- `gitlab_ci` view: `db/docs/views/`
- `gitlab_shared` view: `db/docs/views/`
2023-07-09 08:55:56 +05:30
- `gitlab_embedding` view: `ee/db/embedding/docs/views/`
- `gitlab_geo` view: `ee/db/geo/docs/views/`
2023-03-04 22:38:38 +05:30
1. Name the file `<view_name>.yml`, and include as much information as you know about the view.
1. Include this file in the commit with the migration that creates the view.
## Dropping views
2023-03-17 16:20:25 +05:30
## Schema
| Attribute | Type | Required | Description |
|----------------------------|---------------|----------|-------------|
| `view_name` | String | yes | Database view name. |
| `classes` | Array(String) | no | List of classes that are associated to this view. |
| `feature_categories` | Array(String) | yes | List of feature categories using this view. |
| `description` | String | no | Text description of the information stored in the view, and its purpose. |
| `introduced_by_url` | URL | no | URL to the merge request or commit which introduced this view. |
| `milestone` | String | no | The milestone that introduced this view. |
| `gitlab_schema` | String | yes | GitLab schema name. |
| `removed_by_url` | String | yes | URL to the merge request or commit which removed this view. |
| `removed_in_milestone` | String | yes | The milestone that removes this view. |
### Process
When dropping a view, you should:
1. Move the dictionary file for this table to the `deleted_views` directory:
- `gitlab_main` view: `db/docs/deleted_views/`
- `gitlab_ci` view: `db/docs/deleted_views/`
- `gitlab_shared` view: `db/docs/deleted_views/`
2023-07-09 08:55:56 +05:30
- `gitlab_embedding` view: `ee/db/embedding/docs/deleted_views/`
- `gitlab_geo` view: `ee/db/geo/docs/deleted_views/`
2023-03-17 16:20:25 +05:30
1. Add the fields `removed_by_url` and `removed_in_milestone` to the dictionary file.
1. Include this change in the commit with the migration that drops the view.