fix/added pool size, overflow, timeout and recycle configs

Author: chintakjoshi

app/config.py

@@ -55,6 +55,10 @@ class DatabaseSettings(BaseModel):
     """Database connection settings."""
 
     url: str = Field(description="Async SQLAlchemy URL using asyncpg driver.")
+    pool_size: int = Field(default=20, ge=1)
+    max_overflow: int = Field(default=20, ge=0)
+    pool_timeout_seconds: int = Field(default=30, ge=1)
+    pool_recycle_seconds: int = Field(default=1800, ge=1)
 
     @field_validator("url")
     @classmethod

app/db/session.py

@@ -23,7 +23,14 @@ async def _dispose_async_engine(engine: AsyncEngine) -> None:
 def get_engine() -> AsyncEngine:
     """Build and cache the async SQLAlchemy engine."""
     settings = get_settings()
-    return create_async_engine(settings.database.url, pool_pre_ping=True)
+    return create_async_engine(
+        settings.database.url,
+        pool_pre_ping=True,
+        pool_size=settings.database.pool_size,
+        max_overflow=settings.database.max_overflow,
+        pool_timeout=settings.database.pool_timeout_seconds,
+        pool_recycle=settings.database.pool_recycle_seconds,
+    )
 
 
 @reloadable_singleton

docs/configuration.md

@@ -98,6 +98,14 @@ Forbidden in production:
 
 - `DATABASE__URL`
   must use the `postgresql+asyncpg://` SQLAlchemy URL form
+- `DATABASE__POOL_SIZE`
+  steady-state SQLAlchemy pool size, defaults to `20`
+- `DATABASE__MAX_OVERFLOW`
+  extra connections permitted above `DATABASE__POOL_SIZE`, defaults to `20`
+- `DATABASE__POOL_TIMEOUT_SECONDS`
+  how long to wait for a pooled connection before failing, defaults to `30`
+- `DATABASE__POOL_RECYCLE_SECONDS`
+  maximum connection age before SQLAlchemy recycles it on checkout, defaults to `1800`
 
 ### Redis
 

docs/operations.md

@@ -125,6 +125,19 @@ Tune these if the Redis path is behind an idle-sensitive proxy or load balancer:
 The worker intentionally keeps its blocking dequeue window below common managed
 Redis idle timeouts.
 
+## Database Pool Tuning
+
+The API uses explicit SQLAlchemy pool tuning rather than library defaults. The
+main knobs are:
+
+- `DATABASE__POOL_SIZE`
+- `DATABASE__MAX_OVERFLOW`
+- `DATABASE__POOL_TIMEOUT_SECONDS`
+- `DATABASE__POOL_RECYCLE_SECONDS`
+
+`DATABASE__POOL_RECYCLE_SECONDS` is especially important for managed Postgres
+providers and proxies that silently drop older idle connections.
+
 ## Retention Purge
 
 The scheduler registers the recurring retention-purge job only when:

tests/unit/test_config_production_hardening.py

@@ -76,11 +76,33 @@ def test_development_settings_allow_empty_prod_only_fields() -> None:
     settings = _build_settings()
     assert settings.app.environment == "development"
     assert settings.app.allowed_hosts == []
+    assert settings.database.pool_size == 20
+    assert settings.database.max_overflow == 20
+    assert settings.database.pool_timeout_seconds == 30
+    assert settings.database.pool_recycle_seconds == 1800
     assert settings.session_security.refresh_token_hash_key is None
     assert settings.signing_keys.encryption_key is None
     assert settings.webhook.secret_encryption_key is None
 
 
+@pytest.mark.parametrize(
+    ("field_name", "value"),
+    [
+        ("pool_size", 0),
+        ("max_overflow", -1),
+        ("pool_timeout_seconds", 0),
+        ("pool_recycle_seconds", 0),
+    ],
+)
+def test_database_settings_reject_invalid_pool_tuning(field_name: str, value: int) -> None:
+    """Database pool tuning should reject invalid non-positive values."""
+    with pytest.raises(ValueError):
+        DatabaseSettings(
+            url="postgresql+asyncpg://user:pass@db.example.com:5432/auth_service",
+            **{field_name: value},
+        )
+
+
 @pytest.mark.parametrize(
     ("mutate", "message"),
     [

tests/unit/test_reloadable_singletons.py

@@ -40,6 +40,10 @@ def _seed_minimal_env(
     monkeypatch: pytest.MonkeyPatch,
     *,
     database_url: str = "postgresql+asyncpg://user:pass@db.example.com:5432/auth_service",
+    database_pool_size: str = "20",
+    database_max_overflow: str = "20",
+    database_pool_timeout_seconds: str = "30",
+    database_pool_recycle_seconds: str = "1800",
     redis_url: str = "redis://redis.example.com:6379/0",
     access_ttl_seconds: str = "900",
     refresh_ttl_seconds: str = "604800",
@@ -48,6 +52,10 @@ def _seed_minimal_env(
     monkeypatch.setenv("APP__ENVIRONMENT", "development")
     monkeypatch.setenv("APP__SERVICE", "auth-service")
     monkeypatch.setenv("DATABASE__URL", database_url)
+    monkeypatch.setenv("DATABASE__POOL_SIZE", database_pool_size)
+    monkeypatch.setenv("DATABASE__MAX_OVERFLOW", database_max_overflow)
+    monkeypatch.setenv("DATABASE__POOL_TIMEOUT_SECONDS", database_pool_timeout_seconds)
+    monkeypatch.setenv("DATABASE__POOL_RECYCLE_SECONDS", database_pool_recycle_seconds)
     monkeypatch.setenv("REDIS__URL", redis_url)
     monkeypatch.setenv("JWT__ALGORITHM", "RS256")
     monkeypatch.setenv("JWT__PRIVATE_KEY_PEM", "private-key")
@@ -198,6 +206,40 @@ def _create_async_engine(url: str, **kwargs: object) -> _AsyncEngineStub:
     ]
 
 
+def test_get_engine_applies_configured_pool_tuning(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Engine factory should pass validated pool tuning to SQLAlchemy."""
+    _seed_minimal_env(
+        monkeypatch,
+        database_pool_size="32",
+        database_max_overflow="48",
+        database_pool_timeout_seconds="45",
+        database_pool_recycle_seconds="2700",
+    )
+    _clear_reloadable_getters()
+    captured: dict[str, object] = {}
+
+    def _create_async_engine(url: str, **kwargs: object) -> _AsyncEngineStub:
+        captured["url"] = url
+        captured["kwargs"] = dict(kwargs)
+        return _AsyncEngineStub(url)
+
+    monkeypatch.setattr(db_session_module, "create_async_engine", _create_async_engine)
+
+    engine = db_session_module.get_engine()
+
+    assert engine is not None
+    assert captured == {
+        "url": "postgresql+asyncpg://user:pass@db.example.com:5432/auth_service",
+        "kwargs": {
+            "pool_pre_ping": True,
+            "pool_size": 32,
+            "max_overflow": 48,
+            "pool_timeout": 45,
+            "pool_recycle": 2700,
+        },
+    }
+
+
 @pytest.mark.asyncio
 async def test_get_session_service_refreshes_nested_dependencies_when_settings_change(
     monkeypatch: pytest.MonkeyPatch,