PageBridge

Database Setup

PageBridge stores search analytics data in PostgreSQL using Drizzle ORM. Here is how to configure your database.

Local development with Docker

The quickest way to get started is with Docker:

docker run -d --name pagebridge-db \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=pagebridge \
  -p 5432:5432 \
  postgres:16
bash

Or use the included Docker Compose file if working from the monorepo:

docker compose up -d
bash

Set your connection string:

DATABASE_URL='postgresql://postgres:postgres@localhost:5432/pagebridge'
bash

Hosted database providers

For production, use a hosted PostgreSQL provider:

  • Neon — Serverless Postgres with branching. Free tier available.
  • Supabase — Hosted Postgres with a generous free tier.
  • Railway — Simple cloud Postgres provisioning.
  • Vercel Postgres — Integrated with Vercel deployments.

Use the connection string from your provider:

DATABASE_URL='postgresql://user:password@host:5432/dbname?sslmode=require'
bash

Pushing the schema

PageBridge uses Drizzle ORM for schema management. Push the schema to create the required tables:

# From the monorepo root
pnpm db:push

# Or directly with drizzle-kit
pnpm drizzle-kit push
bash

Database tables

PageBridge creates the following tables:

TablePurpose
searchAnalyticsPage-level search metrics (clicks, impressions, CTR, position) per day
queryAnalyticsQuery-level search metrics per page per day
syncLogHistory of sync executions with status and row counts
pageIndexStatusCached Google index inspection results (24h TTL)
unmatchDiagnosticsDiagnostic data for URLs that could not be matched to Sanity documents

Exploring with Drizzle Studio

You can browse your data with the built-in Drizzle Studio UI:

pnpm db:studio
bash

This opens a web interface at https://local.drizzle.studio where you can view and query all tables.

Running migrations

If you need migration files (for example, in a CI pipeline), generate and run them with:

# Generate migration files
pnpm db:generate

# Run pending migrations
pnpm db:migrate

# Or run migrations automatically before a sync
pagebridge sync --site sc-domain:example.com --migrate
bash

The --migrate flag on the sync and diagnose commands will automatically run any pending migrations before executing the command.

Next steps