Setup & Configuration

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

# 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"

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

npx prisma db pull

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:

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

• 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