LightRAG/SESSION_FINAL_SIMPLIFICATION.md

Session History - Final Simplification

What Changed

Based on user feedback, we've completely removed SESSION_POSTGRES_* variables and simplified to use only the existing POSTGRES_* configuration.

Before vs After

❌ Before (Too Complex)

SESSION_POSTGRES_HOST=localhost
SESSION_POSTGRES_PORT=5433
SESSION_POSTGRES_USER=lightrag
SESSION_POSTGRES_PASSWORD=lightrag_password
SESSION_POSTGRES_DATABASE=lightrag_sessions

✅ After (Simple!)

# Just enable it!
SESSION_HISTORY_ENABLED=true

# That's it! Uses existing POSTGRES_* automatically

Configuration

Session history now always uses the same PostgreSQL as LightRAG:

# Your existing LightRAG configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DATABASE=lightrag_db

# Enable session history - no additional config needed!
SESSION_HISTORY_ENABLED=true

Database Tables

These tables will be created in your POSTGRES_DATABASE:

• lightrag_chat_sessions_history
• lightrag_chat_messages_history
• lightrag_message_citations_history

All in the same database as your LightRAG data. Clean and simple!

Docker Compose

No separate database container needed:

services:
  lightrag:
    # ... your existing config
    # Session history uses same PostgreSQL

Benefits

1. ✅ Zero additional configuration
2. ✅ No confusion about which ENV to use
3. ✅ One PostgreSQL instance
4. ✅ Easier to manage
5. ✅ Simpler docker setup

Migration

If you had SESSION_POSTGRES_* in your .env, just remove them:

# Remove these lines (no longer used)
# SESSION_POSTGRES_HOST=...
# SESSION_POSTGRES_PORT=...
# SESSION_POSTGRES_USER=...
# SESSION_POSTGRES_PASSWORD=...
# SESSION_POSTGRES_DATABASE=...

# Keep only this
SESSION_HISTORY_ENABLED=true

Code Changes

session_database.py

• Removed all SESSION_POSTGRES_* references
• Uses POSTGRES_* directly
• Cleaner, simpler code

env.example

• Removed all SESSION_POSTGRES_* variables
• Single line: SESSION_HISTORY_ENABLED=true

docker-compose.yml

• Removed separate session-db service
• No volumes needed for separate session DB

Why This Makes Sense

1. Single Source of Truth: One set of database credentials
2. No Duplication: Don't repeat POSTGRES_* with different names
3. KISS Principle: Keep It Simple, Stupid
4. User Feedback: Based on actual user needs

Use Cases

Development

POSTGRES_HOST=localhost
POSTGRES_DATABASE=dev_lightrag
SESSION_HISTORY_ENABLED=true

✅ Everything in one place

Production

POSTGRES_HOST=prod-db.example.com
POSTGRES_DATABASE=lightrag_prod
SESSION_HISTORY_ENABLED=true

✅ Production-ready with minimal config

Testing

POSTGRES_HOST=localhost
POSTGRES_DATABASE=test_lightrag
SESSION_HISTORY_ENABLED=false

✅ Easy to disable when not needed

What If I Need Separate Database?

If you really need a separate database for sessions (rare case), you can:

1. Use a different POSTGRES_DATABASE name in Docker Compose
2. Or modify session_database.py locally for your needs

But honestly, for 99% of use cases, same database is fine!

Summary

Before: Confusing with multiple ENV variables for the same thing After: One line to enable, uses existing configuration

That's the power of simplicity! 🎉

---

Technical Details

The SessionDatabaseConfig class now simply reads POSTGRES_*:

class SessionDatabaseConfig:
    def __init__(self):
        self.host = os.getenv("POSTGRES_HOST", "localhost")
        self.port = os.getenv("POSTGRES_PORT", "5432")
        self.user = os.getenv("POSTGRES_USER", "postgres")
        self.password = os.getenv("POSTGRES_PASSWORD", "password")
        self.database = os.getenv("POSTGRES_DATABASE", "lightrag_db")
        # ... build connection string

No fallbacks, no overrides, no confusion. Just works! ✨