Performance

⚡ Performance Tuning & Optimization

Stackhouse is a thin Axum server over PostgreSQL (relational data) and Qdrant (vector search) — there is no embedded LSM storage engine in this build, so tuning is mostly about tuning those two systems plus connection pooling, not app-level compaction/cache knobs.

Connection Pooling

Per-tenant pool settings are managed by PoolingService (stackhouse/src/platform/pooling.rs) and persisted in stackhouse_pool_configs:

{
  "pool_mode": "transaction",
  "max_connections": 100,
  "min_connections": 0,
  "idle_timeout_secs": 600,
  "max_lifetime_secs": 1800,
  "connection_timeout_secs": 30,
  "statement_timeout_secs": 30,
  "query_wait_timeout_secs": 30
}

max_connections defaults to 100 per tenant; lower it for smaller Postgres instances (e.g. Cloud SQL db-f1-micro) to avoid exhausting the server's own max_connections.

Vector Search

Vector collections are backed by Qdrant (stackhouse/src/storage/vectors.rs talks to the Qdrant HTTP API), which manages its own HNSW index (m, ef_construct, ef_search, etc.) server-side. Tune those via Qdrant's own collection config (see the Qdrant HNSW config docs) rather than through Stackhouse.

Indexes

Use standard CREATE INDEX via the raw-SQL admin endpoint or a migration for hot columns on Postgres tables; RLS policies (see Row-Level Security) that filter on a column benefit the most from an index on that column, since Postgres evaluates the USING expression per row.

Optimization Tips

Do

✅ Use batch operations where the API supports them ✅ Create Postgres indexes on hot/filtered columns (especially RLS USING columns) ✅ Size connection pools to your Postgres instance's max_connections ✅ Use read replicas for read-heavy workloads (see Replication)

Avoid

❌ Don't over-fetch data ❌ Avoid large, long-running transactions ❌ Don't create more indexes than your write workload can tolerate

Next: Monitoring