Fresh-connection probe (never pooled) that times connect/query/total for a Neon-style scale-to-zero compute, with --repeat/--every-seconds to catch the real cold-vs-warm gap and a --json summary (min/p50/p95/max). Verified for real against a local Postgres 16 container: happy path, --repeat/--every-seconds, --json, and all three failure paths (wrong port, wrong password, missing connection string) — see test-fixtures/local-postgres-verification.md for the full transcript, including an honest note on two false "cold" readings that transcript caught (local network/load jitter, not a real suspend/resume). No real Neon account was available in this environment (no credentials, and the Neon MCP needs an interactive browser OAuth this session can't complete) so the real Neon suspend/resume cycle itself is not verified live — logged honestly in the README's "Honest limits" section rather than claimed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
neon-cold-start-probe
Neon (and most serverless/autoscaling Postgres, including Scribase's own Free/Hobby tier) suspends a compute after a few idle minutes to save cost. The next connection has to wake it up before it can answer — slower than every connection after it. Nobody publishes a number for your database's wake-up time, and the usual advice is "it felt slow for a second." This measures it for real: a brand-new connection each time (never pooled — pooling is exactly what would hide the thing you're trying to see), timed in three parts (connect, query, total).
30-second quickstart
npx --yes git+https://git.ereboslab.com/caelum0x/neon-cold-start-probe.git \
"postgres://user:pass@ep-xxxx.region.aws.neon.tech/dbname?sslmode=require"
or clone it and run locally:
git clone https://git.ereboslab.com/caelum0x/neon-cold-start-probe.git
cd neon-cold-start-probe && npm install
node bin/neon-cold-start-probe.mjs "$DATABASE_URL"
Output:
probe 1/1: connect=931ms query=7ms total=938ms [COLD]
Seeing an actual cold start, not just a number
A single probe only tells you one connection's latency. To see the cold vs warm gap for real:
- Let the project sit idle past its suspend timeout (Neon's default/free setting is 5 minutes; check your project's compute settings for the real value).
- Run a
--repeatprobe immediately after — the first result is the one that had to wake the compute; the rest, back-to-back, will be warm because the first one already woke it:
node bin/neon-cold-start-probe.mjs "$DATABASE_URL" --repeat 5 --every-seconds 1
probe 1/5: connect=931ms query=7ms total=938ms [COLD]
probe 2/5: connect=14ms query=2ms total=16ms [warm]
probe 3/5: connect=13ms query=2ms total=15ms [warm]
probe 4/5: connect=12ms query=2ms total=14ms [warm]
probe 5/5: connect=15ms query=2ms total=17ms [warm]
summary: min=14ms p50=16ms p95=938ms max=938ms (1/5 probes >= 500ms, 0 failed)
Running --repeat back-to-back from a warm start (the default, no prior idle wait) will almost
always show every probe as warm — that's expected, not a bug; it's the same compute, still awake.
Options
| Flag | Default | What it does |
|---|---|---|
--url <conn-string> |
— | Also accepts a positional arg, or DATABASE_URL |
--repeat <n> |
1 |
Number of fresh-connection probes |
--every-seconds <s> |
0 |
Wait between probes |
--timeout <s> |
15 |
Per-probe connect timeout |
--cold-threshold-ms <ms> |
500 |
Total ms a probe is labelled COLD above |
--json |
off | Machine-readable output, including per-probe and summary (min/p50/p95/max) |
Where the 500ms default comes from
It is not a number Neon publishes — Neon documents that autoscaling computes suspend and
resume on demand but does not commit to a wake-up SLA. It's the midpoint of a real measurement
done building this tool's sibling project, a Postgres service with the same scale-to-zero
behavior: sleep the compute via its API, then measure the first request vs a warm one, 3 runs —
cold 0.93–1.47s, warm 0.09–0.24s. Pass your own --cold-threshold-ms once you have a few real
samples from your own project; it varies by region, plan and how large the compute is.
Honest limits
- This build has no real Neon test credentials (no Neon account token in this environment,
and the Neon MCP integration needs an interactive browser OAuth sign-in nobody here could
complete). Everything was tested for real against a local Postgres 16 container — proves
the connect/query/timing/retry/classification logic is correct, but a local container never
suspends, so it cannot reproduce an actual Neon cold start. Full transcript, including the
failure paths (wrong port, wrong password, missing arg):
test-fixtures/local-postgres-verification.md. - A single slow reading is not proof of a cold start. Network jitter, a loaded laptop, or a busy database can also push a connection over the threshold — the local-Postgres transcript above shows this happening for real (an 819ms and a 1664ms reading against a container that was never suspended, just competing with other load on the machine at the time). Take more than one sample, and compare the first probe after real idle time against the rest, not any one number in isolation.
- This is a generic Postgres latency probe, not Neon-specific code — it works against any Postgres connection string (including Scribase's). The Neon framing is because Neon's free-tier suspend behavior is the most-searched version of this pain; if you're on a different autoscaling Postgres, point it there instead.
- No
--watch/daemon mode yet — each run is a fixed number of probes, then it exits.
Need more?
If cold starts are a dealbreaker rather than a curiosity: Scribase is Postgres + auth + storage + email on one account. Its own Free/Hobby tier also scales to zero and pays the same kind of wake-up cost (measured: 0.93–1.47s cold vs 0.09–0.24s warm — the numbers this tool's default threshold is based on) — only the $25/mo Pro tier stays always-warm. No "no cold starts, ever" claim here for the free tier, because it wouldn't be true; the comparison page lays out both tiers' real numbers side by side.
License
MIT