GitLab PostgreSQL Connection Calculator

Plan your database connections for GitLab 16.0+ (dual database mode). Based on GitLab 18.9 documentation.

⚠️ Note: This calculator focuses on database connection planning based on GitLab's official formulas. Connection calculations are accurate for planning purposes. Always monitor your actual connection usage and adjust accordingly.

Show Resource Estimates (CPU & RAM) Optional

Puma Configuration

GitLab Configuration (gitlab.rb)

puma['worker_processes'] = 8
puma['max_threads'] = 4
# DB_POOL_HEADROOM = 10 (default)

Puma Workers:

Default is based on CPU core count. Typically 1 worker per vCPU core.

Max Threads per Worker:

Default is 4 threads. Higher values increase concurrency per worker.

DB Pool Headroom:

Default is 10. Extra connections reserved for handling demand spikes. Do not change unless necessary.

Number of Puma Services:

Total number of nodes/servers running Puma in your deployment.

Formula: workers × (max_threads + headroom) × nodes

8 × (4 + 10) × 1 = 112 connections

(14 connections per worker × 8 workers = 112 per node)

Sidekiq Configuration

GitLab Configuration (gitlab.rb)

sidekiq['queue_groups'] = ['*'] * 1
sidekiq['concurrency'] = 20
# DB_POOL_HEADROOM = 10 (default)

📖 Run multiple Sidekiq processes

Sidekiq Processes:

Default is 1 process. Scale up with multiple processes to handle more background jobs.

Concurrency per Process:

Default is 20. Number of threads each Sidekiq process can run simultaneously.

DB Pool Headroom:

Default is 10. Extra connections reserved for handling demand spikes. Do not change unless necessary.

Number of Sidekiq Services:

Total number of nodes/servers running Sidekiq in your deployment.

Formula: processes × (concurrency + 1 + headroom) × nodes

1 × (20 + 1 + 10) × 1 = 31 connections

(31 connections per process × 1 processes = 31 per node)

Geo Configuration (Optional)

Enable Geo

Total Connection Requirements

GitLab 16.0+ uses dual database connections (main + ci tables), which doubles the connection count.

Single Database Total

Puma: 112

Sidekiq: 31

Geo: 0

143

connections

Dual Database Total (×2)

Required for GitLab 16.0+

143 × 2

286

connections needed