Large Tables Limitations - Team Awareness

Context

We have introduced new limitations to prevent adding new indexes or columns on large tables to improve manageability for both GitLab and our customers. These changes will affect several tables across our database infrastructure.

Impact

Starting from our next release, teams will need to follow new guidelines when working with the tables listed below. The main limitations are:

• Adding an index: maximum size 50 GB
• Adding a column with foreign key: maximum size 50 GB
• Adding a new column: maximum size 100 GB

Affected Tables

The following tables are subject to these limitations:

Table Name	Feature Categories
audit_events	groupcompliance
security_findings	groupsecurity infrastructure
merge_request_diff_commits	groupcode review
merge_request_diff_files	groupcode review
resource_label_events	groupproject management
merge_request_metrics	groupoptimize
todos	grouppersonal productivity
vulnerability_finding_links	groupsecurity infrastructure
sent_notifications	groupproject management
events	grouporganizations
security_scans	groupsecurity infrastructure
packages_package_files	grouppackage registry
web_hook_logs	groupimport and integrate
merge_requests	groupcode review
vulnerability_occurrences	groupsecurity infrastructure
notes	groupcode review
issues	groupproject management
projects	grouporganizations
project_authorizations	groupauthentication
vulnerabilities	groupsecurity infrastructure
vulnerability_reads	groupsecurity infrastructure
personal_access_tokens	groupauthentication
oauth_access_tokens	groupauthentication
sbom_occurrences	groupsecurity infrastructure
push_event_payloads	groupsource code
deployments	groupenvironments
merge_request_diffs	groupcode review
description_versions	groupproject management
system_note_metadata	groupproject management
approval_merge_request_rules_users	groupcode review
note_diff_files	groupcode review
ci_job_artifact_states	groupgeo
taggings	grouprunner groupci platform
ci_build_report_results	grouppipeline execution
ci_build_needs	grouppipeline execution
ci_build_names	grouppipeline execution
ci_builds_metadata	grouppipeline execution
ci_job_variables	grouppipeline execution
ci_job_artifacts	grouppipeline security
ci_pipeline_messages	grouppipeline execution
ci_stages	grouppipeline execution
ci_builds	grouppipeline execution
ci_pipelines	grouppipeline execution
ci_build_tags	groupci platform
ci_pipeline_variables	grouppipeline security

What You Need to Do

1. Review if your team works with any of these tables
2. Update your development practices to consider these limitations
3. For new features involving these tables, consider the following alternatives:
   • Create a separate table for new columns
   • Use Elasticsearch for additional filtering/search functionality
   • Simplify filtering/sorting options

Exceptions

Exceptions to these limitations are only granted for:

• Migrating table columns from int4 to int8
• Adding sharding keys to support cells
• Modifying tables for partitioning or data retention
• Replacing existing indexes to improve query performance

Additional Resources

• Large Tables Limitations Documentation
• Database Size Limits
• Reference Issue: #477398 (closed)

Next Steps

• Please review this information with your team
• Raise any concerns or questions in this issue
• Update your team's documentation and development guidelines accordingly