Skip to main content
Biovity uses PostgreSQL as its database. Follow these steps to set up your local database and run migrations.

​
Prerequisites

Before setting up the database, ensure you have:
  • PostgreSQL installed locally or access to a hosted instance (e.g., Supabase)
  • Database credentials configured in .env.local

​
Install PostgreSQL locally

If you don’t have PostgreSQL installed:
1

Download PostgreSQL

Download and install PostgreSQL from postgresql.orgOr use a package manager:
brew install postgresql@16
brew services start postgresql@16
2

Create a database

Create a new database for Biovity:
# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE biovity;

# Exit psql
\q
3

Update connection string

Update your .env.local with the local database credentials:
.env.local
DATABASE_URL="postgresql://postgres:password@localhost:5432/biovity"
For a managed PostgreSQL instance, you can use Supabase:
1

Create a Supabase project

  1. Go to supabase.com
  2. Create a new project
  3. Wait for the database to be provisioned
2

Get connection string

  1. Navigate to Settings > Database
  2. Copy the Connection string under “Connection pooling”
  3. Replace [YOUR-PASSWORD] with your database password
3

Update environment variable

Add the connection string to your .env.local:
.env.local
DATABASE_URL="postgresql://postgres.xxxxx:password@aws-0-us-west-1.pooler.supabase.com:5432/postgres"

​
Run database migrations

Biovity’s database migrations are located in lib/db/migrations/. The migration system is managed through Better Auth’s schema setup.
To initialize the database schema:
1

Verify database connection

Test your database connection by checking if the connection string is valid:
# Using psql
psql "$DATABASE_URL" -c "SELECT version();"
If the connection is successful, you’ll see the PostgreSQL version.
2

Run migrations

Better Auth automatically creates required tables on first run. Start the development server to initialize the schema:
bun dev
The authentication tables will be created automatically, including:
  • user - User accounts
  • session - Active sessions
  • account - OAuth accounts
  • Custom fields: type, profession, avatar, isActive, organizationId

​
Database architecture

Biovity uses a connection pooling strategy for PostgreSQL:
  • Connection pool - Shared connection pool in lib/db/index.ts
  • Connection limits - Configured for optimal performance
  • Idle timeout - Prevents stale connections
For production best practices, refer to the docs/POSTGRES-BEST-PRACTICES.md file in the Biovity repository.

​
Verify database setup

To verify your database is set up correctly:
  1. Check that tables were created: 
    psql "$DATABASE_URL" -c "\dt"
  2. Verify Better Auth tables exist:
    • user
    • session
    • account

​
Troubleshooting

​
Connection refused

If you see “connection refused” errors:
  • Verify PostgreSQL is running: pg_isready
  • Check the port is correct (default: 5432)
  • Ensure the host is accessible

​
Authentication failed

  • Verify username and password in DATABASE_URL
  • Check database exists: psql -U postgres -l
  • Ensure user has proper permissions

​
SSL errors with Supabase

If you encounter SSL errors, append ?sslmode=require to your connection string: 
DATABASE_URL="postgresql://...?sslmode=require"

​
Next steps

After setting up the database, proceed to running locally to start the development server.

Build docs developers (and LLMs) love

Get started for freeTalk to us