Next.js + MotherDuck Postgres endpoint quickstart

Next.js + MotherDuck Postgres endpoint quickstart

An interactive NYC Taxi analytics dashboard built on Next.js App Router, querying MotherDuck over the Postgres endpoint with the standard pg driver.

The template queries MotherDuck's public sample_data.nyc.taxi share, so you get a working dashboard the moment you deploy.

Deploy

Or install the MotherDuck Native Integration from the Vercel Marketplace — it provisions a database and sets the required environment variables for you.

What's inside

• App Router home page (src/app/page.tsx) that server-renders the usable date bounds, then hands off to a client dashboard.
• src/app/api/dashboard/route.ts — fans out six parameterized aggregate queries in parallel (KPIs, trips-per-day, pickups-by-hour, revenue-by-payment-type, payment→rate Sankey, top pickup zones) for a given start/end range.
• src/app/api/bounds/route.ts — returns the min/max days with meaningful trip volume so the date picker stays on well-populated data.
• src/lib/motherduck.ts — a shared pg.Pool registered with attachDatabasePool from @vercel/functions, so connections survive and shut down cleanly across warm invocations on Fluid Compute.
• src/components/dashboard.tsx — client dashboard with KPI cards, Recharts line/bar/Sankey charts, click-to-drill day view, and a bounded date-range picker.
• shadcn/ui components (button, card, calendar, date-range-picker, popover, separator, skeleton), Tailwind CSS v4, Geist fonts, dark mode by default.

Prerequisites

• Node.js 20 or later
• A MotherDuck account — free tier works. Sign up at app.motherduck.com.

Getting started

1
# 1. Clone and install
2
git clone https://github.com/motherduckdb/nextjs-motherduck-pg-quickstart.git
3
cd nextjs-motherduck-pg-quickstart
4
npm install
5

6
# 2. Configure your MotherDuck token
7
cp .env.example .env.local
8
# then edit .env.local and paste your token from
9
# https://app.motherduck.com/settings/tokens
10

11
# 3. Run the dev server
12
npm run dev

Open http://localhost:3000 — the dashboard auto-loads the full date range from sample_data.nyc.taxi. Click any point on the trips-per-day line to drill into a single day.

How it works

The Postgres endpoint lets MotherDuck speak the Postgres wire protocol, so any Postgres client — including pg on a Vercel Function — can run full DuckDB SQL against it. This template wires up a pooled connection once and shares it across requests:

1
// src/lib/motherduck.ts
2
const pool = new Pool({
3
  connectionString: `postgresql://user:${token}@${host}:5432/${DATABASE}`,
4
  ssl: { rejectUnauthorized: true },
5
  max: 10,
6
  idleTimeoutMillis: 5000,
7
});
8

9
attachDatabasePool(pool); // graceful shutdown on Fluid Compute

Route handlers borrow a client from the pool, run parameterized queries in parallel with Promise.all, and return JSON. No ORMs, no code generation, no cold-start cost beyond the first Postgres handshake.

Environment variables

See .env.example for the full list with inline documentation.

The template is wired to MotherDuck's public sample_data share, so the database name is hard-coded in src/lib/motherduck.ts rather than surfaced as an env var. Change the DATABASE constant there if you repoint the template at your own database.

Learn more

• MotherDuck × Vercel integration guide
• Postgres endpoint docs
• Next.js App Router
• Vercel Fluid Compute

License

MIT