institutional-trader/README/QUICK_START_LOCAL.md

Quick Start: Local PostgreSQL Setup

Get your trading system running with a local PostgreSQL database in 5 minutes!

Prerequisites

• PostgreSQL installed (see LOCAL_DB_SETUP.md for installation)
• Node.js and npm installed
• CSV files in project root: OptionsFlow.csv, OptionsVolume.csv, OptionsOpenInterest.csv

Step-by-Step Setup

1. Install PostgreSQL (if not already installed)

Windows:

• Download from: https://www.postgresql.org/download/windows/
• Install and remember the password you set for postgres user

macOS:

brew install postgresql@15
brew services start postgresql@15

Linux:

sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

2. Configure Environment

Create backend/.env file:

USE_LOCAL_DB=true
LOCAL_DB_HOST=localhost
LOCAL_DB_PORT=5432
LOCAL_DB_USER=postgres
LOCAL_DB_PASSWORD=your_postgres_password
LOCAL_DB_NAME=institutional_trader

PORT=3010
NODE_ENV=development
CORS_ORIGIN=http://localhost:5173

Important: Replace your_postgres_password with your actual PostgreSQL password.

3. Set Up Database

cd backend
npm install
npm run setup-local-db

This creates:

• ✅ Database institutional_trader
• ✅ All necessary tables
• ✅ Indexes for performance

4. Import CSV Files

npm run import-csv

This imports:

• ✅ OptionsFlow.csv → OptionsFlow_monthly table
• ✅ OptionsVolume.csv → OptionsVolume table
• ✅ OptionsOpenInterest.csv → OptionsOpenInterest table

5. Start Server

npm run dev

You should see:

📦 Using local PostgreSQL database
✅ Database connection successful (PostgreSQL direct)
🚀 Server running on http://localhost:3010

Verify Everything Works

1. Check database connection:

   • Server should show: ✅ Database connection successful

2. Test API endpoint:

   curl http://localhost:3010/api/options/flow?startDate=2024-12-10&endDate=2024-12-10
   

3. Check data was imported:

   -- Connect to database
   psql -U postgres -d institutional_trader
   
   -- Check record counts
   SELECT COUNT(*) FROM "OptionsFlow_monthly";
   SELECT COUNT(*) FROM "OptionsVolume";
   SELECT COUNT(*) FROM "OptionsOpenInterest";
   

Troubleshooting

"Cannot connect to PostgreSQL"

1. Check PostgreSQL is running:

   # Windows: Check Services
   # macOS
   brew services list
   # Linux
   sudo systemctl status postgresql
   

2. Start PostgreSQL if needed:

   # macOS
   brew services start postgresql@15
   # Linux
   sudo systemctl start postgresql
   

"password authentication failed"

• Verify password in .env matches your PostgreSQL password
• Try connecting manually: psql -U postgres -h localhost

"database does not exist"

• Run setup again: npm run setup-local-db

Next Steps

✅ Database is set up and running locally ✅ CSV data is imported ✅ Server is running

You can now:

• Test all API endpoints
• Develop new features
• Run queries without quota limits
• Work offline

Switching Back to Remote Database

When you want to use Supabase again:

1. Update .env:

   USE_LOCAL_DB=false
   DATABASE_URL=postgresql://postgres:password@host:5432/database
   

2. Restart server

The system automatically detects which database to use based on your .env configuration.