Skip to main content

​
Prerequisites

  • PostgreSQL 16 or later
  • Node.js ≥ 20
  • pnpm package manager

​
Using Docker Compose

The easiest way to get started is using the included Docker Compose configuration: 
docker compose up -d
This starts a PostgreSQL 16 container with:
  • Port: 5432
  • User: postgres (configurable via POSTGRES_USER)
  • Password: postgres (configurable via POSTGRES_PASSWORD)
  • Database: toots (configurable via POSTGRES_DB)
  • Persistent volume: db_data
Make sure to set POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB in your environment or root .env file before running Docker Compose.

​
Manual PostgreSQL setup

If you prefer to use an existing PostgreSQL instance:
  1. Create a database for Toots:
CREATE DATABASE toots;
  1. Update your DATABASE_URL in apps/web/.env:
DATABASE_URL="postgresql://[user]:[password]@[host]:[port]/toots"

​
Database schema

Toots uses Prisma for database management. The schema includes:

​
Core models

  • User - User accounts with email/password authentication
  • Session - User sessions managed by better-auth
  • Account - OAuth and credential account information
  • Project - Projects with tickets and chat messages
  • Ticket - Actionable work items with priority, type, and status
  • Message - Project chat history
  • Verification - Email verification tokens

​
Key relationships

User
├── sessions: Session[]
├── accounts: Account[]
└── projects: Project[]

Project
├── user: User
├── messages: Message[]
└── tickets: Ticket[]

​
Running migrations

After configuring your database connection, run migrations to create the schema: 
pnpm --filter web db:migrate
This runs prisma migrate dev, which:
  1. Creates migration files if the schema changed
  2. Applies pending migrations to your database
  3. Generates the Prisma Client
Always run migrations before starting the development server or deploying to production.

​
Database scripts

The web app includes several helpful database scripts:

​
Generate Prisma Client

Regenerate the Prisma Client after schema changes: 
pnpm --filter web db:generate

​
Database push

Push schema changes without creating migration files (useful for prototyping): 
pnpm --filter web db:push
db:push is not recommended for production. Use db:migrate to create versioned migration files.

​
Prisma Studio

Open Prisma Studio to view and edit database records: 
pnpm --filter web db:studio
This opens a visual database browser at http://localhost:5555.

​
Production deployment

For production builds, migrations are automatically run as part of the build process:
package.json
{
  "scripts": {
    "build": "prisma generate && prisma migrate deploy && next build"
  }
}
The prisma migrate deploy command:
  • Applies pending migrations without prompting
  • Does not create new migrations
  • Suitable for CI/CD pipelines

​
Connection pooling

Toots uses the @prisma/adapter-pg for connection pooling. This is configured automatically through the Prisma schema:
schema.prisma
datasource db {
  provider = "postgresql"
}
The database adapter is configured in the application code to use the pg package for efficient connection management.

​
Troubleshooting

​
Migration failed

If a migration fails:
  1. Check your DATABASE_URL is correct
  2. Ensure the database exists
  3. Verify PostgreSQL is running
  4. Check database logs for errors

​
Connection refused

If you can’t connect to the database: 
# Check if PostgreSQL is running
docker compose ps

# View PostgreSQL logs
docker compose logs db

​
Reset database

To reset your database (WARNING: deletes all data): 
pnpm --filter web db:push --force-reset

​
Next steps

After setting up your database:
  1. Configure authentication
  2. Set up AI integration
  3. Start the development server

Build docs developers (and LLMs) love

Get started for freeTalk to us