backend/docs/README_POSTGRESQL.md

PostgreSQL Setup for AegisLM

🐳 Option 1: Docker (Easiest)

Step 1: Install Docker Desktop

1. Download Docker Desktop from https://www.docker.com/products/docker-desktop/
2. Install and start Docker Desktop
3. Make sure Docker is running (check system tray)

Step 2: Start PostgreSQL

cd d:\Projects\ALM\backend
docker-compose up -d postgres

Step 3: Verify Connection

docker-compose logs postgres

Step 4: Run Setup Script

python setup_postgresql.py

🪟 Option 2: Windows Native Installation

Step 1: Download PostgreSQL

1. Go to https://www.enterprisedb.com/downloads/postgres-postgresql-downloads
2. Download PostgreSQL for Windows (version 15 or later)
3. Run the installer

Step 2: Installation Settings

• Password: password (match .env file)
• Port: 5432
• Username: postgres
• Database: aegislm (create after installation)

Step 3: Start PostgreSQL Service

1. Open Windows Services
2. Find "postgresql-x64-15" (or similar version)
3. Right-click → Start

Step 4: Create Database

Open Command Prompt and run:

psql -U postgres -c "CREATE DATABASE aegislm;"

Step 5: Test Connection

psql -U postgres -d aegislm

🌐 Option 3: Cloud PostgreSQL (Production Ready)

Neon (Recommended for Production)

1. Sign up at https://neon.tech/
2. Create new project
3. Get connection string
4. Update .env file:

DATABASE_URL="postgresql+asyncpg://user:password@ep-xxx.us-east-2.aws.neon.tech/aegislm?sslmode=require"

AWS RDS

1. Go to AWS Console → RDS
2. Create PostgreSQL instance
3. Configure security group to allow your IP
4. Update connection string

Railway

1. Sign up at https://railway.app/
2. Add PostgreSQL service
3. Get connection string
4. Update .env file

🔧 Configuration

Update .env file

# Database - PostgreSQL Production
DATABASE_URL="postgresql+asyncpg://postgres:password@localhost:5432/aegislm"
DATABASE_POOL_SIZE=10
DATABASE_MAX_OVERFLOW=20

Test Connection

python setup_postgresql.py

🚨 Troubleshooting

Connection Refused Error

1. Check if PostgreSQL is running
2. Verify port 5432 is available
3. Check firewall settings
4. Verify credentials in .env

Docker Issues

1. Make sure Docker Desktop is running
2. Check if port 5432 is already in use
3. Try docker system prune to clean up

Permission Issues

1. Run Command Prompt as Administrator
2. Check PostgreSQL service status
3. Verify user permissions

✅ Verification

After setup, run:

python setup_postgresql.py

You should see:

🎉 POSTGRESQL SETUP COMPLETE!
✅ PostgreSQL is ready for production!
✅ All database operations working!
✅ Health checks passing!

🔄 Migration from SQLite

If you have existing data in SQLite:

1. Export data from SQLite
2. Import to PostgreSQL
3. Update .env to use PostgreSQL
4. Run setup script

🚀 Production Deployment

For production:

1. Use cloud PostgreSQL (Neon/AWS/Railway)
2. Enable SSL
3. Use environment variables for credentials
4. Set up connection pooling
5. Configure backups