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

Why Supabase free tier works for NightOwl

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

• Real PostgreSQL 15+ — not a Postgres-flavored layer. NightOwl uses native COPY, JSONB, partial indexes; Supabase supports all of it.
• 500 MB free database — enough for 4-7 days of telemetry at small-SaaS traffic with retention pruning.
• IPv4 + IPv6 pooler — works from any Laravel host, including older Forge/Hetzner boxes that don't speak IPv6.

Two catches worth knowing up front:

• Free tier compute is shared and slow. Supabase free projects run on a shared 2-core instance with throttled IOPS. Dashboard queries that take 100-200 ms on a dedicated database can take 1-3 seconds on the free tier — especially aggregations over the last 24 hours of requests. This is the database, not NightOwl. If pages feel slow once you have a few days of telemetry, that's the signal to upgrade Supabase, not to switch tools.
• Auto-pause after 7 idle days. Because NightOwl writes continuously, the database is never idle — auto-pause does not trigger as long as the agent is draining. The risk is only there if you stop the agent for a week.

Step 1 — Create a free Supabase project

Head to supabase.com, sign in (GitHub or email), and click New project. Pick the region closest to your Laravel app's server — same-region puts the agent and database on the same backbone, which keeps drain latency under 10 ms.

Set a strong database password and save it somewhere — Supabase doesn't show it again. Click Create new project. Provisioning takes about 2 minutes.

Step 2 — Copy the session pooler connection string

Once the project is ready, click Project Settings → Database. Scroll to Connection string. You'll see three tabs: Direct connection, Transaction pooler, Session pooler.

Use the Session pooler. NightOwl's drain uses PostgreSQL COPY for batch ingestion — that doesn't work under transaction-mode pooling, which holds connections only for the length of one transaction. Session pooling reuses connections across the whole drain pass, which is what COPY needs.

Paste your password into the placeholder if Supabase shows [YOUR-PASSWORD]. Keep this URI handy for the next step.

Step 3 — Register the app in NightOwl

Sign in to the NightOwl dashboard (or start a free trial if you haven't yet). Click New application and name it (e.g. "production-api"). The form has five separate database connection fields — parse the Supabase session-pooler URI by hand into them:

• db_host — the hostname (e.g. aws-0-eu-west-3.pooler.supabase.com)
• db_port — 5432 (session pooler)
• db_database — postgres (Supabase's default DB name)
• db_username — postgres.[project-ref]
• db_password — the password you set in Step 1

Click Test connection. NightOwl runs SELECT 1 against the database; on success the form unlocks. Save, and NightOwl issues an agent token. Copy this token — you'll add it to your Laravel .env next.

Step 4 — Install the NightOwl agent in your Laravel app

In your Laravel project root:

composer require nightowl/agent

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

NIGHTOWL_DB_HOST=aws-0-eu-west-3.pooler.supabase.com
NIGHTOWL_DB_PORT=5432
NIGHTOWL_DB_DATABASE=postgres
NIGHTOWL_DB_USERNAME=postgres.[project-ref]
NIGHTOWL_DB_PASSWORD=[your 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 the nightowl connection — creating all nightowl_* tables in your Supabase database. The migrations run from your Laravel app, not from the NightOwl dashboard.

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 — Supervisor, systemd, or your platform's worker config. Forge users can add it as a daemon; the docs page at docs.usenightowl.com has copy-paste configs.

Now hit any route in your Laravel app. Within a few seconds, you should see the request appear in the Requests tab of the NightOwl dashboard.

Step 6 — Tune retention for the 500 MB free tier

Out of the box, NightOwl retains 14 days of telemetry. On a 500 MB Supabase 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 so old rows get cleaned up automatically:

use Illuminate\Support\Facades\Schedule;

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

Or run it manually whenever you want to free space: php artisan nightowl:prune.

nightowl:prune deletes rows older than NIGHTOWL_RETENTION_DAYS across all 11 telemetry tables (requests, queries, exceptions, jobs, scheduled tasks, mail, notifications, cache events, outgoing requests, commands, logs). It's a single retention value — there's no per-table tuning at the moment.

When to upgrade to Supabase Pro

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

• Dashboard pages take more than ~2 seconds to load — shared compute is the bottleneck, not NightOwl. Pro gives you a dedicated 2-core instance and unthrottled IOPS, which usually drops query times by 5-10×.
• Database hits 80% of 500 MB even with 2-day retention — you're past low-volume territory; Pro at $25/mo gives you 8 GB and real backups.
• You need 30+ day retention for incident post-mortems — at typical SaaS traffic, that's well past 500 MB.
• You want point-in-time recovery — free tier has none. Pro adds 7-day PITR.

Total stack at that point: $15 NightOwl Team + $25 Supabase Pro = $40/month, all-in, with 8 GB of telemetry retention and no per-event metering. Compare that to Sentry or Datadog at equivalent volume.

composer require nightowl/agent
php artisan nightowl:install