Hardware Limits & Graceful Exhaustion
What it is
Section titled “What it is”AetheriusDB couples two complementary protections. The first is proactive: before a query starts executing, the planner estimates its peak memory footprint. If the estimate would exceed safe capacity, the query is rejected up front with a precise error code — no work is done, no buffers are allocated. The second is reactive: if a surge slips past estimation, the out-of-memory condition is caught, the offending in-flight work is stopped in isolation, and the server keeps running.
The net effect is that the database does not get killed when a single query goes wrong. A pathological statement — a billion-row cross join, a runaway aggregation — fails its own request and frees its own resources. The other sessions on the cluster carry on without noticing.
Why it matters
Section titled “Why it matters”A traditional database hit by an out-of-memory kill loses every in-flight transaction across the whole process, prints a vague log line, and forces a crash-recovery cycle on restart. Graceful exhaustion turns a cluster-wide outage into a single failed query with an actionable error code.
- Pre-flight estimation — heavy queries are rejected before they allocate.
- Per-query isolation — one runaway statement cannot take down the server.
- Typed error — the client gets an
AE-MEM-*code that names the limit it hit. - Stays alive — the database holds onto its own lifecycle even under hostile workloads.
How you use it
Section titled “How you use it”The safety net is on by default; no configuration is needed for the protection itself. You can tune the threshold and observe how often it fires.
-- A deliberately expensive query against a giant table.SELECT a.*, b.* FROM huge_table a CROSS JOIN huge_table b;The query is rejected before any rows are produced, and the error tells you both what happened and how to fix it:
ERROR AE-MEM-0095 Query output exceeds physical capacity boundsEstimated peak working set: 2.4 TB; allowed: 480 GB.Try narrowing the join condition or rewriting as a window query.Inspect how often the safety net has fired, and tune the threshold if needed:
-- How often has the safety net fired in the last hour?SELECT code, count(*) FROM system.errors WHERE code LIKE 'AE-MEM-%' AND occurred_at > now() - INTERVAL '1 hour' GROUP BY code;
-- Tune the rejection threshold (optional; default rejects above 95%).ALTER SYSTEM SET memory_reject_threshold = 0.90;Clients can branch on the code and react — retry with a tighter predicate, escalate to a human, or pick a different access pattern.
Key concepts
Section titled “Key concepts”| Concept | What it means |
|---|---|
| Estimator | The planner stage that bounds a query’s peak working set before execution. |
| Rejection threshold | The capacity fraction (default 95%) above which a query is rejected outright. |
| Graceful degradation | Catching the rare surge that slips past, stopping only the offending work. |
AE-MEM-* | The family of typed errors for memory-pressure outcomes. |
flowchart LR
classDef a fill:#1f2640,stroke:#7c5cff,color:#e8eaf0
classDef b fill:#1f2640,stroke:#00d4ff,color:#e8eaf0
classDef g fill:#1f2640,stroke:#4ade80,color:#4ade80
classDef w fill:#1f2640,stroke:#fbbf24,color:#fbbf24
Q[Incoming query]:::a --> EST[Capacity<br/>estimator]:::b
EST -->|safe| EXEC[Execute]:::g
EST -->|exceeds threshold| REJ[Reject<br/>AE-MEM-0095]:::w
EXEC --> SURGE{Unexpected<br/>surge?}:::b
SURGE -->|yes| KILL[Stop offending<br/>work]:::w
SURGE -->|no| OK[Rows]:::g
KILL --> ERR[Typed error<br/>to client]:::w