Neon’s auto-suspend feature can dramatically cut costs by powering down your database when it’s not in use.
Here’s how it works: when your Neon compute branch detects a period of inactivity, it automatically suspends the branch. This effectively stops all incoming connections and query processing, and importantly, stops incurring compute charges. When a new connection or query arrives, Neon automatically resumes the branch, bringing it back online. The key is that this suspend/resume cycle is transparent to your application – it just experiences a brief pause and then normal operation.
Let’s see it in action. Imagine you have a Neon project with a main branch. By default, this branch might be configured to suspend after 5 minutes of inactivity.
{
"id": "br_main",
"name": "main",
"project_id": "pr_12345",
"settings": {
"suspend_timeout_seconds": 300, // 5 minutes
"auto_suspend": true
},
// ... other branch settings
}
If no queries are executed against this branch for 5 minutes, Neon’s system will detect this inactivity. You won’t see any immediate error messages, but the compute resources for br_main will be deallocated.
Now, if a user tries to access your application, and the application attempts to connect to the main branch, Neon’s connection pooler will receive the request. It will attempt to establish a connection to the suspended compute. This is where the magic happens: instead of failing, Neon’s infrastructure intercepts this. It triggers the resume process for br_main.
The resume process involves reallocating compute resources and bringing the PostgreSQL instance back online. This takes a few seconds. During this time, the initial connection attempt might timeout from the application’s perspective. However, once the branch is resumed, subsequent connection attempts will succeed immediately. Most modern connection pooling libraries are designed to handle these brief resume delays gracefully, retrying connections until they succeed.
The primary lever you control is suspend_timeout_seconds. This setting determines how long Neon waits for activity before suspending. A shorter timeout saves more money but increases the chance of experiencing a resume delay. A longer timeout reduces resume delays but costs more. You’ll find this setting within your Neon project’s branch configuration.
You can adjust this value directly via the Neon API or through the Neon Console. For instance, to set the auto-suspend timeout to 15 minutes (900 seconds), you would update the branch’s settings:
neonctl branches update br_main --settings='{"suspend_timeout_seconds": 900, "auto_suspend": true}'
The auto_suspend flag itself is crucial. If auto_suspend is false, the branch will never suspend, regardless of the suspend_timeout_seconds value.
The actual mechanism for detecting inactivity isn’t just about idle connections; it’s about the absence of any query execution or connection establishment activity against the compute endpoint for that branch. Neon’s control plane monitors these metrics. When the configured timeout is reached, it signals the compute plane to deallocate resources. The resume is triggered by the first incoming network packet destined for the suspended compute endpoint.
Many developers assume that if a connection is open, the database won’t suspend. However, Neon’s auto-suspend is based on active query execution, not just the presence of an open TCP connection. A connection that is established but remains idle for longer than the suspend_timeout_seconds will still lead to suspension. This is a key nuance for understanding when you might encounter resume delays.
The next concept to explore is Neon’s branching strategy and how managing multiple branches impacts your overall cost and operational complexity.