feat: Add database setup guide and local configuration files
- Added DATABASE_SETUP.md with comprehensive guide for PostgreSQL and Redis installation on Windows - Created .claude/settings.local.json with permission settings for pytest and database fix scripts - Updated .gitignore to exclude .env.backup file - Included database connection test utilities in lyra/database_setup.py - Added environment variable configuration examples for local development
This commit is contained in:
182
DATABASE_SETUP.md
Normal file
182
DATABASE_SETUP.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# 🗄️ 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!**
|
||||
Reference in New Issue
Block a user