feat: add environment variables to allow configuration of django persistent connections (#1861)

Author: gustavobtflores

.env.example

@@ -26,6 +26,10 @@ DB_PASSWORD=CHANGE_ME
 DB_ENGINE=django.db.backends.postgresql
 DB_OPTIONS_CONNECT_TIMEOUT=16
 
+# Django persistent connections (production): enable for better performance
+# DB_CONN_MAX_AGE=60          # Seconds to keep connections open (0 = close after each request)
+# DB_CONN_HEALTH_CHECKS=True  # Verify connection is alive before reuse (recommended with persistent connections)
+
 # Optional: separate application database user/name for setup-dashboard-db.sh.
 # Defaults to DB_USER / DB_NAME if not set.
 # APP_DB_USER=dashboard

backend/README.md

@@ -52,6 +52,26 @@ export DB_PORT=5432
 export DB_ENGINE=django_prometheus.db.backends.postgresql
 export DB_OPTIONS_CONNECT_TIMEOUT=16
 ```
+
+#### Connection Pooling (Production)
+
+For production deployments, you can enable persistent database connections to reduce connection overhead:
+
+```sh
+# Enable persistent connections (value in seconds)
+export DB_CONN_MAX_AGE=60
+
+# Enable health checks to verify connections before reuse (recommended by Django docs)
+export DB_CONN_HEALTH_CHECKS=True
+```
+
+- `DB_CONN_MAX_AGE`: Controls how long database connections are kept open for reuse.
+  - `0` (default): Close connection after each request (development mode)
+  - Positive integer: Keep connections open for that many seconds
+  - Not recommended for local development as the dev server creates a new thread per request
+
+- `DB_CONN_HEALTH_CHECKS`: When `True`, Django verifies the connection is still alive before reusing it. This prevents errors after database restarts or when connections are terminated by the server.
+
 > [!NOTE]
 > It is possible to have authentication issues when escaping special characters. In some cases, it is necessary to add more than one backslash, while in others, no addition is needed. To assist with this, you can export `DEBUG_DB_VARS=True` to check the database connection info in the terminal, allowing you to determine if the characters got escaped as intended. **This variable should NOT be set to True in production**.
 
@@ -229,7 +249,7 @@ In order to debug backend in PyCharm, just follow these steps:
    - in `Run` session of the dialog, select `script`, then find the script `manage.py` at the `backend` folder
    - at `script` name input, just enter `runserver`
    - at `Environment Variables`, enter the following values:
-     - `DB_ENGINE`: `django.db.backends.postgresql`, `DB_NAME`: `dashboard`, `DB_USER`: `<youremail>@profusion.mobi`, `DB_PASSWORD`: `<yourpassword>`, `DB_HOST`: `127.0.0.1`, `DB_PORT`: `5432`, `DB_OPTIONS_CONNECT_TIMEOUT`: `16`
+     - `DB_ENGINE`: `django.db.backends.postgresql`, `DB_NAME`: `dashboard`, `DB_USER`: `<youremail>@profusion.mobi`, `DB_PASSWORD`: `<yourpassword>`, `DB_HOST`: `127.0.0.1`, `DB_PORT`: `5432`, `DB_OPTIONS_CONNECT_TIMEOUT`: `16`, `DB_CONN_MAX_AGE`: `0`, `DB_CONN_HEALTH_CHECKS`: `False`
      - `DEBUG`: `True`
 
 Quote character in password field is escaped normally with `\"` .

backend/kernelCI/settings.py

@@ -261,6 +261,10 @@ def get_json_env_var(name, default):
     "HOST": os.getenv("DB_HOST", "127.0.0.1"),
     "PORT": os.getenv("DB_PORT", "5432"),
     "ENGINE": os.getenv("DB_ENGINE", "django_prometheus.db.backends.postgresql"),
+    "CONN_MAX_AGE": int(os.getenv("DB_CONN_MAX_AGE", "0")),
+    "CONN_HEALTH_CHECKS": is_boolean_or_string_true(
+        os.environ.get("DB_CONN_HEALTH_CHECKS", False)
+    ),
     "OPTIONS": {
         "connect_timeout": int(os.getenv("DB_OPTIONS_CONNECT_TIMEOUT", "16")),
     },