db connections

docs/getting-started/env-configuration.mdx

@@ -5553,11 +5553,19 @@ To use SQLCipher with existing data, you must either start fresh (with users exp
 - Default: `None`
 - Description: Specifies the pooling strategy and size of the database pool. By default SQLAlchemy will automatically chose the proper pooling strategy for the selected database connection. A value of `0` disables pooling. A value larger `0` will set the pooling strategy to `QueuePool` and the pool size accordingly.
 
+:::tip High-Concurrency Deployments
+
+For deployments with many concurrent users, consider increasing both `DATABASE_POOL_SIZE` and `DATABASE_POOL_MAX_OVERFLOW`. A good starting point is `DATABASE_POOL_SIZE=15` and `DATABASE_POOL_MAX_OVERFLOW=20`.
+
+**Important:** The combined total (`DATABASE_POOL_SIZE` + `DATABASE_POOL_MAX_OVERFLOW`) should remain well below your database server's `max_connections` limit. PostgreSQL defaults to 100 max connections, so keeping the combined total under 50-80 per Open WebUI instance is recommended to leave room for other clients and maintenance connections.
+
+:::
+
 #### `DATABASE_POOL_MAX_OVERFLOW`
 
 - Type: `int`
 - Default: `0`
-- Description: Specifies the database pool max overflow.
+- Description: Specifies the database pool max overflow. This allows additional connections beyond `DATABASE_POOL_SIZE` during traffic spikes.
 
 :::info
 

docs/troubleshooting/multi-replica.mdx

@@ -131,7 +131,11 @@ Refer to the **[Cloud Infrastructure Latency](/tutorials/tips/performance#%EF%B8
 
 ### 7. Optimizing Database Performance
 
-For PostgreSQL deployments with adequate resources, enabling database session sharing can improve performance under high concurrency:
+For PostgreSQL deployments with adequate resources, consider these optimizations:
+
+#### Database Session Sharing
+
+Enabling session sharing can improve performance under high concurrency:
 
 ```bash
 DATABASE_ENABLE_SESSION_SHARING=true
@@ -139,6 +143,19 @@ DATABASE_ENABLE_SESSION_SHARING=true
 
 See [DATABASE_ENABLE_SESSION_SHARING](/getting-started/env-configuration#database_enable_session_sharing) for details.
 
+#### Connection Pool Sizing
+
+If you experience `QueuePool limit reached` errors or connection timeouts under high concurrency, increase the pool size:
+
+```bash
+DATABASE_POOL_SIZE=15 (or higher)
+DATABASE_POOL_MAX_OVERFLOW=20 (or higher)
+```
+
+**Important:** The combined total (`DATABASE_POOL_SIZE` + `DATABASE_POOL_MAX_OVERFLOW`) should remain well below your database's `max_connections` limit. PostgreSQL defaults to 100 max connections, so keep the combined total under 50-80 per Open WebUI instance to leave room for other clients and maintenance operations.
+
+See [DATABASE_POOL_SIZE](/getting-started/env-configuration#database_pool_size) for details.
+
 ---
 
 ## Deployment Best Practices

docs/tutorials/tips/performance.md

@@ -112,6 +112,15 @@ If you upgraded to v0.7.0 and experienced slow admin page loads, API timeouts, o
 
 :::
 
+### Connection Pool Sizing
+
+For high-concurrency PostgreSQL deployments, the default connection pool settings may be insufficient. If you experience `QueuePool limit reached` errors or connection timeouts, increase the pool size:
+
+-   **Env Var**: `DATABASE_POOL_SIZE=15` (default: uses SQLAlchemy defaults)
+-   **Env Var**: `DATABASE_POOL_MAX_OVERFLOW=20` (default: 0)
+
+**Important:** The combined total (`DATABASE_POOL_SIZE` + `DATABASE_POOL_MAX_OVERFLOW`) should remain well below your database's `max_connections` limit. PostgreSQL defaults to 100 max connections, so keep the combined total under 50-80 per Open WebUI instance to leave room for other clients and maintenance operations.
+
 ### Vector Database (RAG)
 For multi-user setups, the choice of Vector DB matters.