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..a948b9881 --- /dev/null +++ b/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. 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 = [