PGConfig API

This project is a VERY BIG WORK IN PROGRESS.

PGConfig.org API v2.

Objectives of this repo

1. host the v2 api of pgconfig.org:

   • Create new API using fiber
     • Route compare
     • other routes
   • Update Release with and build the docker images
   • Add JSON format option
   • Remove "blocked" params in the SGPostgresConfig format

2. build and release the pgconfigctl:

   • Migrate/Review all Categories:
     • Memory Configuration
     • Checkpoint Related Configuration
     • Network Related Configuration
     • Storage Configuration
     • Worker Processes Configuration
   • Implement compute filters:
     • Arch
     • OS
     • Storage
     • CPU Count
     • Total RAM
     • Profile
     • Version
   • Review all metrics
   • move all inputs to the pkg/input pkg
     • update pgconfigctl to use the new inputs
     • update api to use the new inputs

3. review metrics

   • based in stackgres list: https://gitlab.com/ongresinc/stackgres/-/issues/486#note_360442486
   • based in the old api:
     • https://github.com/sebastianwebber/pgconfig-api/blob/master/advisors/tuning.py
     • https://github.com/sebastianwebber/pgconfig-api/blob/master/advisors/config.py

License

CPU Core Counting

The API expects the total_cpu parameter to represent the total number of logical CPU cores, which includes hyperthreading. This is the standard output from:

• Linux/Unix: nproc command
• Go: runtime.NumCPU()
• Windows: Total processor count in Task Manager

Example: A system with 8 physical cores and hyperthreading enabled has 16 logical cores. Use total_cpu=16.

Why logical cores? Modern PostgreSQL (2017-2025) benefits from hyperthreading with up to 15% performance improvement. The tuning formulas for max_worker_processes, max_parallel_workers, and io_workers are designed to work with logical core counts.

Rules Engine

The configuration is adjusted by a rules engine based on the environment.

Category	Condition	Action/Adjustment
Architecture	32-bit (386, i686)	Cap shared_buffers, work_mem, maintenance_work_mem at 4GB.
OS	Windows	Set effective_io_concurrency to 0.
	Windows & PG Version <= 9.6	Limit shared_buffers to 512MB.
Profile	Desktop	Set shared_buffers to Total RAM / 16.
Storage	Disk Type is SSD	Set effective_io_concurrency to 200 and random_page_cost to 1.1.
	Disk Type is SAN	Set effective_io_concurrency to 300 and random_page_cost to 1.1.
	Disk Type is HDD	Set effective_io_concurrency to 2.
PG Version	< 9.5	Remove min_wal_size and max_wal_size.
	< 9.6	Remove max_parallel_worker_per_gather. Cap shared_buffers at 8GB.
	< 10.0	Remove max_parallel_workers.
	>= 9.5	Remove checkpoint_segments.
	<= 9.3	Remove the entire worker category.