Your database survives self-service

A dashboard with fifteen cards is fifteen queries. Put it on a wall display with a one-minute auto-refresh, share it with a department, and the arithmetic runs away from you quickly. Nobody involved did anything wrong — they built a dashboard, which is the entire point of the product — but the source database now sees a sustained burst of analytical queries it was never sized for.

The classic outcome is not a slow dashboard. It is connection-pool exhaustion on the application that shares the database, at which point the analytics tool has taken down the system it was supposed to be reporting on. Retrying makes it worse. This is the single most common way self-service BI loses the trust of the team that runs the database.

Every Qrly connection has a governor: a semaphore sized to that connection's max concurrent queries, fronted by a FIFO wait queue capped at max queue size. Queries that cannot acquire a permit wait in order. Queries that arrive when the queue is already full get an immediate queue-full error, and a query that has waited longer than queue wait timeout is failed rather than left hanging.

The refusal is the feature. A tool that queues without bound eventually delivers every one of those queries to the database, just later and all at once. Qrly bounds the queue and returns an error, so load shedding happens in the BI tier where it is cheap, not in the database where it is not.

Governor lifecycle events are persisted on a background executor, so recording them never sits on the query's own critical path. The admin page shows live per-connection statistics — active, queued, max concurrent, max queue and last wait — with auto-refresh, alongside a recent-events table.

That turns "the dashboard felt slow this morning" into a question with an answer. You can see whether queries were waiting, how long, on which connection, and whether the queue was ever full — before you start blaming the database.

Concurrency limits shape the peak. Budgets shape the total. Each user has an effective daily budget resolved as per-user override → organisation default → 1000, checked and reserved atomically before every query and made race-safe by an upsert on the (user, date) pair — so two browser tabs cannot both spend the last query.

Bytes returned and AI tokens are recorded asynchronously afterwards. Administrators get a budget page, a per-user editor, a reset action and a usage report; users see their own remaining budget on their profile, which stops the whole thing being a mystery when a query is refused.

The first tier lives in the process. It stores encrypted bytes rather than object graphs, and it is budgeted in bytes twice over — once per connection and once JVM-wide — with registered evictors that evict the entries nearest to expiry first. That is a deliberately unfashionable policy: it protects the entries with the most useful life left, rather than the ones that happen to have been touched recently.

Because it is in-process, it is the fastest tier and it is gone on restart. It is the right tier for a dashboard that ten people open in the same ten minutes.

T1 can also hold results in a columnar layout using typed primitive arrays per column — LONG, DOUBLE, STRING and BOOLEAN — rather than boxed row objects. The point is CPU-cache-friendly scans: a column of longs read sequentially out of a primitive array behaves very differently from the same data spread across a million small objects.

Hit counters and byte estimates are tracked per entry, so the columnar store is measurable rather than a matter of faith.

Pointed at the shared application database, T2 gives cross-instance hits at roughly ten milliseconds: one node runs the query, every node in the cluster benefits. The registry is warmed from T2 at startup, so a rolling restart does not throw away everything the cluster had learned.

This is the sensible default for a clustered deployment where all instances serve the same tenants.

The alternative T2 backend is a SQLite file in WAL mode, one per connection, laid out on disk as {basePath}/{tenantSlug}/{orgSlug}/{connectionId}/cache.db. It is node-local rather than cluster-shared, and it buys something the shared database cannot: physical separation. One tenant's cached results are a different file, in a different directory, on a path you can point at in an audit.

Both backends carry the columnar layout in a compact self-describing binary wire format, so what T1 held in memory is what T2 writes to disk.

Cached results are encrypted at rest in the JVM tier and in the persistent tier. The cache never stores plaintext rows — not in memory, not in the shared application database, not in the SQLite file.

This is the difference between a cache you can enable on a connection carrying customer data and one you cannot. A cache that quietly duplicates production rows into a second, less-protected store is a compliance problem wearing a performance costume.

The cache key is a SHA-256 hash of the organisation, the connection, the SQL with whitespace collapsed and keywords normalised, and the parameters sorted by name. Two logically identical queries that differ only in formatting or parameter ordering hit the same entry.

Because the organisation and connection are part of the key, a result can never be served across a tenant boundary — the key space is partitioned by construction, not by a filter someone has to remember to apply.

Callers can pass NORMAL, NO_CACHE or NO_STORE to bypass or refuse to populate the cache for a specific run — useful when someone is reconciling a figure and wants to be certain they are looking at the source. Concurrent requests for the same key are de-duplicated so only one of them runs the query.

Per-connection consecutive-failure counters feed a ten-minute circuit breaker, and dispatch runs on virtual threads. A cache backend that starts failing stops being asked, rather than adding latency to every request while it fails.

This is the rule the rest of the design hangs off: cache failures degrade to a miss, never to an error. If the cache cannot answer, cannot decrypt, or cannot be reached, the query runs against the source and the user sees a result.

It means enabling caching cannot make your reporting less available than it was before you enabled it. The worst case is the performance you already had.