🚀StarShip Developer Kit

Database Management

Overview

The Next.js 15 StarShip Developer Kit implements a developer-centric database architecture designed for both productivity and seamless deployment:

  • Local Docker PostgreSQL for fast, isolated development
  • Supabase development database for backup and synchronization
  • Separate Supabase production database for clean deployment
  • Drizzle ORM for type-safe database operations
  • Automatic migrations and data synchronization

💡 Developer Experience First

Our unique multi-environment approach prioritizes developer experience without compromising production stability. This architecture can be implemented entirely using Supabase's free tier, making it accessible for projects of all sizes.

Multi-Environment Database Architecture

1. Local Docker PostgreSQL

Your primary development database:

  • Zero latency - runs directly on your machine
  • Complete control over schema and data
  • No internet connection required
  • Spin up fresh instances in seconds with Docker
  • Perfect for rapid iteration and testing
docker compose up -d - Starts your development database instantly

2. Supabase Development Database

Your backup and synchronization layer:

  • Automatic backup of local development work
  • Share database state with team members
  • Test against a cloud environment
  • Restore development state after machine changes
  • Free tier provides ample storage for development needs
pnpm db:sync - Synchronizes your local database to Supabase

3. Supabase Production Database

Your stable production environment:

  • Completely isolated from development data
  • Clean, controlled migrations from development
  • Automatic backups and point-in-time recovery
  • Scales with your application needs
  • Free tier suitable for MVPs and small applications
pnpm db:migrate:prod - Safely applies migrations to production

Why This Architecture Excels

✅ Perfect for Solo Developers and Teams

Local development databases give you lightning-fast iteration without internet dependency, while Supabase integration ensures your work is backed up and shareable. Teams can synchronize their local environments when needed.

✅ Zero-Cost Production Ready

Supabase's free tier provides all you need to run both development and production databases. As your application grows, you can easily upgrade only the production instance, keeping development costs minimal.

✅ Type-Safe with Drizzle ORM

Drizzle ORM provides complete type safety across your database operations. Schema changes generate TypeScript types automatically, catching errors at compile time rather than runtime.

✅ Dev/Prod Parity Without Complexity

Using PostgreSQL throughout all environments ensures complete compatibility. No surprises when deploying to production, as you're using the same database technology everywhere.

Environment Configuration

Configure your multi-environment database setup through environment variables:

# Local Development Database (Docker)
DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
DB_USER="nextstarter"
DB_PASSWORD=""
DB_NAME="nextstarter"
DB_PORT="5432"

# Supabase Development Environment
DEVELOPMENT_DATABASE_URL="postgresql://postgres.supabase:password@aws-region.pooler.supabase.com:6543/postgres"
NEXT_PUBLIC_SUPABASE_URL="https://your-dev-project.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="your-dev-anon-key"
SUPABASE_SERVICE_ROLE_KEY="your-dev-service-role-key"

# Supabase Production Environment
PRODUCTION_DATABASE_URL="postgresql://postgres.supabase:password@aws-region.pooler.supabase.com:6543/postgres"
# Production Supabase keys are set in your deployment platform

This three-tier setup allows you to:

  • Develop locally with maximum speed and flexibility
  • Back up your work and share with team members via development Supabase
  • Deploy confidently to a clean, isolated production environment
  • Implement the entire architecture using Supabase's free tier

Database Commands

The developer kit includes several npm scripts for managing your multi-environment database setup:

# Local Development Commands
pnpm db:generate         # Generate migrations from schema changes
pnpm db:push            # Apply migrations to local database
pnpm db:reset           # Reset local database to clean state
pnpm db:seed            # Populate local database with initial data
pnpm db:studio          # Open Drizzle Studio UI for local database

# Multi-Environment Commands
pnpm db:studio:local    # Open Drizzle Studio for your Docker database (reliable connection)
pnpm db:sync            # Synchronize local database to Supabase development
pnpm db:migrate:prod    # Apply migrations to production database (careful!)

# Docker Management
docker compose up -d    # Start the Docker PostgreSQL container
docker compose down     # Stop the Docker PostgreSQL container

🔥 Pro Tip

For the most reliable database access during development, use pnpm db:studio:local which ensures your Drizzle Studio connects to your Docker database regardless of your current environment settings.