|
| 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 | + |
0 commit comments