Set up NightOwl with a free Neon Postgres

What you'll have at the end

A working NightOwl dashboard showing live telemetry from your Laravel app — requests, queries, jobs, exceptions, scheduled tasks — with all data stored in a free Neon serverless Postgres under your control. Total monthly cost: from $5 for NightOwl Hobby, $0 for the database.

Why Neon free tier works for NightOwl

Three properties make Neon a clean fit for NightOwl's BYOD Postgres model:

• Real Postgres 16, fully libpq-compatible — NightOwl uses native COPY, JSONB, and partial indexes; Neon supports all of it without a translation layer.
• 0.5 GB free storage — enough for 4-7 days of telemetry at small-app traffic with retention pruning.
• Branching — useful when you want to test a NightOwl schema migration without touching production data.

Three catches worth knowing up front:

• Cold starts on free-tier compute. Neon's free compute autosuspends after ~5 minutes of idle. The next query waits 500 ms to 2 s while compute wakes up. While your Laravel app is taking traffic, the agent's continuous drain keeps Neon warm — but the first dashboard load after an idle night can feel slow. This is Neon's free tier, not NightOwl.
• Small free compute (0.25 vCPU autoscaling). Aggregation queries over multiple days of telemetry can take 1-3 seconds where a dedicated 2-core would take 100-200 ms. Same caveat — this is Neon, not NightOwl. Verify in Neon's own SQL editor; the same queries will be just as slow.
• 0.5 GB hard cap. Heavy traffic blows through this in days. Tune retention aggressively or upgrade to the Launch tier.

Step 1 — Create a free Neon project

Head to neon.tech, sign in, and click New project. Pick a region close to your Laravel app's server — same-region keeps the agent's drain latency under 10 ms.

Neon creates a default database called neondb with a randomly generated user and password. You can rename, but for NightOwl telemetry the defaults are fine.

Step 2 — Copy the direct connection string

On the project dashboard, find the Connection Details panel. Neon offers two connection types: Pooled (hostname has a -pooler suffix, transaction-mode pooled) and Direct (regular hostname, session-level).

Use the direct connection. NightOwl's drain uses Postgres COPY for batch ingestion — that doesn't work under transaction-mode pooling. The direct connection gives session-level semantics, which is what COPY needs.

Note the sslmode=require at the end — Neon enforces TLS on every connection. Don't strip it.

Step 3 — Register the app in NightOwl

Sign in to the NightOwl dashboard (or start a free trial). Click New application and name it (e.g. "production-api"). The form has five separate database connection fields — parse the Neon direct URI by hand into them:

• db_host — the hostname (e.g. ep-xxx-xxx.region.aws.neon.tech, no -pooler suffix)
• db_port — 5432
• db_database — neondb (Neon's default DB name)
• db_username — the user from the URI (Neon generates a random one)
• db_password — the password embedded in the URI

Click Test connection. NightOwl runs SELECT 1; on success the form unlocks. Save, and NightOwl issues an agent token. Copy it.

Step 4 — Install the NightOwl agent

In your Laravel project root:

composer require nightowl/agent

Add the database connection details (same values you entered in Step 3) plus the agent token to your Laravel .env:

NIGHTOWL_DB_HOST=ep-xxx-xxx.region.aws.neon.tech
NIGHTOWL_DB_PORT=5432
NIGHTOWL_DB_DATABASE=neondb
NIGHTOWL_DB_USERNAME=[user from URI]
NIGHTOWL_DB_PASSWORD=[password from URI]
NIGHTOWL_TOKEN=[agent token from Step 3]
NIGHTOWL_APP_ID=[app id from Step 3]

Then run the installer:

php artisan nightowl:install

nightowl:install publishes config/nightowl.php and runs the schema migrations against the nightowl connection — creating all nightowl_* tables in your Neon database.

Step 5 — Start the agent and verify telemetry

Run the agent process. In dev:

php artisan nightowl:agent

In production, supervise it the same way you supervise queue workers. docs.usenightowl.com has copy-paste Supervisor and systemd configs.

Now hit any route in your Laravel app. Within a few seconds, the request should appear in the Requests tab of the NightOwl dashboard. If Neon was suspended, the very first request will take a beat extra while compute wakes — that's the cold-start cost, not a NightOwl issue.

Step 6 — Tune retention for the 0.5 GB free tier

Out of the box, NightOwl retains 14 days of telemetry. On a 0.5 GB Neon free tier, drop that to 2 days. Add this to your Laravel .env:

NIGHTOWL_RETENTION_DAYS=2

Then schedule the prune command in routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('nightowl:prune')->daily();

Or run manually: php artisan nightowl:prune. This deletes rows older than NIGHTOWL_RETENTION_DAYS across all 11 telemetry tables. Single retention value — no per-table tuning at the moment.

When to upgrade to Neon Launch

Four signals it's time to leave the free tier:

• Cold starts on the dashboard frustrate you — Launch ($19/mo) gives you always-on compute. No autosuspend, no wake-up wait.
• Dashboard pages take more than ~2 seconds to load even when warm — Launch unlocks bigger autoscaling, which usually drops query times by 5-10×.
• Storage hits 80% of 0.5 GB even with 2-day retention — Launch gives you 10 GB and longer retention.
• You need 30+ day retention for incident post-mortems — at typical SaaS traffic, that's well past 0.5 GB.

Total stack at that point: $15 NightOwl Team + $19 Neon Launch = $34/month, all-in. Compare that to Sentry or Datadog at equivalent volume.

Neon vs Supabase for NightOwl

Both work. Pick based on your usage shape:

• Neon if you want serverless billing, branching, and don't mind cold starts on idle. Better for lower-traffic apps where the database stays warm only during active hours.
• Supabase if you want always-on compute on free tier (no cold starts), broader ecosystem, and don't need branching. Slightly more storage on free (500 MB ≈ 0.5 GB, comparable).

composer require nightowl/agent
php artisan nightowl:install