feat(prepared_statements): ttl configuration

Author: meskill

docs/administration/config.md

@@ -44,6 +44,8 @@ The following configuration parameters are available and their current values:
 | `port` [:material-link:](../configuration/pgdog.toml/general.md#port) | `6432` |
 | `prepared_statements` [:material-link:](../configuration/pgdog.toml/general.md#prepared_statements) | `extended` |
 | `prepared_statements_limit` [:material-link:](../configuration/pgdog.toml/general.md#prepared_statements_limit) | `500` |
+| `prepared_statements_ttl` [:material-link:](../configuration/pgdog.toml/general.md#prepared_statements_ttl) | `default` |
+| `prepared_statements_ttl_jitter` [:material-link:](../configuration/pgdog.toml/general.md#prepared_statements_ttl_jitter) | `30000` |
 | `pub_sub_channel_size` [:material-link:](../configuration/pgdog.toml/general.md#pub_sub_channel_size) | `4098` |
 | `query_cache_limit` | `500` |
 | `query_log` | `default` |

docs/features/connection-pooler/prepared-statements.md

@@ -45,6 +45,25 @@ This limit is strictly enforced on server connections: if a prepared statement n
 
 Since clients re-use prepared statements, this limit isn't enforced for clients: they can prepare as many statements as they wish (and you have memory for). Each statement keeps a counter of when it's used by a client. If the counter reaches zero, i.e., all clients either closed it explicitly or disconnected, the statement is removed from the global cache.
 
+## Statement TTL
+
+Postgres builds an execution plan when a statement is prepared and keeps it for the lifetime of the statement. Since PgDog
+keeps server connections open for a long time, a plan can stay in use long after the data it was built for has changed.
+
+To mitigate this, PgDog can be configured to close statements on server connections after some time. After the statement is closed PgDog will recreate the statement seamlessly when the next client tries to use the same statement again.
+
+To enable TTL, extend `pgdog.toml` with the following [settings](../../configuration/pgdog.toml/general.md#prepared_statements_ttl):
+
+```toml
+[general]
+prepared_statements_ttl = 300_000
+prepared_statements_ttl_jitter = 30_000
+```
+
+Jitter setting is helpful to avoid all statements expiring at the same time, which could cause a noticeable spike in server load.
+
+By default the TTL is disabled and statements stay prepared for the lifetime of the server connection.
+
 ## Tracking used statements
 
 The number of prepared statements and what they are can be tracked by executing this command on the [admin database](../../administration/index.md):
@@ -56,7 +75,7 @@ The number of prepared statements and what they are can be tracked by executing
     ```
 === "Output"
     ```
-       name    |                       statement                       | rewrite | used_by | memory_used 
+       name    |                       statement                       | rewrite | used_by | memory_used
     -----------+-------------------------------------------------------+---------+---------+-------------
      __pgdog_1 | SELECT abalance FROM pgbench_accounts WHERE aid = $1; |         |       4 |         144
     (1 row)