Plainform

Plainform connects to Supabase's PostgreSQL database using two environment variables: DATABASE_URL (for connection pooling) and DIRECT_URL (for migrations). These variables are validated by @t3-oss/env-nextjs to ensure your app won't start without proper database configuration.

Getting Your Connection Strings

Create a Supabase Project

Go to Supabase Dashboard
Click "New Project"
Choose your organization and region
Set a strong database password (save this - you'll need it)
Wait for the project to finish provisioning

Get Connection Strings

In your Supabase project, go to Settings → Database
Scroll to the Connection String section
You'll see two connection modes:

Connection Pooling (Transaction Mode):

Used for: Regular database queries via Prisma Client
Copy the connection string (it includes ?pgbouncer=true)
This will be your DATABASE_URL

Direct Connection (Session Mode):

Used for: Database migrations via Prisma Migrate
Copy the connection string (without ?pgbouncer=true)
This will be your DIRECT_URL

Add to Environment Variables

Add both connection strings to your .env file:

.env

# Supabase PostgreSQL Connection
DATABASE_URL="postgresql://postgres.xxxxx:[YOUR-PASSWORD]@aws-0-us-west-1.pooler.supabase.com:6543/postgres?pgbouncer=true"
DIRECT_URL="postgresql://postgres.xxxxx:[YOUR-PASSWORD]@aws-0-us-west-1.pooler.supabase.com:5432/postgres"

Replace [YOUR-PASSWORD] with the database password you set when creating the project.

Verify Configuration

The @t3-oss/env-nextjs schema in env.ts validates these variables:

env.ts

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().min(5),
    DIRECT_URL: z.string().min(5),
    // ... other variables
  },
  // ...
});

If either variable is missing or invalid, your app won't start and you'll see a validation error.

Test the Connection

Run Prisma's introspection to verify the connection works:

Terminal

npx prisma db pull

If successful, you'll see your database schema. If it fails, double-check your connection strings and password.

Connection String Breakdown

Understanding the two connection strings:

DATABASE_URL (Pooled Connection)

postgresql://postgres.xxxxx:[PASSWORD]@aws-0-us-west-1.pooler.supabase.com:6543/postgres?pgbouncer=true

Port: 6543 (PgBouncer pooler)
Parameter: ?pgbouncer=true
Used by: Prisma Client for queries
Why: Connection pooling prevents exhausting database connections in serverless environments

DIRECT_URL (Direct Connection)

postgresql://postgres.xxxxx:[PASSWORD]@aws-0-us-west-1.pooler.supabase.com:5432/postgres

Port: 5432 (standard PostgreSQL)
No pooling parameter
Used by: Prisma Migrate for schema changes
Why: Migrations require direct database access (poolers don't support all migration operations)

Prisma Configuration

Your prisma/schema.prisma uses both URLs:

prisma/schema.prisma

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")      // Pooled connection
  directUrl = env("DIRECT_URL")        // Direct connection
}

Prisma automatically uses:

DATABASE_URL for queries (prisma.user.findMany())
DIRECT_URL for migrations (npx prisma migrate dev)

Security Best Practices

Never commit your .env file to version control. It's already in .gitignore.

Use strong passwords: Generate a random 32+ character password for your database
Rotate credentials: If credentials are exposed, reset your database password in Supabase dashboard
Environment-specific: Use different databases for development, staging, and production
Team access: Share connection strings securely (1Password, encrypted channels)

Troubleshooting

Common issues and solutions:

"Invalid connection string"

Verify you copied the entire string including postgresql://
Check for extra spaces or line breaks
Ensure password is URL-encoded (replace special characters)

"Connection timeout"

Check your internet connection
Verify Supabase project is active (not paused)
Confirm you're using the correct region endpoint

"Too many connections"

Use DATABASE_URL (pooled) for queries, not DIRECT_URL
Check if you have connection leaks in your code
Consider upgrading your Supabase plan for more connections

For more troubleshooting, see the Supabase Troubleshooting page.

Next Steps

Database Setup - Learn about Prisma schema and models
Migrations - Create and apply database migrations
Supabase Documentation - Explore Supabase database features

Setup & Configuration