SIB/old/README-POSTGRESQL-SETUP.md

# PostgreSQL Direct Connection Setup

This guide explains how to use the PostgreSQL database directly instead of Supabase.

## Architecture

Since Flutter web cannot connect directly to PostgreSQL from the browser (security restrictions), we use a two-tier architecture:

```
Flutter App (Web) → FastAPI Backend → PostgreSQL Database
```

The backend acts as an API layer that connects to PostgreSQL and exposes REST endpoints.

## Database Configuration

The PostgreSQL database is configured as:
- **Host**: localhost
- **Port**: 5432
- **Database**: sibu
- **Username**: sibu
- **Password**: sibu

Connection string: `postgresql+asyncpg://sibu:sibu@localhost:5432/sibu`

## Setup Steps

### 1. Ensure PostgreSQL is Running

Make sure your PostgreSQL database is running and accessible:

```bash
# Test connection (if you have psql installed)
psql -h localhost -p 5432 -U sibu -d sibu
```

### 2. Apply Database Migrations

The database schema needs to be created. You have two options:

#### Option A: Use Supabase Migrations

If you have the Supabase migrations in `supabase/migrations/`, you can apply them directly:

```bash
# Connect to PostgreSQL and run migrations
psql -h localhost -p 5432 -U sibu -d sibu -f supabase/migrations/20241019215951_sibu_transportation_system.sql
# ... apply other migrations
```

#### Option B: Use Alembic (Backend Migrations)

The backend uses Alembic for migrations:

```bash
cd backend
uv run alembic upgrade head
```

### 3. Start the Backend API

```bash
cd backend
uv run fastapi dev app/main.py
```

The API will be available at `http://localhost:8000`

### 4. Run Flutter App

```bash
cd old
./scripts/run-flutter-backend.sh
```

Or manually:

```bash
flutter run -d chrome --dart-define=API_BASE_URL=http://localhost:8000
```

## Backend API Endpoints

The backend provides the following endpoints:

- `GET /api/routes` - Get all routes
- `GET /api/routes/{route_id}` - Get specific route
- `GET /api/bus-stops` - Get all bus stops
- `GET /api/bus-stops/{stop_id}` - Get specific bus stop
- `GET /api/schedules` - Get schedules (with optional route_id, stop_id filters)
- `GET /api/coupons` - Get coupons (with optional category, is_active filters)
- `GET /api/taxis` - Get taxis (with optional filters)
- `GET /health` - Health check

## Configuration Files

### Backend Configuration

**File**: `backend/.env.development`
```env
DATABASE_URL=postgresql+asyncpg://sibu:sibu@localhost:5432/sibu
ENVIRONMENT=development
DEBUG=true
```

**File**: `backend/app/core/config.py`
- Default database URL is set to your PostgreSQL connection

### Flutter Configuration

The Flutter app uses `ApiClient` service which:
- Defaults to `http://localhost:8000`
- Can be configured via `--dart-define=API_BASE_URL=<url>`

## Switching Between Supabase and PostgreSQL

### Use PostgreSQL (via Backend API)
```bash
cd old
./scripts/run-flutter-backend.sh
```

### Use Supabase
```bash
cd old
./scripts/run-flutter-local.sh  # For local Supabase
# OR
flutter run -d chrome \
  --dart-define=SUPABASE_URL=<url> \
  --dart-define=SUPABASE_ANON_KEY=<key>
```

## Troubleshooting

### Backend Can't Connect to PostgreSQL

1. **Check PostgreSQL is running:**
   ```bash
   # macOS
   brew services list | grep postgresql
   
   # Or check if port is listening
   lsof -i :5432
   ```

2. **Verify credentials:**
   ```bash
   psql -h localhost -p 5432 -U sibu -d sibu
   ```

3. **Check database exists:**
   ```sql
   \l  -- List databases
   ```

### Flutter Can't Connect to Backend

1. **Check backend is running:**
   ```bash
   curl http://localhost:8000/health
   ```

2. **Check CORS settings** in `backend/app/main.py`

3. **Verify API URL** in Flutter:
   ```dart
   // Check ApiClient base URL
   print(ApiClient.instance._baseUrl);
   ```

### Database Schema Issues

If tables don't exist:

1. **Apply migrations:**
   ```bash
   cd backend
   uv run alembic upgrade head
   ```

2. **Or manually create from Supabase migrations:**
   ```bash
   psql -h localhost -p 5432 -U sibu -d sibu < supabase/migrations/20241019215951_sibu_transportation_system.sql
   ```

## Development Workflow

1. **Start PostgreSQL** (if not running as a service)
2. **Start Backend API:**
   ```bash
   cd backend
   uv run fastapi dev app/main.py
   ```
3. **Run Flutter App:**
   ```bash
   cd old
   ./scripts/run-flutter-backend.sh
   ```

## Next Steps

The Flutter app services need to be updated to use `ApiClient` instead of `SupabaseService`. Currently, the app still uses Supabase. To fully migrate:

1. Update `TransportationService` to use `ApiClient`
2. Update `CouponService` to use `ApiClient`
3. Update `TaxiService` to use `ApiClient`
4. Remove or make optional `SupabaseService`

This migration can be done incrementally.