PGConfig Documentation

# API Specification

This project it's API that pgconfig.org (opens new window) uses to calculate the tuning values and stuff.

# How it works

The web interface (pgconfig.org website (opens new window) or just UI) access this api on the address https://api.pgconfig.org/v1/tuning/get-config (opens new window).

You can call it from curl, eg:

$ curl 'https://api.pgconfig.org/v1/tuning/get-config'
{"data": [{"category": "memory_related","description": "Memory Configuration","parameters": [{"config_value": "512MB","format": "Bytes","name": "shared_buffers"},{"config_value": "2GB","format": "Bytes","name": "effective_cache_size"},{"config_value": "20MB","format": "Bytes","name": "work_mem"},{"config_value": "128MB","format": "Bytes","name": "maintenance_work_mem"}]},{"category": "checkpoint_related","description": "Checkpoint Related Configuration","parameters": [{"config_value": "512MB","format": "Bytes","name": "min_wal_size"},{"config_value": "2GB","format": "Bytes","name": "max_wal_size"},{"config_value": 0.7,"format": "Float","name": "checkpoint_completion_target"},{"config_value": "15MB","format": "Bytes","name": "wal_buffers"}]},{"category": "network_related","description": "Network Related Configuration","parameters": [{"config_value": "*","format": "String","name": "listen_addresses"},{"config_value": 100,"format": "Decimal","name": "max_connections"}]}],"jsonapi": {"version": "1.0"},"links": {"self": "http://api.pgconfig.org/v1/tuning/get-config"},"meta": {"arguments": {},"copyright": "PGConfig API","version": "2.0 beta"}}
1
2

With a little formating, looks like this:

{  
   "data":[  
      {  
         "category":"memory_related",
         "description":"Memory Configuration",
         "parameters":[  
            {  
               "config_value":"512MB",
               "format":"Bytes",
               "name":"shared_buffers"
            },
            {  
               "config_value":"2GB",
               "format":"Bytes",
               "name":"effective_cache_size"
            },
            {  
               "config_value":"20MB",
               "format":"Bytes",
               "name":"work_mem"
            },
            {  
               "config_value":"128MB",
               "format":"Bytes",
               "name":"maintenance_work_mem"
            }
         ]
      },
      {  
         "category":"checkpoint_related",
         "description":"Checkpoint Related Configuration",
         "parameters":[  
            {  
               "config_value":"512MB",
               "format":"Bytes",
               "name":"min_wal_size"
            },
            {  
               "config_value":"2GB",
               "format":"Bytes",
               "name":"max_wal_size"
            },
            {  
               "config_value":0.7,
               "format":"Float",
               "name":"checkpoint_completion_target"
            },
            {  
               "config_value":"15MB",
               "format":"Bytes",
               "name":"wal_buffers"
            }
         ]
      },
      {  
         "category":"network_related",
         "description":"Network Related Configuration",
         "parameters":[  
            {  
               "config_value":"*",
               "format":"String",
               "name":"listen_addresses"
            },
            {  
               "config_value":100,
               "format":"Decimal",
               "name":"max_connections"
            }
         ]
      }
   ],
   "jsonapi":{  
      "version":"1.0"
   },
   "links":{  
      "self":"http://api.pgconfig.org/v1/tuning/get-config"
   },
   "meta":{  
      "arguments":{  

      },
      "copyright":"PGConfig API",
      "version":"2.0 beta"
   }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

Basically, the important data are in the data node, grouped by categories, just like in the UI. 😃

A important thing about this is that you can format the output displayed more conveniently, only informing the format=conf parameters, eg:

$ curl 'https://api.pgconfig.org/v1/tuning/get-config?format=conf'
# Generated by PGConfig 2.0 beta
## http://pgconfig.org

# Memory Configuration
shared_buffers = 512MB
effective_cache_size = 2GB
work_mem = 20MB
maintenance_work_mem = 128MB

# Checkpoint Related Configuration
min_wal_size = 512MB
max_wal_size = 2GB
checkpoint_completion_target = 0.7
wal_buffers = 15MB

# Network Related Configuration
listen_addresses = '*'
max_connections = 100
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Another options for the format parameters are json (the default value) and alter_system, take a look:

$ curl 'https://api.pgconfig.org/v1/tuning/get-config?format=alter_system'
-- Generated by PGConfig 2.0 beta
---- http://pgconfig.org

-- Memory Configuration
ALTER SYSTEM SET shared_buffers TO '512MB';
ALTER SYSTEM SET effective_cache_size TO '2GB';
ALTER SYSTEM SET work_mem TO '20MB';
ALTER SYSTEM SET maintenance_work_mem TO '128MB';

-- Checkpoint Related Configuration
ALTER SYSTEM SET min_wal_size TO '512MB';
ALTER SYSTEM SET max_wal_size TO '2GB';
ALTER SYSTEM SET checkpoint_completion_target TO '0.7';
ALTER SYSTEM SET wal_buffers TO '15MB';

-- Network Related Configuration
ALTER SYSTEM SET listen_addresses TO '*';
ALTER SYSTEM SET max_connections TO '100';
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

In short: to change the output, all you need is to do it's put the parameters in the URL.

# Available parameters

DANGER

Don't forget, when setting the total_ram parameter, set the value like the expression [0-9]{1,}GB, eg: 4GB.

The list below lists the available parameters:

Parameter Possible values Default Value Description
pg_version from 9.0 until 12 12 Defines the PostgreSQL Version
total_ram any value above 1GB 2GB Defines the total dedicated memory to PostgreSQL
max_connections any value above 1 100 expected number of connections
environment_name WEB, OLTP, DW, Mixed and Desktop WEB Defines the environment that the server will run (more details below)
os_type Linux, Windows and Unix Linux Defines the type of operating system used
arch x86-64 and i686 x86-64 Defines the server architecture
drive_type HDD, SSD and SAN HDD Defines the default storage type
cpus any value above 1 -1 Defines the total CPUs available
format json, conf and alter_system json Defines the output format

# Specific for the JSON output

Parameter Possible values Default Value Description
show_doc true or false json Shows the documentation

# Specific for the conf or alter_system output

Parameter Possible values Default Value Description
include_pgbadger true or false json Add the basic settings to enable pgbadger
log_format stderr, csvlog and syslog stderr Sets de default log format for the pgbadger. (Used only when include_pgbadger is true)
Last Updated: 8/24/2020, 12:12:58 AM

About the environment →