데이터베이스 딕셔너리

요약

이 페이지는 GitLab의 데이터베이스 스키마를 문서화하여, 데이터 분석가 및 다른 그룹이 특정 데이터베이스 테이블을 담당하는 기능 카테고리를 찾을 수 있도록 합니다. 데이터베이스 딕셔너리 메타데이터 파일은 main, ci, sec 데이터베이스의 경우 gitlab 프로젝트의 db/docs/ 디렉터리에 저장됩니다.

이 페이지는 GitLab의 데이터베이스 스키마를 문서화하여, 데이터 분석가 및 다른 그룹이 특정 데이터베이스 테이블을 담당하는 기능 카테고리를 찾을 수 있도록 합니다.

위치#

데이터베이스 딕셔너리 메타데이터 파일은 main, ci, sec 데이터베이스의 경우 gitlab 프로젝트의 db/docs/ 디렉터리에 저장됩니다. embedding 데이터베이스의 경우 딕셔너리 파일은 ee/db/embedding/docs/에 저장됩니다. geo 데이터베이스의 경우 딕셔너리 파일은 ee/db/geo/docs/에 저장됩니다.

딕셔너리 파일 예시#

---
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'
gitlab_schema: gitlab_main_org
sharding_key:
    project_id: projects
table_size: small

테이블 추가#

스키마#

속성	타입	필수 여부	설명
table_name	String	예	데이터베이스 테이블 이름.
classes	Array(String)	아니오	이 테이블과 연관된 클래스 목록.
feature_categories	Array(String)	예	이 테이블을 사용하는 기능 카테고리 목록.
description	String	아니오	테이블에 저장된 정보와 그 목적에 대한 텍스트 설명.
introduced_by_url	URL	아니오	이 테이블을 도입한 머지 리퀘스트 또는 커밋의 URL.
milestone	String	예	이 테이블을 도입한 마일스톤.
gitlab_schema	String	예	GitLab 스키마 이름.
notes	String	아니오	코멘트 용도로 사용. Psych가 YAML 코멘트를 파싱할 수 없으므로 이 필드를 사용합니다.
table_size	String	예	GitLab.com에서의 현재 테이블 크기 분류. 1 크기에는 인덱스가 포함됩니다. 파티셔닝된 테이블의 경우 크기는 가장 큰 파티션의 크기입니다. 유효한 옵션: unknown, small (< 10 GB), medium (< 50 GB), large (< 100 GB), over_limit (100 GB 초과).
organization_transfer_support	String	조건부	sharding_key에 organization_id가 포함된 경우 필수. 조직 이전 지원을 참조하세요.
sharding_key	Hash	조건부	테이블을 조직과 연결하는 데 사용되는 칼럼을 식별합니다. 칼럼에 NOT NULL 제약 조건이 있는 경우에만 설정합니다. 샤딩 키 필드를 참조하세요.
desired_sharding_key	Hash	조건부	칼럼이 존재하지만 아직 NOT NULL 제약 조건이 없는 경우의 의도된 샤딩 키 칼럼을 식별합니다. 샤딩 키 필드를 참조하세요.

각주:

새 테이블은 데이터가 없으므로 기본적으로 small입니다. 이 속성은 매월 자동으로 업데이트됩니다.

프로세스#

테이블을 추가할 때는 다음을 수행해야 합니다:

적절한 디렉터리에 이 테이블에 대한 새 파일을 생성합니다:

gitlab_main 테이블: db/docs/

gitlab_ci 테이블: db/docs/
gitlab_sec 테이블: db/docs/
gitlab_shared 테이블: db/docs/
gitlab_embedding 테이블: ee/db/embedding/docs/
gitlab_geo 테이블: ee/db/geo/docs/
파일 이름을 <table_name>.yml로 지정하고, 테이블에 대해 알고 있는 정보를 최대한 포함시킵니다.
테이블을 생성하는 마이그레이션과 함께 이 파일을 커밋에 포함시킵니다.

테이블 삭제#

스키마#

속성	타입	필수 여부	설명
table_name	String	예	데이터베이스 테이블 이름.
classes	Array(String)	아니오	이 테이블과 연관된 클래스 목록.
feature_categories	Array(String)	예	이 테이블을 사용하는 기능 카테고리 목록.
description	String	아니오	테이블에 저장된 정보와 그 목적에 대한 텍스트 설명.
introduced_by_url	URL	아니오	이 테이블을 도입한 머지 리퀘스트 또는 커밋의 URL.
milestone	String	아니오	이 테이블을 도입한 마일스톤.
gitlab_schema	String	예	GitLab 스키마 이름.
removed_by_url	String	예	이 테이블을 제거한 머지 리퀘스트 또는 커밋의 URL.
removed_in_milestone	String	예	이 테이블을 제거하는 마일스톤.

프로세스#

테이블을 삭제할 때는 다음을 수행해야 합니다:

이 테이블의 딕셔너리 파일을 deleted_tables 디렉터리로 이동합니다:

gitlab_main 테이블: db/docs/deleted_tables/

gitlab_ci 테이블: db/docs/deleted_tables/
gitlab_sec 테이블: db/docs/deleted_tables/
gitlab_shared 테이블: db/docs/deleted_tables/
gitlab_embedding 테이블: ee/db/embedding/docs/deleted_tables/
gitlab_geo 테이블: ee/db/geo/docs/deleted_tables/
딕셔너리 파일에 removed_by_url 및 removed_in_milestone 필드를 추가합니다.
테이블을 삭제하는 마이그레이션과 함께 이 변경 사항을 커밋에 포함시킵니다.

뷰 추가#

스키마#

속성	타입	필수 여부	설명
table_name	String	예	데이터베이스 뷰 이름.
classes	Array(String)	아니오	이 뷰와 연관된 클래스 목록.
feature_categories	Array(String)	예	이 뷰를 사용하는 기능 카테고리 목록.
description	String	아니오	뷰에 저장된 정보와 그 목적에 대한 텍스트 설명.
introduced_by_url	URL	아니오	이 뷰를 도입한 머지 리퀘스트 또는 커밋의 URL.
milestone	String	아니오	이 뷰를 도입한 마일스톤.
gitlab_schema	String	예	GitLab 스키마 이름.

프로세스#

새 뷰를 추가할 때는 다음을 수행해야 합니다:

적절한 디렉터리에 이 뷰에 대한 새 파일을 생성합니다:

gitlab_main 뷰: db/docs/views/

gitlab_ci 뷰: db/docs/views/
gitlab_sec 뷰: db/docs/views/
gitlab_shared 뷰: db/docs/views/
gitlab_embedding 뷰: ee/db/embedding/docs/views/
gitlab_geo 뷰: ee/db/geo/docs/views/
파일 이름을 <view_name>.yml로 지정하고, 뷰에 대해 알고 있는 정보를 최대한 포함시킵니다.
뷰를 생성하는 마이그레이션과 함께 이 파일을 커밋에 포함시킵니다.

뷰 삭제#

스키마#

속성	타입	필수 여부	설명
view_name	String	예	데이터베이스 뷰 이름.
classes	Array(String)	아니오	이 뷰와 연관된 클래스 목록.
feature_categories	Array(String)	예	이 뷰를 사용하는 기능 카테고리 목록.
description	String	아니오	뷰에 저장된 정보와 그 목적에 대한 텍스트 설명.
introduced_by_url	URL	아니오	이 뷰를 도입한 머지 리퀘스트 또는 커밋의 URL.
milestone	String	아니오	이 뷰를 도입한 마일스톤.
gitlab_schema	String	예	GitLab 스키마 이름.
removed_by_url	String	예	이 뷰를 제거한 머지 리퀘스트 또는 커밋의 URL.
removed_in_milestone	String	예	이 뷰를 제거하는 마일스톤.

프로세스#

뷰를 삭제할 때는 다음을 수행해야 합니다:

이 테이블의 딕셔너리 파일을 deleted_views 디렉터리로 이동합니다:

gitlab_main 뷰: db/docs/deleted_views/

gitlab_ci 뷰: db/docs/deleted_views/
gitlab_sec 뷰: db/docs/deleted_views/
gitlab_shared 뷰: db/docs/deleted_views/
gitlab_embedding 뷰: ee/db/embedding/docs/deleted_views/
gitlab_geo 뷰: ee/db/geo/docs/deleted_views/
딕셔너리 파일에 removed_by_url 및 removed_in_milestone 필드를 추가합니다.
뷰를 삭제하는 마이그레이션과 함께 이 변경 사항을 커밋에 포함시킵니다.

샤딩 키 필드#

sharding_key 및 desired_sharding_key 필드는 테이블에 샤딩 키를 추가하는 진행 상황을 추적합니다. 이 필드들은 추적 목적으로 사용되며, 샤딩 프로세스를 지원하는 도구를 활성화합니다.

sharding_key: 데이터베이스에서 샤딩 키 칼럼에 NOT NULL 제약 조건이 적용된 경우에만 이 필드를 사용합니다. 이는 테이블이 완전히 샤딩되어 조직 격리 준비가 완료되었음을 나타냅니다.
desired_sharding_key: 샤딩 키 칼럼이 존재하지만 아직 NOT NULL 제약 조건이 없는 경우(예: 백필 프로세스 진행 중)에 이 필드를 사용합니다. 테이블에 이 필드가 설정된 경우 백필을 더 쉽게 할 수 있는 도구를 사용할 수 있습니다. 백필이 완료되고 NOT NULL 제약 조건이 추가되면 desired_sharding_key를 sharding_key로 교체합니다.

테이블에 샤딩 키를 추가하는 자세한 지침은 샤딩 가이드라인을 참조하세요.

조직 이전 지원#

organization_id로 샤딩된 테이블은 사용자나 그룹을 조직 간에 이전할 때 적절하게 처리해야 합니다. organization_transfer_support 필드는 이 지원이 구현되었는지 여부를 추적합니다.

필수 조건#

organization_transfer_support 필드는 테이블의 sharding_key에 organization_id가 포함된 경우 필수입니다.

스키마#

organization_transfer_support: <status_value>

값은 supported, todo, 또는 no_work_needed 중 하나여야 합니다.

상태 값#

supported: 테이블이 조직 이전 서비스에서 적절하게 처리됩니다.

organization_id로 샤딩된 모든 신규 테이블에 필수입니다.

테이블은 다음 이전 서비스 중 하나에서 참조되어야 합니다:

app/services/organizations/transfer/groups_service.rb

app/services/organizations/transfer/users_service.rb
ee/app/services/ee/organizations/transfer/groups_service.rb
todo: 테이블에 조직 이전 지원이 필요하지만 아직 구현되지 않았습니다.

이전에 organization_id로 샤딩된 기존 테이블에 사용합니다.

no_work_needed: 테이블이 검토되었으며 조직 이전 중에 어떤 업데이트도 필요하지 않습니다.

테이블의 organization_id가 이미 처리된 다른 관계를 통해 파생되거나 연쇄적으로 적용되는 경우에 사용합니다.

데이터베이스 딕셔너리

GitLab v19.1

원문 보기

번역일: 2026-06-19

요약

위치#

딕셔너리 파일 예시#

---
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'
gitlab_schema: gitlab_main_org
sharding_key:
    project_id: projects
table_size: small

테이블 추가#

스키마#

속성	타입	필수 여부	설명
table_name	String	예	데이터베이스 테이블 이름.
classes	Array(String)	아니오	이 테이블과 연관된 클래스 목록.
feature_categories	Array(String)	예	이 테이블을 사용하는 기능 카테고리 목록.
description	String	아니오	테이블에 저장된 정보와 그 목적에 대한 텍스트 설명.
introduced_by_url	URL	아니오	이 테이블을 도입한 머지 리퀘스트 또는 커밋의 URL.
milestone	String	예	이 테이블을 도입한 마일스톤.
gitlab_schema	String	예	GitLab 스키마 이름.
notes	String	아니오	코멘트 용도로 사용. Psych가 YAML 코멘트를 파싱할 수 없으므로 이 필드를 사용합니다.
table_size	String	예	GitLab.com에서의 현재 테이블 크기 분류. 1 크기에는 인덱스가 포함됩니다. 파티셔닝된 테이블의 경우 크기는 가장 큰 파티션의 크기입니다. 유효한 옵션: unknown, small (< 10 GB), medium (< 50 GB), large (< 100 GB), over_limit (100 GB 초과).
organization_transfer_support	String	조건부	sharding_key에 organization_id가 포함된 경우 필수. 조직 이전 지원을 참조하세요.
sharding_key	Hash	조건부	테이블을 조직과 연결하는 데 사용되는 칼럼을 식별합니다. 칼럼에 NOT NULL 제약 조건이 있는 경우에만 설정합니다. 샤딩 키 필드를 참조하세요.
desired_sharding_key	Hash	조건부	칼럼이 존재하지만 아직 NOT NULL 제약 조건이 없는 경우의 의도된 샤딩 키 칼럼을 식별합니다. 샤딩 키 필드를 참조하세요.

각주:

새 테이블은 데이터가 없으므로 기본적으로 small입니다. 이 속성은 매월 자동으로 업데이트됩니다.

프로세스#

테이블을 추가할 때는 다음을 수행해야 합니다:

적절한 디렉터리에 이 테이블에 대한 새 파일을 생성합니다:

gitlab_main 테이블: db/docs/

gitlab_ci 테이블: db/docs/
gitlab_sec 테이블: db/docs/
gitlab_shared 테이블: db/docs/
gitlab_embedding 테이블: ee/db/embedding/docs/
gitlab_geo 테이블: ee/db/geo/docs/
파일 이름을 <table_name>.yml로 지정하고, 테이블에 대해 알고 있는 정보를 최대한 포함시킵니다.
테이블을 생성하는 마이그레이션과 함께 이 파일을 커밋에 포함시킵니다.

테이블 삭제#

스키마#

속성	타입	필수 여부	설명
table_name	String	예	데이터베이스 테이블 이름.
classes	Array(String)	아니오	이 테이블과 연관된 클래스 목록.
feature_categories	Array(String)	예	이 테이블을 사용하는 기능 카테고리 목록.
description	String	아니오	테이블에 저장된 정보와 그 목적에 대한 텍스트 설명.
introduced_by_url	URL	아니오	이 테이블을 도입한 머지 리퀘스트 또는 커밋의 URL.
milestone	String	아니오	이 테이블을 도입한 마일스톤.
gitlab_schema	String	예	GitLab 스키마 이름.
removed_by_url	String	예	이 테이블을 제거한 머지 리퀘스트 또는 커밋의 URL.
removed_in_milestone	String	예	이 테이블을 제거하는 마일스톤.

프로세스#

테이블을 삭제할 때는 다음을 수행해야 합니다:

이 테이블의 딕셔너리 파일을 deleted_tables 디렉터리로 이동합니다:

gitlab_main 테이블: db/docs/deleted_tables/

gitlab_ci 테이블: db/docs/deleted_tables/
gitlab_sec 테이블: db/docs/deleted_tables/
gitlab_shared 테이블: db/docs/deleted_tables/
gitlab_embedding 테이블: ee/db/embedding/docs/deleted_tables/
gitlab_geo 테이블: ee/db/geo/docs/deleted_tables/
딕셔너리 파일에 removed_by_url 및 removed_in_milestone 필드를 추가합니다.
테이블을 삭제하는 마이그레이션과 함께 이 변경 사항을 커밋에 포함시킵니다.

뷰 추가#

스키마#

속성	타입	필수 여부	설명
table_name	String	예	데이터베이스 뷰 이름.
classes	Array(String)	아니오	이 뷰와 연관된 클래스 목록.
feature_categories	Array(String)	예	이 뷰를 사용하는 기능 카테고리 목록.
description	String	아니오	뷰에 저장된 정보와 그 목적에 대한 텍스트 설명.
introduced_by_url	URL	아니오	이 뷰를 도입한 머지 리퀘스트 또는 커밋의 URL.
milestone	String	아니오	이 뷰를 도입한 마일스톤.
gitlab_schema	String	예	GitLab 스키마 이름.

프로세스#

새 뷰를 추가할 때는 다음을 수행해야 합니다:

적절한 디렉터리에 이 뷰에 대한 새 파일을 생성합니다:

gitlab_main 뷰: db/docs/views/

gitlab_ci 뷰: db/docs/views/
gitlab_sec 뷰: db/docs/views/
gitlab_shared 뷰: db/docs/views/
gitlab_embedding 뷰: ee/db/embedding/docs/views/
gitlab_geo 뷰: ee/db/geo/docs/views/
파일 이름을 <view_name>.yml로 지정하고, 뷰에 대해 알고 있는 정보를 최대한 포함시킵니다.
뷰를 생성하는 마이그레이션과 함께 이 파일을 커밋에 포함시킵니다.

뷰 삭제#

스키마#

속성	타입	필수 여부	설명
view_name	String	예	데이터베이스 뷰 이름.
classes	Array(String)	아니오	이 뷰와 연관된 클래스 목록.
feature_categories	Array(String)	예	이 뷰를 사용하는 기능 카테고리 목록.
description	String	아니오	뷰에 저장된 정보와 그 목적에 대한 텍스트 설명.
introduced_by_url	URL	아니오	이 뷰를 도입한 머지 리퀘스트 또는 커밋의 URL.
milestone	String	아니오	이 뷰를 도입한 마일스톤.
gitlab_schema	String	예	GitLab 스키마 이름.
removed_by_url	String	예	이 뷰를 제거한 머지 리퀘스트 또는 커밋의 URL.
removed_in_milestone	String	예	이 뷰를 제거하는 마일스톤.

프로세스#

뷰를 삭제할 때는 다음을 수행해야 합니다:

이 테이블의 딕셔너리 파일을 deleted_views 디렉터리로 이동합니다:

gitlab_main 뷰: db/docs/deleted_views/

gitlab_ci 뷰: db/docs/deleted_views/
gitlab_sec 뷰: db/docs/deleted_views/
gitlab_shared 뷰: db/docs/deleted_views/
gitlab_embedding 뷰: ee/db/embedding/docs/deleted_views/
gitlab_geo 뷰: ee/db/geo/docs/deleted_views/
딕셔너리 파일에 removed_by_url 및 removed_in_milestone 필드를 추가합니다.
뷰를 삭제하는 마이그레이션과 함께 이 변경 사항을 커밋에 포함시킵니다.

샤딩 키 필드#

sharding_key: 데이터베이스에서 샤딩 키 칼럼에 NOT NULL 제약 조건이 적용된 경우에만 이 필드를 사용합니다. 이는 테이블이 완전히 샤딩되어 조직 격리 준비가 완료되었음을 나타냅니다.
desired_sharding_key: 샤딩 키 칼럼이 존재하지만 아직 NOT NULL 제약 조건이 없는 경우(예: 백필 프로세스 진행 중)에 이 필드를 사용합니다. 테이블에 이 필드가 설정된 경우 백필을 더 쉽게 할 수 있는 도구를 사용할 수 있습니다. 백필이 완료되고 NOT NULL 제약 조건이 추가되면 desired_sharding_key를 sharding_key로 교체합니다.

테이블에 샤딩 키를 추가하는 자세한 지침은 샤딩 가이드라인을 참조하세요.

조직 이전 지원#

필수 조건#

organization_transfer_support 필드는 테이블의 sharding_key에 organization_id가 포함된 경우 필수입니다.

스키마#

organization_transfer_support: <status_value>

값은 supported, todo, 또는 no_work_needed 중 하나여야 합니다.

상태 값#

supported: 테이블이 조직 이전 서비스에서 적절하게 처리됩니다.

organization_id로 샤딩된 모든 신규 테이블에 필수입니다.

테이블은 다음 이전 서비스 중 하나에서 참조되어야 합니다:

app/services/organizations/transfer/groups_service.rb

app/services/organizations/transfer/users_service.rb
ee/app/services/ee/organizations/transfer/groups_service.rb
todo: 테이블에 조직 이전 지원이 필요하지만 아직 구현되지 않았습니다.

이전에 organization_id로 샤딩된 기존 테이블에 사용합니다.

no_work_needed: 테이블이 검토되었으며 조직 이전 중에 어떤 업데이트도 필요하지 않습니다.

테이블의 organization_id가 이미 처리된 다른 관계를 통해 파생되거나 연쇄적으로 적용되는 경우에 사용합니다.