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**:
   ```cmd
   # 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**:
   ```cmd
   # Open Command Prompt as Administrator and run:
   net start Memurai
   ```

## ⚙️ **Configuration**

### **1. Update Environment Variables**

Edit the `.env` file in your Lyra project directory:

```env
# 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:

```cmd
# 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:

```cmd
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:
  ```cmd
  net start Memurai
  ```

**Problem**: `redis module not found`
- **Solution**: Install the Redis Python package:
  ```cmd
  pip install redis
  ```

### **General Issues**

**Problem**: Import errors in test script
- **Solution**: Install missing dependencies:
  ```cmd
  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**:
   ```cmd
   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!**