LightRAG/MIGRATION_STEPS.md

Migration Steps - Session History Integration

Current Situation

You are on the session_intergrate branch which still uses the old service/ folder approach. The new integration code I created uses lightrag/api/session_* modules.

Quick Fix Applied

I've updated these files to use the new integrated modules:

1. lightrag/api/routers/query_routes.py

Changed imports from:

from app.core.database import SessionLocal
from app.services.history_manager import HistoryManager

To:

from lightrag.api.session_database import SessionLocal, get_db
from lightrag.api.session_manager import SessionHistoryManager

2. lightrag/api/session_database.py

Added SessionLocal alias for backward compatibility:

SessionLocal = lambda: get_session_db_manager().get_session()

Steps to Complete Migration

1. Install Dependencies

cd /d/work/LightRAG
pip install sqlalchemy psycopg2-binary httpx

2. Configure PostgreSQL

Ensure your .env file has PostgreSQL configured:

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DATABASE=lightrag_db

3. Start PostgreSQL

If using Docker:

docker run -d --name postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=lightrag_db \
  -p 5432:5432 \
  postgres:16

Or use existing PostgreSQL instance.

4. Test Server

cd /d/work/LightRAG
lightrag-server

Check logs for:

INFO: Session history database initialized successfully

5. Test Session Endpoints

# Create a session
curl -X POST http://localhost:9621/history/sessions \
  -H "Content-Type: application/json" \
  -H "X-User-ID: test@example.com" \
  -d '{"title": "Test Session"}'

# List sessions
curl http://localhost:9621/history/sessions \
  -H "X-User-ID: test@example.com"

Troubleshooting

Error: "Failed to fetch sessions: 500"

Cause: PostgreSQL not configured or not running

Fix:

1. Check .env has POSTGRES_* variables
2. Start PostgreSQL
3. Check server logs for database connection errors

Error: "ModuleNotFoundError: No module named 'httpx'"

Fix:

pip install httpx

Error: "No module named 'sqlalchemy'"

Fix:

pip install sqlalchemy psycopg2-binary

Database Connection Refused

Fix:

1. Check PostgreSQL is running:

   # Windows
   tasklist | findstr postgres
   
   # Linux/Mac
   ps aux | grep postgres
   

2. Test connection:

   psql -h localhost -U postgres -d lightrag_db
   

3. Check firewall not blocking port 5432

Clean Migration (Recommended)

If you want to start fresh with the new integrated approach:

1. Backup Current Work

git stash save "backup before migration"

2. Create New Branch

git checkout -b session-integrated-clean

3. Apply New Files

Copy all the new files I created:

• lightrag/api/session_models.py
• lightrag/api/session_schemas.py
• lightrag/api/session_database.py
• lightrag/api/session_manager.py
• Updated lightrag/api/routers/history_routes.py
• Updated lightrag/api/routers/query_routes.py
• Updated lightrag/api/lightrag_server.py

4. Remove Old Service Folder

mv service service.backup

5. Test

lightrag-server

Files Modified

• ✅ lightrag/api/session_models.py - NEW
• ✅ lightrag/api/session_schemas.py - NEW
• ✅ lightrag/api/session_database.py - NEW
• ✅ lightrag/api/session_manager.py - NEW
• ✅ lightrag/api/routers/history_routes.py - UPDATED
• ✅ lightrag/api/routers/query_routes.py - UPDATED
• ✅ lightrag/api/lightrag_server.py - UPDATED
• ✅ docker-compose.yml - SIMPLIFIED
• ✅ env.example - UPDATED
• ✅ README.md - UPDATED

Next Steps

1. Test the integrated version
2. If working, commit the changes
3. Remove old service/ folder
4. Update documentation
5. Deploy!

Support

If issues persist:

1. Check all files are properly updated
2. Ensure PostgreSQL is accessible
3. Review server logs
4. Create GitHub issue with logs