From 8a7a8bed8e61346aa831b839c509eaef8f8bfb9c Mon Sep 17 00:00:00 2001
From: meskill <8974488+meskill@users.noreply.github.com>
Date: Thu, 13 Aug 2026 14:55:08 +0000
Subject: [PATCH] feat(prepared_statements): ttl configuration

---
 docs/administration/config.md                 |  2 ++
 .../connection-pooler/prepared-statements.md  | 21 ++++++++++++++++++-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/docs/administration/config.md b/docs/administration/config.md
index 016382d7..faa8d39b 100644
--- a/docs/administration/config.md
+++ b/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` |
diff --git a/docs/features/connection-pooler/prepared-statements.md b/docs/features/connection-pooler/prepared-statements.md
index 3b3f8c04..b9b79a41 100644
--- a/docs/features/connection-pooler/prepared-statements.md
+++ b/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
+```
+
+The 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)