Complete Guide to Setting Up Sushify Next.js with Supabase Database in 2025

Introduction

Setting up a reliable database is important for any SaaS application. In this guide, we'll walk you through integrating Sushify Next.js, a modern SaaS boilerplate, with Supabase, a PostgreSQL database platform. By the end of this tutorial, you'll have a functional database setup with type-safe queries and production-ready configuration.

Why Choose Sushify Next.js and Supabase?

Sushify Next.js Benefits

Sushify Next.js is a complete SaaS boilerplate built with modern technologies:

Next.js 15 with App Router and Server Components
Full-stack ready with database integration and type-safe queries
Type-safe end-to-end with TypeScript and Prisma
Production-optimized for performance, SEO, and security
Flexible architecture with monorepo structure and modular design

Prerequisites

Before getting started, ensure you have:

Node.js v20 or higher installed
pnpm package manager (v10.14.0 or compatible)
A Supabase account (sign up at supabase.com)
Basic knowledge of Next.js and React

Step 1: Install Sushify Next.js

First, clone the Sushify Next.js repository and install dependencies:

# Clone the repository (or use your forked version)
git clone https://github.com/Sushify-dev/Sushify-Next.js.git
cd Sushify-Next.js

# Install dependencies
pnpm install

Step 2: Create a Supabase Project

Go to supabase.com and sign in
Click New Project
Fill in your project details:
- Name: Choose a descriptive name (e.g., "my-saas-app")
- Database Password: Generate a strong password and save it securely
- Region: Select the region closest to your users
Click Create new project and wait for provisioning (1-2 minutes)

Step 3: Get Your Database Connection Strings

Once your Supabase project is ready:

Click the Connect button at the top of your project dashboard
In the connection dialog, select the ORMs tab
You'll see two connection strings:
- Connection pooling (for application queries)
- Direct connection (for migrations)

The connection strings will look similar to this format:

# Connection pooling (DATABASE_URL)
postgresql://postgres.[ref]:[password]@[region].pooler.supabase.com:6543/postgres?pgbouncer=true

# Direct connection (DIRECT_URL)
postgresql://postgres.[ref]:[password]@[region].pooler.supabase.com:5432/postgres

Copy these exact strings from your Supabase dashboard - they will contain your specific project reference, password, and region.

Step 4: Configure Environment Variables

Copy the example environment file:

cp .env.local.example .env.local

Open .env.local in your code editor and add your Supabase connection strings:

# Database Configuration
DATABASE_URL="postgresql://postgres.[PROJECT-REF]:[PASSWORD]@[HOST]:6543/postgres?pgbouncer=true"
DIRECT_URL="postgresql://postgres.[PROJECT-REF]:[PASSWORD]@[HOST]:5432/postgres"

Important Notes:

Replace [PROJECT-REF], [PASSWORD], and [HOST] with your actual Supabase credentials from Step 3
DATABASE_URL uses port 6543 with connection pooling (PgBouncer) for optimal performance
DIRECT_URL uses port 5432 for direct connections, required for Prisma migrations

Step 5: Initialize the Database Schema

Now that your database connection is configured, initialize your database schema using Prisma:

Push the Database Schema

This command syncs your Prisma schema with your Supabase database, creating all necessary tables and relationships:

pnpm --filter database push

You'll see output indicating tables being created:

🚀 Your database is now in sync with your Prisma schema.
✔ Generated Prisma Client

Verify in Supabase Dashboard

Go to your Supabase project dashboard
Navigate to Table Editor in the left sidebar
You should see all the tables created by Prisma, including:
- user - User accounts
- session - User sessions
- organization - Multi-tenant organizations
- member - Organization members
- And more...

Step 6: Generate Prisma Client

Generate the type-safe Prisma Client for database queries:

pnpm --filter database generate

This creates TypeScript types and methods based on your database schema, enabling type-safe database access throughout your application.

Step 7: Start Your Development Server

Launch the development server:

pnpm dev

Your application should now be running at http://localhost:3000!

Let's verify everything is working correctly by testing database queries.

Create a simple test file to verify Prisma is working:

import { db } from "@repo/database";

async function testDatabase() {
  const users = await db.user.findMany({
    take: 10,
  });

  console.log(`Found ${users.length} users`);
  console.log(users);
}

testDatabase();

Run it with:

npx tsx test-db.ts

Understanding the Database Architecture

Prisma ORM

Sushify Next.js uses Prisma as its ORM (Object-Relational Mapping) tool. The schema is located at packages/database/prisma/schema.prisma:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")
}

generator client {
  provider = "prisma-client-js"
}

model User {
  id    String @id @default(cuid())
  name  String
  email String @unique
  // ... other fields
}

Database Package Structure

packages/database/
├── prisma/
│   └── schema.prisma     # Database schema definition
├── src/
│   ├── index.ts          # Exported database client
│   └── queries/          # Pre-built query functions
├── package.json
└── README.md

Type Safety Benefits

With Prisma, you get:

Autocomplete for database queries
Type checking at compile time
Validation of query parameters
IntelliSense for all database models

Example:

import { db } from "@repo/database";

// TypeScript knows all fields and relationships
const user = await db.user.findUnique({
  where: { id: "user_id" },
  include: {
    organizations: true,
    accounts: true,
  },
});

// user.name is typed as string
// user.email is typed as string
// TypeScript will error on invalid fields

Modifying Your Database Schema

As your application grows, you'll need to modify your database schema:

1. Update Schema File

Edit packages/database/prisma/schema.prisma:

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  String
  author    User     @relation(fields: [authorId], references: [id])
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model User {
  id    String @id @default(cuid())
  name  String
  email String @unique
  posts Post[]  // Add this relation
}

2. Generate Prisma Client

pnpm --filter database generate

3. Apply Changes

For development:

pnpm --filter database push

For production (creates migration files):

pnpm --filter database migrate

Troubleshooting

Connection Timeout Errors

If you encounter connection timeouts:

Verify your Supabase project is active
Check that your IP isn't blocked (Supabase allows all IPs by default)
Ensure your connection strings are correct
Try using the direct connection URL temporarily

Migration Errors

If migrations fail:

Use DIRECT_URL for migrations, not DATABASE_URL
Check for syntax errors in your schema
Ensure no manual database changes conflict with schema
Reset database with pnpm --filter database push --force-reset (development only)

Prisma Client Not Generated

If TypeScript can't find Prisma types:

Run pnpm --filter database generate
Restart your TypeScript server in VS Code
Check that node_modules/.prisma exists

Advanced Features

Prisma Studio

Explore and edit your database visually:

pnpm --filter database studio

This opens a web interface at http://localhost:5555 where you can:

Browse all tables
Edit records
Run queries
Visualize relationships

Conclusion

Congratulations! You've successfully set up Sushify Next.js with Supabase. You now have:

A configured PostgreSQL database hosted on Supabase
Type-safe database access with Prisma ORM
Production-ready database architecture
Knowledge of best practices and troubleshooting

Next Steps

Customize Your Schema - Modify database models for your specific use case
Optimize Database Performance - Add indexes and optimize queries
Set Up Database Backups - Enable Point-in-Time Recovery
Monitor Database Usage - Use Supabase analytics to track performance
Deploy to Production - Apply your database setup to production environment

Additional Resources

Need Help?

If you encounter any issues or have questions:

Check the Sushify GitHub Issues
Consult the official documentation
Reach out to support

Happy building with Sushify Next.js and Supabase!