218 lines
5.1 KiB
Markdown
218 lines
5.1 KiB
Markdown
# 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:
|
|
|
|
```typescript
|
|
// Default behavior:
|
|
// - Development: ../../apps/admin/data/fitai.db
|
|
// - Production: ./data/fitai.db
|
|
// - Custom: Set DATABASE_URL environment variable
|
|
```
|
|
|
|
**Environment Variable**:
|
|
```bash
|
|
# Optional: Override default database path
|
|
DATABASE_URL=/path/to/your/fitai.db
|
|
```
|
|
|
|
### Admin App
|
|
|
|
The admin app uses the following database path configuration:
|
|
|
|
```typescript
|
|
// 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**:
|
|
```bash
|
|
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:
|
|
|
|
```typescript
|
|
// packages/database/drizzle.config.ts
|
|
dbCredentials: {
|
|
url: "../../apps/admin/data/fitai.db"
|
|
}
|
|
```
|
|
|
|
**Drizzle Commands**:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# From project root
|
|
cp apps/admin/data/fitai.db backups/fitai-$(date +%Y%m%d-%H%M%S).db
|
|
```
|
|
|
|
### Restoring from Backup
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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)**
|
|
```bash
|
|
cd packages/database
|
|
npm run db:studio
|
|
# Opens at http://localhost:4983
|
|
```
|
|
|
|
**Option 2: SQLite CLI**
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
mkdir -p /path/to/data
|
|
chmod 755 /path/to/data
|
|
```
|
|
|
|
### Backup Strategy
|
|
|
|
Implement automated backups in production:
|
|
|
|
```bash
|
|
# 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](./CLERK_WEBHOOK_SETUP.md) - User synchronization
|
|
- [Testing Fitness Profile](./TESTING_FITNESS_PROFILE.md) - Feature testing
|
|
- [Webhook Database Fix](./WEBHOOK_DATABASE_FIX.md) - Webhook implementation details
|