Lyra/DATABASE_SETUP.md

🗄️ Database Setup Guide for Lyra AI

This guide will help you set up PostgreSQL and Redis locally on Windows for Lyra AI.

📋 Prerequisites

• Windows 10/11
• Administrator privileges for installation
• At least 2GB free disk space

🐘 PostgreSQL Installation

Option 1: Automated Installation (Recommended)

The automated installation should be running. If it completes successfully, skip to the Configuration section.

Option 2: Manual Installation

If the automated installation fails or you prefer manual installation:

1. Download PostgreSQL:

   • Go to https://www.postgresql.org/download/windows/
   • Download PostgreSQL 17 for Windows x86-64

2. Run the Installer:

   • Run as Administrator
   • Installation Directory: Keep default C:\Program Files\PostgreSQL\17
   • Data Directory: Keep default
   • Password: Choose a strong password for the postgres user (remember this!)
   • Port: Keep default 5432
   • Locale: Keep default

3. Verify Installation:

   # Open Command Prompt and run:
   "C:\Program Files\PostgreSQL\17\bin\psql.exe" --version
   

🔴 Redis Installation (Memurai)

Option 1: Automated Installation (Recommended)

The automated Memurai installation should be running. If it completes successfully, skip to the Configuration section.

Option 2: Manual Installation

If you need to install manually:

1. Download Memurai:

   • Go to https://www.memurai.com/
   • Download Memurai Developer (free for development)

2. Install Memurai:

   • Run the installer as Administrator
   • Keep all default settings
   • Port: 6379 (default)
   • Service: Enable "Install as Windows Service"

3. Start Memurai Service:

   # Open Command Prompt as Administrator and run:
   net start Memurai
   

⚙️ Configuration

1. Update Environment Variables

Edit the .env file in your Lyra project directory:

# Replace 'your_password_here' with your actual PostgreSQL password
DATABASE_URL=postgresql://postgres:YOUR_ACTUAL_PASSWORD@localhost:5432/lyra
REDIS_URL=redis://localhost:6379/0

Important: Replace YOUR_ACTUAL_PASSWORD with the password you set during PostgreSQL installation.

2. Create Lyra Database

Open Command Prompt and run:

# Navigate to PostgreSQL bin directory
cd "C:\Program Files\PostgreSQL\17\bin"

# Connect to PostgreSQL
psql.exe -U postgres -h localhost

# Enter your password when prompted, then run:
CREATE DATABASE lyra;
\q

3. Test Database Connections

Run the database connection test script:

cd C:\Development\Lyra
python test_database_connections.py

Expected output:

✅ PostgreSQL connected successfully!
✅ Redis connected successfully!
🎉 ALL DATABASE TESTS PASSED!

🚨 Troubleshooting

PostgreSQL Issues

Problem: psql: command not found

• Solution: Add PostgreSQL to your PATH:
  1. Open System Properties → Environment Variables
  2. Add C:\Program Files\PostgreSQL\17\bin to your PATH
  3. Restart Command Prompt

Problem: password authentication failed

• Solution: Double-check your password in the .env file

Problem: database "lyra" does not exist

• Solution: Create the database manually using the steps above

Redis/Memurai Issues

Problem: Connection refused to localhost:6379

• Solution: Start the Memurai service:

  net start Memurai
  

Problem: redis module not found

• Solution: Install the Redis Python package:

  pip install redis
  

General Issues

Problem: Import errors in test script

• Solution: Install missing dependencies:

  pip install asyncpg redis python-dotenv
  

✅ Verification Checklist

Before proceeding with Lyra, ensure:

• PostgreSQL is installed and running
• Redis/Memurai is installed and running
• .env file has correct database credentials
• lyra database exists in PostgreSQL
• Database connection test passes
• No firewall blocking ports 5432 or 6379

🚀 Next Steps

Once databases are configured and tested:

1. Start Lyra:

   cd C:\Development\Lyra
   python -m lyra.main
   

2. Monitor Logs:

   • Check logs/lyra.log for any database connection issues
   • Lyra will automatically create necessary database tables on first run

📞 Need Help?

If you encounter issues:

1. Check the logs/lyra.log file for detailed error messages
2. Verify all services are running:
   • PostgreSQL: Check Windows Services for "postgresql-x64-17"
   • Redis: Check Windows Services for "Memurai"
3. Test connections individually using the test script

---

🎭 Once databases are configured, Lyra will have full persistence for conversations, personality evolution, and knowledge storage!