# PostgreSQL Database Setup Guide

This guide will help you set up PostgreSQL for the Sales Brain API dashboard.

## Prerequisites

- **Docker Desktop** installed and running (not just Docker CLI)
- Python environment set up with requirements installed
- `.env` file created from `.env.example`

## Quick Setup

1. **Start Docker Desktop** (make sure it's running in the background)

2. **Start PostgreSQL and Redis services:**
   ```bash
   cd model
   docker-compose up -d
   ```
   
   If you get an error about pipe/dockerDesktopLinuxEngine, start Docker Desktop first.

2. **Wait for services to be ready (about 30 seconds):**
   ```bash
   docker-compose logs postgres
   ```
   Wait until you see "database system is ready to accept connections"

3. **Initialize the database schema:**
   ```bash
   python init_db.py
   ```

4. **Create environment variables:**
   Copy `.env.example` to `.env` and update the database connection:
   ```bash
   cp .env.example .env
   ```

   Make sure `.env` contains:
   ```
   DATABASE_URL=postgresql://salesbrain:salesbrain123@localhost:5432/salesbrain
   REDIS_URL=redis://localhost:6379
   ```

5. **Test the database migration:**
   ```bash
   python test_postgres.py
   ```
   This will verify that your PostgreSQL setup is working correctly.

6. **Start the API server:**
   ```bash
   python -m src.app.main_v2
   ```

## Database Services Overview

The `docker-compose.yml` file sets up:

- **PostgreSQL 15**: Main database on port 5432
  - Database: `salesbrain`
  - Username: `salesbrain` 
  - Password: `salesbrain123`
  - Data persisted in `postgres_data` volume

- **Redis**: Caching and session storage on port 6379
  - No authentication for local development
  - Data persisted in `redis_data` volume

## Database Schema

The database includes these main tables:

### Core Tables
- `users` - User accounts and profiles
- `organizations` - Company/organization data
- `api_keys` - API key management with usage tracking

### Dashboard Tables  
- `activities` - Activity logs and audit trail
- `usage_stats` - API usage metrics and statistics
- `subscriptions` - Billing and subscription information

### Features
- UUID primary keys for security
- Automatic timestamps (`created_at`, `updated_at`)
- Soft deletes with `is_active` flags
- Foreign key relationships with cascading
- Indexes for performance on common queries

## Development Commands

### Database Management
```bash
# Stop services
docker-compose down

# Reset database (WARNING: destroys all data)
docker-compose down -v
docker-compose up -d
python init_db.py

# View logs
docker-compose logs postgres
docker-compose logs redis

# Access PostgreSQL directly
docker-compose exec postgres psql -U salesbrain -d salesbrain
```

### Database Queries
```sql
-- Check tables
\dt

-- View users
SELECT id, email, first_name, last_name, organization_id FROM users;

-- View organizations  
SELECT id, name, plan, member_count FROM organizations_view;

-- View API keys
SELECT id, name, key_prefix, organization_id, is_active FROM api_keys;
```

## Production Setup

For production deployment:

1. **Use managed PostgreSQL service** (AWS RDS, Google Cloud SQL, etc.)

2. **Update connection security:**
   - Use SSL connections
   - Strong passwords and restricted access
   - Environment-based configuration

3. **Database migrations:**
   - Version control schema changes
   - Use migration tools like Alembic
   - Backup before migrations

4. **Monitoring and backup:**
   - Set up automated backups
   - Monitor connection pools
   - Log query performance

## Troubleshooting

### Common Issues

**Connection refused:**
```bash
# Check if PostgreSQL is running
docker-compose ps
docker-compose logs postgres
```

**Database doesn't exist:**
```bash
# Recreate database
docker-compose down -v
docker-compose up -d
python init_db.py
```

**Permission denied:**
```bash
# Check Docker permissions
docker-compose down
sudo docker-compose up -d
```

### Environment Variables

Make sure these are set in your `.env` file:
```env
# Database
DATABASE_URL=postgresql://salesbrain:salesbrain123@localhost:5432/salesbrain
REDIS_URL=redis://localhost:6379

# API Keys (add your own)
OPENAI_API_KEY=your_openai_key_here
AZURE_SPEECH_KEY=your_azure_key_here
AZURE_SPEECH_REGION=your_azure_region_here

# Security
JWT_SECRET=your_jwt_secret_here
API_KEY_SECRET=your_api_key_secret_here
```

### Database Connection Testing

Test the connection with Python:
```python
import asyncio
import asyncpg

async def test_connection():
    conn = await asyncpg.connect("postgresql://salesbrain:salesbrain123@localhost:5432/salesbrain")
    result = await conn.fetchval("SELECT version()")
    print(f"Connected to: {result}")
    await conn.close()

asyncio.run(test_connection())
```

## Migration from In-Memory Storage

The dashboard has been migrated from in-memory dictionaries to PostgreSQL:

### Benefits
- **Data Persistence**: Data survives server restarts
- **Better Performance**: Indexed queries and connection pooling  
- **Scalability**: Support for multiple instances
- **Data Integrity**: ACID transactions and foreign key constraints
- **Analytics**: Complex queries for reporting and analytics

### API Compatibility
- All existing API endpoints work the same
- Same response formats and data structures
- Backward compatible with existing client code

The migration is complete and the API should work seamlessly with the new database backend!