docs/PERSISTENT_DATABASE_SETUP.md

Setting Up Persistent Database for AI Learning Path Generator

This guide explains how to set up a free PostgreSQL database so users can:

• Login from any device
• Sync their learning paths across devices
• Keep their progress saved permanently

Quick Setup (5 minutes)

Step 1: Create a Free Neon Database

1. Go to Neon and sign up (free)
2. Create a new project (e.g., "ai-learning-paths")
3. Copy the connection string (looks like: postgresql://user:pass@host/db?sslmode=require)

Step 2: Add to HuggingFace Spaces Secrets

1. Go to your HuggingFace Space settings
2. Click on "Settings" → "Repository secrets"
3. Add a new secret:
   • Name: DATABASE_URL
   • Value: Your Neon connection string

Step 3: Restart Your Space

The app will automatically create all needed tables on startup.

Free Database Options

Provider	Free Tier	Best For
Neon	0.5GB, auto-suspend	Recommended - fastest
Supabase	500MB, 50K requests	Good alternative
CockroachDB	5GB	Distributed

Local Development

For local testing, you can either:

1. Use SQLite (default): Just leave DATABASE_URL empty
2. Use PostgreSQL: Set DATABASE_URL in your .env file

Verify Setup

After deployment, check the logs for:

DATABASE_URL is configured (using PostgreSQL for persistent storage)
✅ Database initialized

Mobile App Configuration

The mobile app automatically syncs with the backend when users are logged in. Data is stored:

• Logged-in users: Server database (synced across devices)
• Guest users: Local device storage only

Troubleshooting

"Connection refused" errors

• Check if the connection string is correct
• Ensure ?sslmode=require is at the end for Neon

"Table doesn't exist" errors

• The app auto-creates tables on startup
• Restart the Space to re-run initialization

Data not syncing

• Ensure user is logged in (not guest mode)
• Check network connectivity to the API