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 Drizzle as the tool.

You will need the DATABASE_URL. For Drizzle, you can use the connection pooling URL or the direct connection URL.

3. Set environment variables

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

For Connection Pooling (Recommended)

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

For Direct Connection

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

4. 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:generate
npm run db:migrate

5. 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.

6. 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;

7. Run development server

Now you should be able to start the development server:

npm run dev

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. Make sure you're using the direct connection URL for migrations
2. Check that your database password is correct
3. Verify that your project has the necessary permissions

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.