caelum0x 5c1758578f fix: clean output for sslmode=require, real arg validation, --version, closing CTA line
- normalize sslmode=require/prefer/verify-ca to verify-full so pg's 8-line
  SECURITY WARNING no longer precedes every Neon probe
- --repeat/--timeout/--every-seconds/--cold-threshold-ms are validated; a bad
  or missing value used to exit 1 silently
- reject non-postgres:// arguments and unknown flags with a clear message
- pay one-time DNS/TLS process costs before probe 1
- output ends with one plain line pointing at the Neon cold-start page
- README: 10-second quickstart, real output sample, copy matches the page

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-17 20:01:34 +03:00

neon-cold-start-probe

Measure how long your Neon (or any scale-to-zero Postgres) database really takes to answer the first connection after it has been idle. One command, no account, no config.

10-second quickstart

npx --yes git+https://rithub.dev/caelum0x/neon-cold-start-probe.git "$DATABASE_URL" --repeat 5

That is the whole setup. It needs Node 18+ and a Postgres connection string.

What you get

Real output from this exact build (Postgres 16 over TLS, sslmode=require, 2026-11-17):

probe 1/5: connect=202ms query=10ms total=212ms [warm]
probe 2/5: connect=55ms query=10ms total=64ms [warm]
probe 3/5: connect=39ms query=1ms total=41ms [warm]
probe 4/5: connect=299ms query=15ms total=314ms [warm]
probe 5/5: connect=36ms query=3ms total=39ms [warm]

summary: min=39ms p50=64ms p95=314ms max=314ms (0/5 probes >= 500ms, 0 failed)

Neon cold starts and compute limits explained, with the fix: https://scribase.com/neon-compute-limit-cold-start?utm_source=cli&utm_medium=cli-output&utm_campaign=neon-cold-start-probe

Every probe opens a brand-new connection (never pooled, because a pool hides exactly the thing you are trying to see) and times three parts: connect, query, total. A probe at or above the threshold (500ms by default) is labelled COLD.

That sample is a database that never suspends, on a busy laptop, so every probe is warm and the spread is machine noise. It is here to show the format, not a Neon number.

How to catch a real cold start

  1. Leave the database idle past its suspend timeout. On Neon Free that is 5 minutes and cannot be changed.
  2. Run the quickstart command once. Probe 1 is the one that had to wake the compute. Probes 2 to 5 run against a compute that is already awake.

The gap between probe 1 and the rest is your cold start, measured from your machine and your region. Run it back to back with no idle wait and every probe is warm. That is expected.

Options

Flag Default What it does
--url <conn-string> none 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 at or above which a probe is labelled COLD
--json off Per-probe results plus summary (min/p50/p95/max) on stdout
--version Print the version

Run it from a clone instead:

git clone https://rithub.dev/caelum0x/neon-cold-start-probe.git
cd neon-cold-start-probe && npm install
node bin/neon-cold-start-probe.mjs "$DATABASE_URL" --repeat 5

Honest limits

  • Not yet run against a live Neon project. Everything here was tested for real against a local Postgres 16 (plain and TLS), which proves the connect, timing, retry and labelling logic but can never suspend. The full transcript, failure paths included, is in test-fixtures/local-postgres-verification.md.
  • One slow reading is not proof of a cold start. Network jitter or a loaded machine can push a warm connection over the threshold. Compare the first probe after real idle time against the rest, and take more than one sample.
  • The 500ms default is not a Neon number. Neon documents that a suspended compute wakes in a few hundred milliseconds and publishes no SLA. 500ms is a starting point; set --cold-threshold-ms once you have samples of your own.
  • It is a generic Postgres probe. It works against any connection string, Scribase's included.
  • One-time process costs (first DNS lookup, loading Node's TLS stack) are paid before probe 1, so they are not counted as database wake-up time.

If the cold start is the problem

Neon cold starts and compute limits explained, with the fix: why the first query is slow, how the Free compute allowance is counted, and what to change.

This tool is built by Scribase: Postgres, sign-in, storage and email on one account instead of four. Scribase also scales idle environments to zero, so point this probe at it too and compare the numbers yourself.

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 MIT 50 KiB
v0.1.1 Latest
2026-11-17 17:01:34 +00:00
Languages
JavaScript 100%