fitaiProto/docs/DATABASE_SETUP.md

Database Setup Guide

Database Location

Primary Database: apps/admin/data/fitai.db

This is the single source of truth for all application data. All API routes, migration scripts, and database operations use this file.

Database Path Configuration

Database Package (@fitai/database)

The database package supports configurable paths via environment variables:

// Default behavior:
// - Development: ../../apps/admin/data/fitai.db
// - Production: ./data/fitai.db
// - Custom: Set DATABASE_URL environment variable

Environment Variable:

# Optional: Override default database path
DATABASE_URL=/path/to/your/fitai.db

Admin App

The admin app uses the following database path configuration:

// Default: ./data/fitai.db (relative to apps/admin/)
filename: './data/fitai.db'

All API routes and scripts use this consistent path.

Migration Scripts

All migration scripts are located in apps/admin/scripts/ and use the correct database path:

• seed-superadmin.js - Creates super admin user
• migrate-roles.js - Adds role column to users table
• migrate-fitness-profile.js - Adds allergies and injuries columns
• migrate-last-visit.js - Adds lastVisit column to clients table

Running Migrations:

cd apps/admin
node scripts/migrate-fitness-profile.js
node scripts/migrate-roles.js
node scripts/migrate-last-visit.js

Drizzle ORM

Drizzle Kit is configured to use the admin database:

// packages/database/drizzle.config.ts
dbCredentials: {
  url: "../../apps/admin/data/fitai.db"
}

Drizzle Commands:

cd packages/database

# Push schema changes to database
npm run db:push

# Open Drizzle Studio (database GUI)
npm run db:studio

Backup and Restore

Creating a Backup

# From project root
cp apps/admin/data/fitai.db backups/fitai-$(date +%Y%m%d-%H%M%S).db

Restoring from Backup

# From project root
cp backups/fitai-YYYYMMDD-HHMMSS.db apps/admin/data/fitai.db

Database Schema

The database uses SQLite with the following main tables:

• users - User accounts (admin, trainer, client)
• clients - Client profiles linked to users
• fitness_profiles - Fitness goals, preferences, and health info
• payments - Payment records
• attendance - Check-in/check-out records
• notifications - User notifications
• recommendations - AI-generated fitness recommendations

Troubleshooting

Database Not Found Error

If you see "database not found" errors:

1. Ensure you're running commands from the correct directory
2. Check that apps/admin/data/fitai.db exists
3. Verify file permissions (should be readable/writable)

Multiple Database Files

There should only be ONE database file: apps/admin/data/fitai.db

If you find other fitai.db files:

• data/fitai.db (root level) - Old duplicate, should not exist
• packages/database/fitai.db - Old duplicate, should not exist

These were consolidated on 2025-11-26. Backups are in backups/database-consolidation-2025-11-26/.

Migration Script Errors

If migration scripts fail:

1. Check that you're in the apps/admin directory
2. Verify the database file exists and is writable
3. Check the script output for specific error messages
4. Ensure no other process has the database locked

Development Workflow

Starting Fresh

# Remove existing database
rm apps/admin/data/fitai.db

# Run migrations to create tables
cd packages/database
npm run db:push

# Seed super admin user
cd ../../apps/admin
node scripts/seed-superadmin.js

Viewing Database Contents

Option 1: Drizzle Studio (Recommended)

cd packages/database
npm run db:studio
# Opens at http://localhost:4983

Option 2: SQLite CLI

cd apps/admin/data
sqlite3 fitai.db
# Then run SQL queries
SELECT * FROM users;
.exit

Option 3: VS Code Extension Install "SQLite Viewer" extension and open apps/admin/data/fitai.db

Production Deployment

Environment Variables

Set the following in production:

# Optional: Custom database path
DATABASE_URL=/var/data/fitai.db

# Set production mode
NODE_ENV=production

Database Location in Production

Ensure the database directory exists and has proper permissions:

mkdir -p /path/to/data
chmod 755 /path/to/data

Backup Strategy

Implement automated backups in production:

# Daily backup cron job
0 2 * * * cp /var/data/fitai.db /var/backups/fitai-$(date +\%Y\%m\%d).db

Security Considerations

1. Never commit the database file to git - It's in .gitignore
2. Protect database file permissions - Only application should have access
3. Regular backups - Implement automated backup strategy
4. Encryption at rest - Consider encrypting the database file in production
5. Access control - Ensure only authorized users can access the database

Related Documentation

• Clerk Webhook Setup - User synchronization
• Testing Fitness Profile - Feature testing
• Webhook Database Fix - Webhook implementation details