Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

perf(agent-bridge): take the sequential scan off the heartbeat path and size the DB pool for it (#344)

Louis Amaudruz5f412cd64e73
diff --git a/core/switch_core/config.py b/core/switch_core/config.py
index f5139e313..7f8f100b6 100644
--- a/core/switch_core/config.py
+++ b/core/switch_core/config.py
@@ -72,10 +72,19 @@ class SwitchConfig(BaseSettings):
# of being truncated or silently dropped.
agent_media_max_bytes: int = 20 * 1024 * 1024
- db_pool_size: int = 20
+ # Every authenticated agent request resolves its bearer token against the
+ # database before the handler runs, and each live agent connection beats
+ # every 2s, so the pool is sized against connection count rather than
+ # human traffic: a fleet of N connections costs roughly N/2 checkouts per
+ # second. Exceeding the pool does not shed load, it queues, and a queued
+ # heartbeat that misses HEARTBEAT_TTL_SECONDS costs the connection.
+ db_pool_size: int = 30
db_max_overflow: int = 10
db_pool_recycle: int = 1800
db_pool_pre_ping: bool = True
+ # SQLAlchemy's default is 30s, long enough that pool starvation surfaces as
+ # unexplained latency rather than an error. Fail fast and loudly instead.
+ db_pool_timeout: float = 5.0
# libpq-style TLS mode for the Postgres connection, forwarded to asyncpg.
# "disable" (the default) keeps in-cluster / local-dev connections plain,
diff --git a/core/switch_core/db/engine.py b/core/switch_core/db/engine.py
index 661c7b405..b8bc989ed 100644
--- a/core/switch_core/db/engine.py
+++ b/core/switch_core/db/engine.py
@@ -20,6 +20,7 @@ def create_engine_from_config(
"max_overflow": config.db_max_overflow,
"pool_recycle": config.db_pool_recycle,
"pool_pre_ping": config.db_pool_pre_ping,
+ "pool_timeout": config.db_pool_timeout,
"connect_args": connect_args,
}
defaults.update(engine_kwargs)
diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.py
index 3485bb5b7..6798bfe95 100644
--- a/core/switch_core/db/models.py
+++ b/core/switch_core/db/models.py
@@ -117,8 +117,11 @@ class Agent(Base):
client_id: Mapped[str] = mapped_column(
Text, ForeignKey("clients.id"), unique=True, nullable=False
)
+ # Indexed because bearer-token auth resolves the key row and then looks the
+ # agent up by this column on every authenticated request, heartbeats
+ # included — without it that is a sequential scan per beat.
api_key_id: Mapped[str] = mapped_column(
- Text, ForeignKey("api_keys.id"), nullable=False
+ Text, ForeignKey("api_keys.id"), nullable=False, index=True
)
owner_id: Mapped[str | None] = mapped_column(
Text, ForeignKey("users.id"), nullable=True
diff --git a/core/switch_core/migrations/versions/f3b81c47d9a2_index_agents_api_key_id.py b/core/switch_core/migrations/versions/f3b81c47d9a2_index_agents_api_key_id.py
new file mode 100644
index 000000000..d0e21cddb
--- /dev/null
+++ b/core/switch_core/migrations/versions/f3b81c47d9a2_index_agents_api_key_id.py
@@ -0,0 +1,25 @@
+"""index agents.api_key_id
+
+Revision ID: f3b81c47d9a2
+Revises: a2171c0de1f4
+Create Date: 2026-09-02
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "f3b81c47d9a2"
+down_revision: str | None = "a2171c0de1f4"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ op.create_index("ix_agents_api_key_id", "agents", ["api_key_id"])
+
+
+def downgrade() -> None:
+ op.drop_index("ix_agents_api_key_id", table_name="agents")
diff --git a/deploy/remote/helm/switch/templates/_helpers.tpl b/deploy/remote/helm/switch/templates/_helpers.tpl
index 889025039..87ebab2ad 100644
--- a/deploy/remote/helm/switch/templates/_helpers.tpl
+++ b/deploy/remote/helm/switch/templates/_helpers.tpl
@@ -227,6 +227,12 @@ Include with `nindent 12`.
value: {{ include "switch.postgresDatabase" . | quote }}
- name: DB_SSL_MODE
value: {{ .Values.postgresql.sslMode | quote }}
+- name: DB_POOL_SIZE
+ value: {{ .Values.postgresql.pool.size | quote }}
+- name: DB_MAX_OVERFLOW
+ value: {{ .Values.postgresql.pool.maxOverflow | quote }}
+- name: DB_POOL_TIMEOUT
+ value: {{ .Values.postgresql.pool.timeout | quote }}
- name: MATRIX_SERVER
value: "http://{{ include "switch.tuwunelHost" . }}:8008"
- name: MATRIX_SERVER_NAME
diff --git a/deploy/remote/helm/switch/templates/postgresql/statefulset.yaml b/deploy/remote/helm/switch/templates/postgresql/statefulset.yaml
index c2c70ce20..49ceba5a3 100644
--- a/deploy/remote/helm/switch/templates/postgresql/statefulset.yaml
+++ b/deploy/remote/helm/switch/templates/postgresql/statefulset.yaml
@@ -25,6 +25,13 @@ spec:
- name: postgresql
image: {{ .Values.postgresql.image }}
imagePullPolicy: {{ .Values.postgresql.imagePullPolicy }}
+ {{- with .Values.postgresql.parameters }}
+ args:
+ {{- range $name, $value := . }}
+ - -c
+ - {{ printf "%s=%v" $name $value | quote }}
+ {{- end }}
+ {{- end }}
ports:
- containerPort: 5432
protocol: TCP
diff --git a/deploy/remote/helm/switch/values.yaml b/deploy/remote/helm/switch/values.yaml
index c5a1cccc1..2f7baa22a 100644
--- a/deploy/remote/helm/switch/values.yaml
+++ b/deploy/remote/helm/switch/values.yaml
@@ -302,6 +302,22 @@ postgresql:
# managed cloud databases generally require "require" or stricter.
sslMode: disable
+ # switch-core's SQLAlchemy connection pool. Size this against the number of
+ # live agent connections, not human traffic: bearer-token auth hits the
+ # database on every authenticated request and each agent connection beats
+ # every 2s, so roughly N/2 checkouts per second for N connections. When the
+ # pool is exhausted requests queue rather than fail, and a heartbeat delayed
+ # past the server's TTL loses its connection — so under-sizing this shows up
+ # as fleet-wide agent disconnects, not as database errors.
+ # size + maxOverflow must stay under Postgres max_connections, remembering
+ # Mattermost and Keycloak share the same instance.
+ pool:
+ size: 30
+ maxOverflow: 10
+ # Seconds to wait for a free slot before raising. Deliberately short:
+ # SQLAlchemy's 30s default hides starvation as latency.
+ timeout: 5
+
# Password source. By default the password is read from the chart-managed
# Secret (secrets.postgresPassword). To source it from a pre-existing Secret
# instead (e.g. synced by external-secrets / sealed-secrets), set
@@ -333,6 +349,18 @@ postgresql:
limits:
memory: 512Mi
+ # Postgres server parameters, passed as `-c name=value`. Each client
+ # connection is a backend process costing several MB of non-reclaimable
+ # memory, so raising the pool above without also raising resources.limits
+ # .memory trades a connection-pool stall for an OOMKill — size them together.
+ # effective_cache_size in particular should track the memory limit rather
+ # than being left at the Postgres default, which assumes a far larger host.
+ # Example:
+ # parameters:
+ # effective_cache_size: 1536MB
+ # shared_buffers: 256MB
+ parameters: {}
+
# ── Backups ───────────────────────────────────────────────────────────────────
# This chart ships no backup jobs on purpose — an on-cluster backup shares the
# storage backend it is meant to protect, and every target already has stronger,