How to Self-Host Dub Link Shortener on Vercel with PlanetScale Database (2025 Complete Guide)

Dub is a modern, open-source link attribution platform that powers over 100M+ clicks monthly for companies like Twilio, Buffer, and Framer. While Dub offers a hosted solution, many developers need to self-host for data sovereignty, custom branding, or compliance requirements. This guide walks through deploying Dub on Vercel with PlanetScale as your database backend.

Why Self-Host Dub on Vercel and PlanetScale?

Before diving into the setup, understanding this specific stack combination helps:

• Vercel: Native Next.js deployment platform (Dub is built with Next.js)
• PlanetScale: Serverless MySQL with automatic branching, perfect for Prisma ORM
• Cost efficiency: Both platforms offer generous free tiers for development
• Zero downtime migrations: PlanetScale's branch-based workflow prevents schema migration issues

Dub's tech stack is specifically optimized for this deployment pattern, using Prisma as the ORM layer between your application and PlanetScale.

Prerequisites and Version Requirements

Before starting, ensure you have:

# Verify Node.js version
node --version  # Should output v23.11.0 or compatible

# Verify pnpm version
pnpm --version  # Should output 9.15.9 or compatible

Required accounts:

• GitHub account (for repository access)
• Vercel account (free tier sufficient)
• PlanetScale account (free tier sufficient)
• Upstash account (for Redis caching)
• Tinybird account (for analytics pipeline)

Step 1: Fork and Clone the Dub Repository

First, fork the official Dub repository to your GitHub account:

# Clone your forked repository
git clone https://github.com/YOUR_USERNAME/dub.git
cd dub

# Install dependencies with exact pnpm version
pnpm install

Dub uses a Turborepo monorepo structure. The main application lives in apps/web, while shared packages are in packages/.

Step 2: Set Up PlanetScale Database

Create Your Database

1. Log into PlanetScale dashboard
2. Click "Create database" and name it dub-production
3. Select your preferred region (choose closest to your Vercel deployment region)
4. Keep the default cluster size for development

Generate Connection Strings

PlanetScale uses two connection patterns:

# Main branch connection (for production)
mysql://username:password@host/dub-production?sslaccept=strict

# Development branch connection (for migrations)
mysql://username:password@host/dub-production?sslaccept=strict

Important: Copy both connection strings. You'll need the format with ?sslaccept=strict for Prisma.

Configure Database for Prisma

PlanetScale requires specific Prisma settings. Create a .env file in the project root:

# Database
DATABASE_URL="mysql://username:password@host/dub-production?sslaccept=strict"

# Prisma configuration for PlanetScale
DATABASE_PRISMA_URL="mysql://username:password@host/dub-production?sslaccept=strict&connect_timeout=30"

Step 3: Push Prisma Schema to PlanetScale

Dub uses Prisma for database migrations. Since PlanetScale doesn't use traditional migration files, you'll push the schema directly:

# Navigate to web app directory
cd apps/web

# Push Prisma schema to PlanetScale
pnpm prisma:push

Common error: If you see The table <table-name> does not exist in the current database, this command resolves it by syncing your schema.

Verify Schema Deployment

Check PlanetScale dashboard:

1. Navigate to your database
2. Click "Console" tab
3. Run: SHOW TABLES;

You should see tables like User, Link, Project, Domain, etc.

Step 4: Configure Required Services

Set Up Upstash Redis

Dub requires Redis for rate limiting and caching:

1. Create database at Upstash Console
2. Copy REST URL and token
3. Add to .env:

UPSTASH_REDIS_REST_URL="https://your-db.upstash.io"
UPSTASH_REDIS_REST_TOKEN="your-token-here"

Configure Tinybird Analytics

Tinybird powers Dub's real-time analytics:

1. Create workspace at Tinybird
2. Generate API token with write permissions
3. Add to .env:

TINYBIRD_API_KEY="your-tinybird-api-key"
TINYBIRD_DATASOURCE="dub_click_events"

NextAuth Configuration

Set up authentication secrets:

# Generate random secret
openssl rand -base64 32

# Add to .env
NEXTAUTH_SECRET="your-generated-secret"
NEXTAUTH_URL="https://your-domain.vercel.app"

Step 5: Deploy to Vercel

Connect Repository to Vercel

1. Log into Vercel Dashboard
2. Click "Add New" → "Project"
3. Import your forked Dub repository
4. Vercel auto-detects Next.js and Turborepo

Configure Build Settings

| Setting | Value | |---------|-------| | Framework Preset | Next.js | | Root Directory | apps/web | | Build Command | pnpm build | | Output Directory | .next | | Install Command | pnpm install | | Node Version | 23.x |

Add Environment Variables

In Vercel project settings → Environment Variables, add all variables from your .env:

DATABASE_URL
DATABASE_PRISMA_URL
UPSTASH_REDIS_REST_URL
UPSTASH_REDIS_REST_TOKEN
TINYBIRD_API_KEY
NEXTAUTH_SECRET
NEXTAUTH_URL

Pro tip: Use Vercel's environment variable groups to manage staging and production separately.

Deploy

Click "Deploy" and Vercel will:

1. Install dependencies with pnpm
2. Build the Next.js application
3. Deploy to edge network
4. Provide production URL

Step 6: Seed Development Data (Optional)

For testing your self-hosted instance, seed sample data:

# From your local environment
cd apps/web

# Seed without truncating existing data
pnpm run script dev/seed

# Or truncate first for clean slate
pnpm run script dev/seed --truncate

This creates test projects, links, and users in your PlanetScale database.

Troubleshooting Common Deployment Issues

Build Fails on Vercel

Issue: The project is not building correctly

Solution:

# Locally, clean all build artifacts
find . -name "node_modules" -type d -exec rm -rf {} +
find . -name ".next" -type d -exec rm -rf {} +
find . -name ".turbo" -type d -exec rm -rf {} +

# Reinstall and rebuild
pnpm install
pnpm build

Verify Node (v23.11.0) and pnpm (9.15.9) versions match recommendations.

Prisma Connection Errors

Issue: Can't reach database server at host:port

Solution: Verify PlanetScale connection string includes:

• Correct username/password
• ?sslaccept=strict query parameter
• Connection timeout parameter for Vercel's serverless functions

Missing Tables Error

Issue: The table User does not exist in the current database

Solution: Run pnpm prisma:push from apps/web directory to sync schema.

Performance Optimization for Self-Hosted Dub

Enable PlanetScale Read Replicas

For production workloads:

1. Upgrade to PlanetScale Scaler plan
2. Create read replica in same region as Vercel deployment
3. Update Prisma connection for read queries:

// Use read replica for analytics queries
const DATABASE_READ_URL = process.env.DATABASE_READ_URL

Configure Vercel Edge Caching

Optimize link redirects with edge caching:

// In your redirect route
export const config = {
  runtime: 'edge',
}

export default async function handler(req: Request) {
  // Dub handles caching internally via Upstash
}

Cost Comparison: Self-Hosted vs Managed

| Component | Self-Hosted (Free Tier) | Dub Managed | |-----------|------------------------|-------------| | Hosting | Vercel: $0/month | Included | | Database | PlanetScale: $0/month (5GB) | Included | | Redis | Upstash: $0/month (10K commands/day) | Included | | Analytics | Tinybird: $0/month (10GB/month) | Included | | Total | $0/month (until scale) | $24/month (Pro plan) |

Self-hosting becomes cost-effective when you need:

• Custom domain whitelabeling
• Data residency in specific regions
• Integration with existing infrastructure
• Development/staging environments

Next Steps

After successful deployment:

1. Configure custom domain: Add your domain in Vercel settings
2. Set up SAML SSO: Use BoxyHQ for enterprise authentication
3. Enable Stripe: Add payment processing for affiliate programs
4. Monitor analytics: Configure Tinybird dashboards for link performance

Maintaining Your Self-Hosted Instance

Keep your Dub instance updated:

# Add upstream remote
git remote add upstream https://github.com/dubinc/dub.git

# Fetch and merge updates
git fetch upstream
git merge upstream/main

# Push to your fork (triggers Vercel deployment)
git push origin main

Dub releases updates regularly. Monitor the GitHub releases for new features and security patches.

Conclusion

Self-hosting Dub on Vercel with PlanetScale provides a production-ready link attribution platform with minimal infrastructure overhead. This stack leverages serverless architecture for automatic scaling while maintaining the flexibility of open-source software.

The combination of Vercel's edge network, PlanetScale's serverless MySQL, and Dub's Next.js architecture creates a highly performant link shortener that can handle millions of clicks monthly—the same stack powering Dub's managed service used by companies like Twilio and Perplexity.

For advanced configurations, explore Dub's self-hosting documentation and join their community for support with your specific deployment needs.