From 12b8602d1f954b0b2aa3c9f621226a62a82f91b7 Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 28 Oct 2025 12:54:23 -0300 Subject: [PATCH 1/5] fix: high-perf pooling doc --- docs/self-hosted/deployment.md | 26 +------- .../oel/oel-high-performance-pooling.mdx | 60 +++++++++++++++++++ src/sidebar.ts | 1 + 3 files changed, 63 insertions(+), 24 deletions(-) create mode 100644 docs/self-hosted/oel/oel-high-performance-pooling.mdx diff --git a/docs/self-hosted/deployment.md b/docs/self-hosted/deployment.md index 9a3063381..51cbb5fb2 100644 --- a/docs/self-hosted/deployment.md +++ b/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 diff --git a/docs/self-hosted/oel/oel-high-performance-pooling.mdx b/docs/self-hosted/oel/oel-high-performance-pooling.mdx new file mode 100644 index 000000000..7488864dd --- /dev/null +++ b/docs/self-hosted/oel/oel-high-performance-pooling.mdx @@ -0,0 +1,60 @@ +--- +id: high-performance-pooling +title: High-performance database connection pooling +sidebar_label: High-performance pooling +--- + +High-performance pooling is available only in the Ory Enterprise License (OEL). It uses +[pgxpool](https://pkg.go.dev/github.com/jackc/pgx/v5/pgxpool) and 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". + +## Key differences from standard pooling + +### Standard pooling behavior + +- Opens connections on demand +- Closes idle connections after timeout +- During traffic spikes, must initialize many new connections simultaneously +- Can cause database overload, timeouts, or connection storms when traffic surges suddenly + +### High-performance pooling behavior + +- Maintains min_pool connections open at all times +- Traffic spikes use pre-established connections +- Avoids connection initialization overhead during demand peaks +- Reduces risk of overwhelming the database during sudden load increases + +### Connection refresh jitter + +High-performance pooling includes randomized jitter when refreshing connections. This prevents synchronized connection resets that +could cause momentary overload when all connections attempt to restart simultaneously. + +## When to use high-performance pooling + +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. + +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. diff --git a/src/sidebar.ts b/src/sidebar.ts index ee9ab58ab..c4d328f5e 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -1211,6 +1211,7 @@ const oel: SidebarItemsConfig = [ items: ["self-hosted/oel/polis/changelog"], }, "self-hosted/oel/monitoring/monitoring", + "self-hosted/oel/high-performance-pooling", ] const security: SidebarItemsConfig = [ From 181f634db491db150e586bc18f2a4d1fe6b73a86 Mon Sep 17 00:00:00 2001 From: Vincent Date: Thu, 30 Oct 2025 11:25:09 -0300 Subject: [PATCH 2/5] chore: apply suggestion from code review Co-authored-by: hackerman <3372410+aeneasr@users.noreply.github.com> --- docs/self-hosted/oel/oel-high-performance-pooling.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/self-hosted/oel/oel-high-performance-pooling.mdx b/docs/self-hosted/oel/oel-high-performance-pooling.mdx index 7488864dd..173245cf9 100644 --- a/docs/self-hosted/oel/oel-high-performance-pooling.mdx +++ b/docs/self-hosted/oel/oel-high-performance-pooling.mdx @@ -4,7 +4,7 @@ title: High-performance database connection pooling sidebar_label: High-performance pooling --- -High-performance pooling is available only in the Ory Enterprise License (OEL). It uses +High-performance pooling is available only with an Ory Enterprise License (OEL). It uses [pgxpool](https://pkg.go.dev/github.com/jackc/pgx/v5/pgxpool) and provides additional configuration options for managing database connections under variable load. From e410fe371743ab3ce1df875f21996c676af1353f Mon Sep 17 00:00:00 2001 From: Vincent Date: Thu, 30 Oct 2025 11:25:25 -0300 Subject: [PATCH 3/5] chore: apply suggestion from code review Co-authored-by: hackerman <3372410+aeneasr@users.noreply.github.com> --- docs/self-hosted/oel/oel-high-performance-pooling.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/self-hosted/oel/oel-high-performance-pooling.mdx b/docs/self-hosted/oel/oel-high-performance-pooling.mdx index 173245cf9..d2dbe8579 100644 --- a/docs/self-hosted/oel/oel-high-performance-pooling.mdx +++ b/docs/self-hosted/oel/oel-high-performance-pooling.mdx @@ -55,6 +55,8 @@ Consider high-performance pooling when your workload exhibits: 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. From 9053bc9e023f826bd08e360612cc404c2d8833a4 Mon Sep 17 00:00:00 2001 From: Vincent Date: Mon, 10 Nov 2025 11:51:07 -0300 Subject: [PATCH 4/5] chore: apply suggestions from code review Co-authored-by: Arne Luenser --- docs/self-hosted/oel/oel-high-performance-pooling.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/self-hosted/oel/oel-high-performance-pooling.mdx b/docs/self-hosted/oel/oel-high-performance-pooling.mdx index d2dbe8579..09c30e9c6 100644 --- a/docs/self-hosted/oel/oel-high-performance-pooling.mdx +++ b/docs/self-hosted/oel/oel-high-performance-pooling.mdx @@ -4,9 +4,8 @@ title: High-performance database connection pooling sidebar_label: High-performance pooling --- -High-performance pooling is available only with an Ory Enterprise License (OEL). It uses -[pgxpool](https://pkg.go.dev/github.com/jackc/pgx/v5/pgxpool) and provides additional configuration options for managing database -connections under variable load. +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. From 3d78b13d361bc9b8833ae3b7666b9deec494fdc6 Mon Sep 17 00:00:00 2001 From: vinckr Date: Mon, 10 Nov 2025 11:55:34 -0300 Subject: [PATCH 5/5] chore: omit slop --- .../oel/oel-high-performance-pooling.mdx | 29 ++++--------------- 1 file changed, 6 insertions(+), 23 deletions(-) diff --git a/docs/self-hosted/oel/oel-high-performance-pooling.mdx b/docs/self-hosted/oel/oel-high-performance-pooling.mdx index 09c30e9c6..a948b9881 100644 --- a/docs/self-hosted/oel/oel-high-performance-pooling.mdx +++ b/docs/self-hosted/oel/oel-high-performance-pooling.mdx @@ -4,8 +4,8 @@ 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. +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. @@ -23,29 +23,12 @@ enabled. - `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". -## Key differences from standard pooling - -### Standard pooling behavior - -- Opens connections on demand -- Closes idle connections after timeout -- During traffic spikes, must initialize many new connections simultaneously -- Can cause database overload, timeouts, or connection storms when traffic surges suddenly - -### High-performance pooling behavior - -- Maintains min_pool connections open at all times -- Traffic spikes use pre-established connections -- Avoids connection initialization overhead during demand peaks -- Reduces risk of overwhelming the database during sudden load increases - -### Connection refresh jitter - -High-performance pooling includes randomized jitter when refreshing connections. This prevents synchronized connection resets that -could cause momentary overload when all connections attempt to restart simultaneously. - ## 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