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:

# 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:

# 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:

cd backend
uv run alembic upgrade head

3. Start the Backend API

cd backend
uv run fastapi dev app/main.py

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

4. Run Flutter App

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

Or manually:

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

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)

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

Use Supabase

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:

   # macOS
   brew services list | grep postgresql
   
   # Or check if port is listening
   lsof -i :5432
   

2. Verify credentials:

   psql -h localhost -p 5432 -U sibu -d sibu
   

3. Check database exists:

   \l  -- List databases
   

Flutter Can't Connect to Backend

1. Check backend is running:

   curl http://localhost:8000/health
   

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

3. Verify API URL in Flutter:

   // Check ApiClient base URL
   print(ApiClient.instance._baseUrl);
   

Database Schema Issues

If tables don't exist:

1. Apply migrations:

   cd backend
   uv run alembic upgrade head
   

2. Or manually create from Supabase migrations:

   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:

   cd backend
   uv run fastapi dev app/main.py
   

3. Run Flutter App:

   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.