caelum0x 6d6af215a1 feat: neon-cold-start-probe — measure real serverless-Postgres wake-up latency
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>
2026-11-17 18:22:54 +03:00

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:

  1. 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).
  2. Run a --repeat probe 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

Description
Measure the real cold-start / wake-up latency of a Neon-style scale-to-zero Postgres endpoint from a fresh connection.
https://scribase.com/neon-compute-limit-cold-start?utm_source=rithub Readme 35 KiB
0.1.0 Latest
2026-11-17 15:23:05 +00:00
Languages
JavaScript 100%