Supabase Setup

In this guide, we'll show you how to set up your application with Supabase as the database and storage provider.

Before we start, make sure you have a Supabase account. If you don't have one yet, you can create one for free at supabase.com.

1. Create a new Supabase project

1. Go to supabase.com and sign in
2. Click New Project
3. Fill in your project details:
   • Name: Your project name
   • Database Password: Choose a strong password (save this!)
   • Region: Choose a region close to your deployment (see note below)

2. Get connection strings

In the Supabase dashboard, click the Connect button in the top row.

Select the ORM tab and Prisma as the tool.

The shipped repository uses DATABASE_URL for both the application and Prisma CLI. If you want to keep a pooled runtime URL and a direct migration URL separate, copy both connection strings and apply the optional configuration in the next steps.

3. Set environment variables

Open your .env file and set the environment variables as follows:

# Connection pooling URL (for runtime - recommended for production)
DATABASE_URL="postgres://postgres.[your-supabase-project]:[password]@aws-0-[aws-region].pooler.supabase.com:6543/postgres?pgbouncer=true"

# Direct connection URL (for migrations and Prisma CLI)
DIRECT_URL="postgresql://postgres:[password]@db.[your-project-ref].supabase.co:5432/postgres"

4. Optionally separate the Prisma migration URL

The shipped prisma.config.ts reads DATABASE_URL. To use the pooled URL at runtime while sending Prisma CLI operations through a direct connection, add DIRECT_URL to .env and change the Prisma config as shown below.

Update your prisma/schema.prisma file or create a prisma.config.ts file:

import 'dotenv/config';

import { defineConfig, env } from 'prisma/config';

export default defineConfig({
  schema: './prisma/schema.prisma',
  datasource: {
    url: env('DIRECT_URL')
  }
});

At runtime, Prisma Client will use the pooled DATABASE_URL from your environment variables. This keeps the direct connection string scoped to Prisma CLI workflows (migrations and introspection) while your application connections continue to flow through Supavisor connection pooling.

5. Run migrations

To push the database schema to Supabase, run the following command:

npm run db:push

Or if you prefer to use migrations:

npm run db:migrate:dev

6. Connect Supabase storage for file uploads

To enable the shipped user avatar and organization logo uploads, you can use Supabase Storage through its S3-compatible endpoint.

Create a storage bucket

1. Go to the Storage tab in the Supabase dashboard
2. Click the Create bucket button
3. Name the bucket, for example avatars
4. Deactivate the Public bucket switch to prevent direct anonymous object access
5. Optionally, define a maximum file size and restrict file types for this bucket

Get storage credentials

1. Navigate to Project settings from the sidebar
2. Select the Storage tab
3. Scroll down to the S3 access keys section
4. Click the New access key button
5. Enter a description for your access key
6. After clicking Create access key, copy the Access key ID and Secret access key

Configure environment variables

Add the following environment variables to your .env file:

S3_ACCESS_KEY_ID="your-access-key"
S3_SECRET_ACCESS_KEY="your-secret-key"
S3_ENDPOINT="https://[YOUR-PROJECT-REF].storage.supabase.co/storage/v1/s3"
S3_REGION="[YOUR-PROJECT-REGION]"
NEXT_PUBLIC_IMAGES_BUCKET_NAME="avatars"

Copy the endpoint and region shown with the S3 access keys in the Supabase dashboard. The region participates in request signing, so do not substitute a region from another project.

7. Confirm storage configuration

No storage code change is required for the bucket name. The shipped configuration reads NEXT_PUBLIC_IMAGES_BUCKET_NAME:

import { env } from '@/lib/env';

export const storageConfig = {
  bucketNames: {
    images: env.NEXT_PUBLIC_IMAGES_BUCKET_NAME ?? ''
  }
} satisfies StorageConfig;

8. Run development server

Now you should be able to start the development server:

npm run dev

The Prisma client is automatically generated during migrations. If you need to generate it manually, you can run:

npm run db:generate

Troubleshooting

Connection issues

If you're experiencing connection issues:

1. Verify your connection string is correct
2. Check that your IP is allowed in Supabase (if IP restrictions are enabled)
3. Ensure you're using the correct region
4. Try using the direct connection URL instead of the pooled connection

Migration issues

If migrations fail:

1. If you opted into separate runtime and migration URLs, verify that migrations use DIRECT_URL
2. Check that your database password is correct
3. Verify that your project has the necessary permissions
4. If you kept the shipped single-URL setup, ensure prisma.config.ts and the application both use DATABASE_URL

Storage issues

If file uploads aren't working:

1. Verify your S3 credentials are correct
2. Check that the bucket exists and is accessible
3. Ensure the bucket name matches your configuration
4. Verify the endpoint URL is correct

That's all it takes to set up your application with Supabase! If you have questions or need help, refer to the Supabase documentation.