Database Setup Guide

Error You're Seeing

No database host or connection string was set

This means the DATABASE_URL environment variable is missing or not configured.

Quick Fix

Option 1: Use Neon (Recommended for Development)

1. Create a Neon account:

   • Go to https://console.neon.tech (opens in a new tab)
   • Sign up (free tier available)

2. Create a new project:

   • Click "New Project"
   • Choose PostgreSQL
   • Name it "optare-dev"
   • Click "Create Project"

3. Get your connection string:

   • Go to "Connection string"
   • Copy the full URL (looks like: postgresql://user:password@host/database)

4. Update .env file:

   DATABASE_URL=postgresql://user:password@host/database

5. Restart the dev server:

   # Stop current server (Ctrl+C)
   pnpm run dev

Option 2: Use Local PostgreSQL

1. Install PostgreSQL:

   • Windows: https://www.postgresql.org/download/windows/ (opens in a new tab)
   • Mac: brew install postgresql
   • Linux: sudo apt-get install postgresql

2. Start PostgreSQL:

   # Windows
   pg_ctl -D "C:\Program Files\PostgreSQL\15\data" start
    
   # Mac
   brew services start postgresql
    
   # Linux
   sudo service postgresql start

3. Create a database:

   createdb optare_dev

4. Update .env file:

   DATABASE_URL=postgresql://postgres:password@localhost:5432/optare_dev

5. Restart the dev server:

   pnpm run dev

Verify Connection

After setting DATABASE_URL, run:

pnpm run dev

You should see:

✓ Local: http://localhost:5173/

If you still see the database error, check:

1. Is DATABASE_URL set?

   echo $DATABASE_URL

2. Is the connection string correct?

   • Format: postgresql://user:password@host:port/database
   • No spaces or special characters

3. Is the database running?

   • For Neon: Check https://console.neon.tech (opens in a new tab)
   • For local: Run psql -U postgres to test

Environment Variables Needed

Required

• DATABASE_URL - PostgreSQL connection string

Recommended

• BETTER_AUTH_SECRET - Random 32+ character string
• BETTER_AUTH_URL - http://localhost:5173 for dev

Optional

• RESEND_API_KEY - For email (get from https://resend.com (opens in a new tab))
• REDIS_URL - For caching (default: redis://localhost:6379)

Generate JWT Keys (Optional)

If you need to generate JWT keys for OAuth token exchange:

node -e "const crypto = require('crypto'); const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', { modulusLength: 2048, publicKeyEncoding: { type: 'spki', format: 'pem' }, privateKeyEncoding: { type: 'pkcs8', format: 'pem' } }); console.log('Private Key:\n', privateKey); console.log('\nPublic Key:\n', publicKey);"

Copy the output to .env:

JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"

Troubleshooting

Error: "Connection refused"

• Database is not running
• Check if PostgreSQL service is started
• For Neon: Check internet connection

Error: "Authentication failed"

• Wrong password in connection string
• Check username and password
• For Neon: Copy the full connection string from console

Error: "Database does not exist"

• Database hasn't been created yet
• For local: Run createdb optare_dev
• For Neon: Create a new project

Error: "No such file or directory"

• .env file not found
• Create .env in project root
• Copy from .env.example

Next Steps

1. ✅ Set up database (Neon or local PostgreSQL)
2. ✅ Add DATABASE_URL to .env
3. ✅ Run pnpm run dev
4. ✅ Test login at http://localhost:5173/login (opens in a new tab)

Production Deployment

For production, use:

1. Neon (Recommended):

   • Serverless PostgreSQL
   • Auto-scaling
   • Free tier available
   • https://neon.tech (opens in a new tab)

2. AWS RDS:

   • Managed PostgreSQL
   • High availability
   • https://aws.amazon.com/rds/ (opens in a new tab)

3. DigitalOcean:

   • Managed databases
   • Simple setup
   • https://www.digitalocean.com/products/managed-databases/ (opens in a new tab)

Get the production connection string and add to your deployment environment variables.

Support

If you're still having issues:

1. Check .env file exists in project root
2. Verify DATABASE_URL is set correctly
3. Test database connection manually
4. Check database logs for errors
5. Restart the dev server

Let me know if you need help! 🚀