Skip to content

Commit b09f0a3

Browse files
authored
Improve Config Documentation (#351)
This PR adds a utility script that generates config documentation from pgcat.toml. Ideally, we'd want to generate the configs directly from config.rs where the actual defaults are set but this is a good start as we already had several undocumented config flags.
1 parent 0704ea0 commit b09f0a3

File tree

4 files changed

+490
-72
lines changed

4 files changed

+490
-72
lines changed

CONFIG.md

Lines changed: 340 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,340 @@
1+
# PgCat Configurations
2+
## `general` Section
3+
4+
### host
5+
```
6+
path: general.host
7+
default: "0.0.0.0"
8+
```
9+
10+
What IP to run on, 0.0.0.0 means accessible from everywhere.
11+
12+
### port
13+
```
14+
path: general.port
15+
default: 6432
16+
```
17+
18+
Port to run on, same as PgBouncer used in this example.
19+
20+
### enable_prometheus_exporter
21+
```
22+
path: general.enable_prometheus_exporter
23+
default: true
24+
```
25+
26+
Whether to enable prometheus exporter or not.
27+
28+
### prometheus_exporter_port
29+
```
30+
path: general.prometheus_exporter_port
31+
default: 9930
32+
```
33+
34+
Port at which prometheus exporter listens on.
35+
36+
### connect_timeout
37+
```
38+
path: general.connect_timeout
39+
default: 5000 # milliseconds
40+
```
41+
42+
How long to wait before aborting a server connection (ms).
43+
44+
### idle_timeout
45+
```
46+
path: general.idle_timeout
47+
default: 30000 # milliseconds
48+
```
49+
50+
How long an idle connection with a server is left open (ms).
51+
52+
### healthcheck_timeout
53+
```
54+
path: general.healthcheck_timeout
55+
default: 1000 # milliseconds
56+
```
57+
58+
How much time to give the health check query to return with a result (ms).
59+
60+
### healthcheck_delay
61+
```
62+
path: general.healthcheck_delay
63+
default: 30000 # milliseconds
64+
```
65+
66+
How long to keep connection available for immediate re-use, without running a healthcheck query on it
67+
68+
### shutdown_timeout
69+
```
70+
path: general.shutdown_timeout
71+
default: 60000 # milliseconds
72+
```
73+
74+
How much time to give clients during shutdown before forcibly killing client connections (ms).
75+
76+
### ban_time
77+
```
78+
path: general.ban_time
79+
default: 60 # seconds
80+
```
81+
82+
How long to ban a server if it fails a health check (seconds).
83+
84+
### log_client_connections
85+
```
86+
path: general.log_client_connections
87+
default: false
88+
```
89+
90+
If we should log client connections
91+
92+
### log_client_disconnections
93+
```
94+
path: general.log_client_disconnections
95+
default: false
96+
```
97+
98+
If we should log client disconnections
99+
100+
### autoreload
101+
```
102+
path: general.autoreload
103+
default: false
104+
```
105+
106+
When set to true, PgCat reloads configs if it detects a change in the config file.
107+
108+
### worker_threads
109+
```
110+
path: general.worker_threads
111+
default: 5
112+
```
113+
114+
Number of worker threads the Runtime will use (4 by default).
115+
116+
### tcp_keepalives_idle
117+
```
118+
path: general.tcp_keepalives_idle
119+
default: 5
120+
```
121+
122+
Number of seconds of connection idleness to wait before sending a keepalive packet to the server.
123+
124+
### tcp_keepalives_count
125+
```
126+
path: general.tcp_keepalives_count
127+
default: 5
128+
```
129+
130+
Number of unacknowledged keepalive packets allowed before giving up and closing the connection.
131+
132+
### tcp_keepalives_interval
133+
```
134+
path: general.tcp_keepalives_interval
135+
default: 5
136+
```
137+
138+
Number of seconds between keepalive packets.
139+
140+
### tls_certificate
141+
```
142+
path: general.tls_certificate
143+
default: <UNSET>
144+
example: "server.cert"
145+
```
146+
147+
Path to TLS Certficate file to use for TLS connections
148+
149+
### tls_private_key
150+
```
151+
path: general.tls_private_key
152+
default: <UNSET>
153+
example: "server.key"
154+
```
155+
156+
Path to TLS private key file to use for TLS connections
157+
158+
### admin_username
159+
```
160+
path: general.admin_username
161+
default: "admin_user"
162+
```
163+
164+
User name to access the virtual administrative database (pgbouncer or pgcat)
165+
Connecting to that database allows running commands like `SHOW POOLS`, `SHOW DATABASES`, etc..
166+
167+
### admin_password
168+
```
169+
path: general.admin_password
170+
default: "admin_pass"
171+
```
172+
173+
Password to access the virtual administrative database
174+
175+
## `pools.<pool_name>` Section
176+
177+
### pool_mode
178+
```
179+
path: pools.<pool_name>.pool_mode
180+
default: "transaction"
181+
```
182+
183+
Pool mode (see PgBouncer docs for more).
184+
`session` one server connection per connected client
185+
`transaction` one server connection per client transaction
186+
187+
### load_balancing_mode
188+
```
189+
path: pools.<pool_name>.load_balancing_mode
190+
default: "random"
191+
```
192+
193+
Load balancing mode
194+
`random` selects the server at random
195+
`loc` selects the server with the least outstanding busy conncetions
196+
197+
### default_role
198+
```
199+
path: pools.<pool_name>.default_role
200+
default: "any"
201+
```
202+
203+
If the client doesn't specify, PgCat routes traffic to this role by default.
204+
`any` round-robin between primary and replicas,
205+
`replica` round-robin between replicas only without touching the primary,
206+
`primary` all queries go to the primary unless otherwise specified.
207+
208+
### query_parser_enabled
209+
```
210+
path: pools.<pool_name>.query_parser_enabled
211+
default: true
212+
```
213+
214+
If Query Parser is enabled, we'll attempt to parse
215+
every incoming query to determine if it's a read or a write.
216+
If it's a read query, we'll direct it to a replica. Otherwise, if it's a write,
217+
we'll direct it to the primary.
218+
219+
### primary_reads_enabled
220+
```
221+
path: pools.<pool_name>.primary_reads_enabled
222+
default: true
223+
```
224+
225+
If the query parser is enabled and this setting is enabled, the primary will be part of the pool of databases used for
226+
load balancing of read queries. Otherwise, the primary will only be used for write
227+
queries. The primary can always be explicitly selected with our custom protocol.
228+
229+
### sharding_key_regex
230+
```
231+
path: pools.<pool_name>.sharding_key_regex
232+
default: <UNSET>
233+
example: '/\* sharding_key: (\d+) \*/'
234+
```
235+
236+
Allow sharding commands to be passed as statement comments instead of
237+
separate commands. If these are unset this functionality is disabled.
238+
239+
### sharding_function
240+
```
241+
path: pools.<pool_name>.sharding_function
242+
default: "pg_bigint_hash"
243+
```
244+
245+
So what if you wanted to implement a different hashing function,
246+
or you've already built one and you want this pooler to use it?
247+
Current options:
248+
`pg_bigint_hash`: PARTITION BY HASH (Postgres hashing function)
249+
`sha1`: A hashing function based on SHA1
250+
251+
### automatic_sharding_key
252+
```
253+
path: pools.<pool_name>.automatic_sharding_key
254+
default: <UNSET>
255+
example: "data.id"
256+
```
257+
258+
Automatically parse this from queries and route queries to the right shard!
259+
260+
### idle_timeout
261+
```
262+
path: pools.<pool_name>.idle_timeout
263+
default: 40000
264+
```
265+
266+
Idle timeout can be overwritten in the pool
267+
268+
### connect_timeout
269+
```
270+
path: pools.<pool_name>.connect_timeout
271+
default: 3000
272+
```
273+
274+
Connect timeout can be overwritten in the pool
275+
276+
## `pools.<pool_name>.users.<user_index>` Section
277+
278+
### username
279+
```
280+
path: pools.<pool_name>.users.<user_index>.username
281+
default: "sharding_user"
282+
```
283+
284+
Postgresql username
285+
286+
### password
287+
```
288+
path: pools.<pool_name>.users.<user_index>.password
289+
default: "sharding_user"
290+
```
291+
292+
Postgresql password
293+
294+
### pool_size
295+
```
296+
path: pools.<pool_name>.users.<user_index>.pool_size
297+
default: 9
298+
```
299+
300+
Maximum number of server connections that can be established for this user
301+
The maximum number of connection from a single Pgcat process to any database in the cluster
302+
is the sum of pool_size across all users.
303+
304+
### statement_timeout
305+
```
306+
path: pools.<pool_name>.users.<user_index>.statement_timeout
307+
default: 0
308+
```
309+
310+
Maximum query duration. Dangerous, but protects against DBs that died in a non-obvious way.
311+
0 means it is disabled.
312+
313+
## `pools.<pool_name>.shards.<shard_index>` Section
314+
315+
### servers
316+
```
317+
path: pools.<pool_name>.shards.<shard_index>.servers
318+
default: [["127.0.0.1", 5432, "primary"], ["localhost", 5432, "replica"]]
319+
```
320+
321+
Array of servers in the shard, each server entry is an array of `[host, port, role]`
322+
323+
### mirrors
324+
```
325+
path: pools.<pool_name>.shards.<shard_index>.mirrors
326+
default: <UNSET>
327+
example: [["1.2.3.4", 5432, 0], ["1.2.3.4", 5432, 1]]
328+
```
329+
330+
Array of mirrors for the shard, each mirror entry is an array of `[host, port, index of server in servers array]`
331+
Traffic hitting the server identified by the index will be sent to the mirror.
332+
333+
### database
334+
```
335+
path: pools.<pool_name>.shards.<shard_index>.database
336+
default: "shard0"
337+
```
338+
339+
Database name (e.g. "postgres")
340+

README.md

Lines changed: 1 addition & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -39,35 +39,7 @@ PGPASSWORD=postgres psql -h 127.0.0.1 -p 6432 -U postgres -c 'SELECT 1'
3939

4040
### Config
4141

42-
| **Name** | **Description** | **Examples** |
43-
|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|
44-
| **`general`** | | |
45-
| `host` | The pooler will run on this host, 0.0.0.0 means accessible from everywhere. | `0.0.0.0` |
46-
| `port` | The pooler will run on this port. | `6432` |
47-
| `enable_prometheus_exporter` | Enable prometheus exporter which will export metrics in prometheus exposition format. | `true` |
48-
| `prometheus_exporter_port` | Port at which prometheus exporter listens on. | `9930` |
49-
| `pool_size` | Maximum allowed server connections per pool. Pools are separated for each user/shard/server role. The connections are allocated as needed. | `15` |
50-
| `pool_mode` | The pool mode to use, i.e. `session` or `transaction`. | `transaction` |
51-
| `connect_timeout` | Maximum time to establish a connection to a server (milliseconds). If reached, the server is banned and the next target is attempted. | `5000` |
52-
| `healthcheck_timeout` | Maximum time to pass a health check (`SELECT 1`, milliseconds). If reached, the server is banned and the next target is attempted. | `1000` |
53-
| `shutdown_timeout` | Maximum time to give clients during shutdown before forcibly killing client connections (ms). | `60000` |
54-
| `healthcheck_delay` | How long to keep connection available for immediate re-use, without running a healthcheck query on it | `30000` |
55-
| `ban_time` | Ban time for a server (seconds). It won't be allowed to serve transactions until the ban expires; failover targets will be used instead. | `60` |
56-
| `autoreload` | Enable auto-reload of config after fixed time-interval. | `false` |
57-
| | | |
58-
| **`user`** | | |
59-
| `name` | The user name. | `sharding_user` |
60-
| `password` | The user password in plaintext. | `hunter2` |
61-
| `statement_timeout` | Timeout in milliseconds for how long a query takes to execute | `0 (disabled)`
62-
| | | |
63-
| **`shards`** | Shards are numerically numbered starting from 0; the order in the config is preserved by the pooler to route queries accordingly. | `[shards.0]` |
64-
| `servers` | List of servers to connect to and their roles. A server is: `[host, port, role]`, where `role` is either `primary` or `replica`. | `["127.0.0.1", 5432, "primary"]` |
65-
| `database` | The name of the database to connect to. This is the same on all servers that are part of one shard. | |
66-
| | | |
67-
| **`query_router`** | | |
68-
| `default_role` | Traffic is routed to this role by default (random), unless the client specifies otherwise. Default is `any`, for any role available. | `any`, `primary`, `replica` |
69-
| `query_parser_enabled` | Enable the query parser which will inspect incoming queries and route them to a primary or replicas. | `false` |
70-
| `primary_reads_enabled` | Enable this to allow read queries on the primary; otherwise read queries are routed to the replicas. | `true` |
42+
(See Configurations page)[https://github.com/levkk/pgcat/blob/main/CONFIG.md]
7143

7244
## Local development
7345

0 commit comments

Comments
 (0)