Set up NightOwl with free Vercel 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 Vercel Marketplace Postgres database under your control. Total monthly cost: from $5 for NightOwl Hobby, $0 for the database.

Why Vercel Postgres makes sense (and when it doesn't)

Two reasons to pick Vercel over going to Neon directly:

• One billing surface — if your Vercel bill is already a line item, this avoids a second vendor relationship.
• Familiar UI — the Vercel dashboard is what you already know; you don't context-switch to a Neon dashboard for occasional checks.

Three catches worth knowing up front:

• It's Neon, with the same free-tier limits. 0.5 GB storage, autosuspend after 5 minutes idle, small autoscaling compute. This is Neon's free tier, not NightOwl — slow dashboard loads after idle periods are wake-up cost. See the Neon guide for the deep version.
• The default DATABASE_URL is pooled (transaction mode). NightOwl's drain uses Postgres COPY which doesn't work under transaction-mode pooling. You must use DATABASE_URL_UNPOOLED instead.
• Vercel adds an abstraction layer. If Neon ships a feature, Vercel may take days or weeks to surface it. Power users hit this faster.

Step 1 — Provision Postgres from Vercel Marketplace

Open your Vercel dashboard at vercel.com/dashboard. Click Storage → Create Database. From the Marketplace, pick Neon Postgres (the Vercel-branded option labelled "Postgres" is also Neon — they're the same).

Pick a region close to your Laravel app's server. Same-region keeps drain latency under 10 ms. Click create — provisioning takes about a minute.

Step 2 — Copy the unpooled connection string

Once the database is provisioned, open it from the Storage tab. Click .env.local or Show secret. You'll see several environment variables:

• DATABASE_URL — pooled (transaction mode). Do not use this.
• DATABASE_URL_UNPOOLED — direct connection, session-level. Use this for NightOwl.
• POSTGRES_URL, POSTGRES_PRISMA_URL, etc. — Vercel-flavored aliases for the same pooled URL. Skip.

Copy DATABASE_URL_UNPOOLED as-is. The format is postgresql://[user]:[password]@ep-xxx.region.aws.neon.tech/[db]?sslmode=require.

Step 3 — Register the app in NightOwl

Sign in to the NightOwl dashboard. Click New application and name it. The form has five separate database fields — parse DATABASE_URL_UNPOOLED by hand into them:

• db_host — hostname (e.g. ep-xxx-xxx.region.aws.neon.tech, no -pooler suffix)
• db_port — 5432
• db_database — neondb (or whatever name appears in the URI's path)
• db_username — the user from the URI
• 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 same five DB connection values 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]
NIGHTOWL_DB_PASSWORD=[password]
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 your Vercel Postgres database.

Step 5 — Start the agent and verify telemetry

Run the agent:

php artisan nightowl:agent

Hit any route in your Laravel app. Within a few seconds it should appear in NightOwl's Requests tab. If Vercel Postgres was suspended (autosuspends after 5 minutes idle), the very first request takes a beat extra while compute wakes up — that's Neon's wake-up cost, not a NightOwl issue.

Step 6 — Tune retention for the 0.5 GB free tier

Drop retention to 2 days. In your Laravel .env:

NIGHTOWL_RETENTION_DAYS=2

Schedule the prune in routes/console.php:

use Illuminate\Support\Facades\Schedule;

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

nightowl:prune deletes rows older than the retention window across all 11 telemetry tables. It's a single retention value — no per-table tuning at the moment.

When to upgrade

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

• Cold starts on the dashboard frustrate you — Vercel Pro ($20/mo) or moving to Neon Launch directly ($19/mo) gets you always-on compute.
• Storage hits 80% of 0.5 GB even with 2-day retention — same upgrade path; 10 GB unlocked on the next tier.
• You want point-in-time recovery — paid Neon (and equivalently Vercel Pro Postgres) adds 7-day PITR.

If you're going to upgrade anyway, it's worth re-evaluating direct-Neon vs Vercel-Postgres pricing — the underlying compute is the same, so the only difference is which dashboard you bill from.

Compare: Vercel Postgres vs Neon vs Supabase vs Aiven

• Vercel Postgres — Neon-powered, lives inside Vercel. Best when you're already on Vercel.
• Neon — same backend, direct relationship. Better if you're not on Vercel.
• Supabase — always-on free compute (no cold starts), 500 MB. Better if cold starts annoy you.
• Aiven — multi-cloud managed Postgres, 1 GB free, always-on. Better for ops/DevOps audiences who pick the cloud region precisely.

composer require nightowl/agent
php artisan nightowl:install