fix: high-perf pooling doc (#2332)

* fix: high-perf pooling doc

* chore: apply suggestion from code review

Co-authored-by: hackerman <3372410+aeneasr@users.noreply.github.com>

* chore: apply suggestion from code review

Co-authored-by: hackerman <3372410+aeneasr@users.noreply.github.com>

* chore: apply suggestions from code review

Co-authored-by: Arne Luenser <arne.luenser@ory.sh>

* chore: omit slop

---------

Co-authored-by: hackerman <3372410+aeneasr@users.noreply.github.com>
Co-authored-by: Arne Luenser <arne.luenser@ory.sh>

Author: 3 people

docs/self-hosted/deployment.md

@@ -70,30 +70,8 @@ DSN=postgres://user:password@host:123/database?sslmode=verify-full
 
 ##### High-performance pooling
 
-:::note
-
-High-performance pooling is supported in Ory Enterprise License (OEL) images.
-
-:::
-
-High-performance pooling is built using [pgxpool](https://pkg.go.dev/github.com/jackc/pgx/v5/pgxpool) and provides additional
-configuration options to the ones listed under "Standard pooling".
-
-To activate high-performance pooling, you must set at least the `pool_min_conns` parameter; otherwise, high-performance pooling
-will not be enabled.
-
-- `pool_min_conns` (number): The minimum number of total (in-use and idle) database connections to keep open at all times. After a
-  connection closes, the pool may dip below `pool_min_conns` momentarily. Defaults to 0.
-- `pool_max_conns` (number): Sets the maximum number of open connections to the database. Overrides `max_conns`.
-- `pool_max_conn_idle_time` (duration: for example "500ms", "5s", "30m", "1h"): Database connections will be closed after idling
-  for this duration. Overrides `max_conn_idle_time`.
-- `pool_max_conn_lifetime` (duration: for example "500ms", "5s", "30m", "1h"): Sets the time after which a connection will be
-  closed, irrespective of how long it has been idle. Overrides `max_conn_lifetime`.
-- `pool_max_conn_lifetime_jitter` (duration: for example "500ms", "5s", "30m", "1h"): Jitter to add to the
-  `pool_max_conn_lifetime` value. This is useful to avoid thundering herd problems when many connections are closed and re-opened
-  at the same time.
-- `pool_health_check_period` (duration: for example "500ms", "5s", "30m", "1h"): Sets the period for health checks to potentially
-  kill stale connections. Defaults to "1m".
+High-performance pooling is supported in Ory Enterprise License (OEL) images. Read more about it in the
+[high-performance pooling](./oel/high-performance-pooling) documentation.
 
 ### CockroachDB
 

docs/self-hosted/oel/oel-high-performance-pooling.mdx

@@ -0,0 +1,44 @@
+---
+id: high-performance-pooling
+title: High-performance database connection pooling
+sidebar_label: High-performance pooling
+---
+
+High-performance pooling is available for CockroachDB and PostgreSQL with an Ory Enterprise License (OEL). It provides additional
+configuration options for managing database connections under variable load.
+
+To activate high-performance pooling, you must set the `pool_min_conns` parameter, otherwise high-performance pooling will not be
+enabled.
+
+- `pool_min_conns` (number): The minimum number of total (in-use and idle) database connections to keep open at all times. After a
+  connection closes, the pool may dip below `pool_min_conns` momentarily. Defaults to 0.
+- `pool_max_conns` (number): Sets the maximum number of open connections to the database. Overrides `max_conns`.
+- `pool_max_conn_idle_time` (duration: for example "500ms", "5s", "30m", "1h"): Database connections will be closed after idling
+  for this duration. Overrides `max_conn_idle_time`.
+- `pool_max_conn_lifetime` (duration: for example "500ms", "5s", "30m", "1h"): Sets the time after which a connection will be
+  closed, irrespective of how long it has been idle. Overrides `max_conn_lifetime`.
+- `pool_max_conn_lifetime_jitter` (duration: for example "500ms", "5s", "30m", "1h"): Jitter to add to the
+  `pool_max_conn_lifetime` value. This is useful to avoid thundering herd problems when many connections are closed and re-opened
+  at the same time.
+- `pool_health_check_period` (duration: for example "500ms", "5s", "30m", "1h"): Sets the period for health checks to potentially
+  kill stale connections. Defaults to "1m".
+
+## When to use high-performance pooling
+
+Standard pooling opens connections on demand and closes them after idle timeout, which can cause connection storms during sudden
+traffic spikes. High-performance pooling maintains `min_pool` persistent connections and includes refresh jitter to prevent
+synchronized resets, without initialization overhead and reducing the risk of database overload during demand surges.
+
+Consider high-performance pooling when your workload exhibits:
+
+- Large, unpredictable traffic spikes
+- Sudden transitions from low to high request volume
+- Time-sensitive operations where connection initialization latency is problematic
+
+For steady-state traffic or gradual load changes, standard pooling may be enough.
+
+## When not to use high-performance pooling
+
+High-performance pooling does not reload TLS certificates while the process is running. If database TLS certificates change, you
+must restart the Ory service to establish connections using the new certificates. Standard pooling supports hot reloading of TLS
+certificates because connections close after idle timeout and reconnect with refreshed credentials.

src/sidebar.ts

@@ -1213,6 +1213,7 @@ const oel: SidebarItemsConfig = [
     items: ["self-hosted/oel/polis/changelog"],
   },
   "self-hosted/oel/monitoring/monitoring",
+  "self-hosted/oel/high-performance-pooling",
 ]
 
 const security: SidebarItemsConfig = [