Docs reorg, config refactor, and ItemValues index fix

- Moved all documentation to docs/ and updated README with categorized links and new docs/INDEX.md - Added HOW_TO_SWITCH_DATABASE.md and several new analysis/action docs - Introduced db-config.ps1 for centralized DB config; all scripts now use it for easy DB switching - Added db-quick.ps1 for interactive diagnostics and index management - Updated Add-All-Indexes.bat to use db-config.ps1 - Added Fix-ItemValues-Performance.ps1 to create 3 critical indexes on ItemValues, addressing 1.3B row seq scan issue - Updated performance_indexes.sql with new ItemValues indexes and ANALYZE - Updated diagnostics.sql and database_report.txt for improved output and clarity - All scripts and docs now reference the new config and index optimization workflow
2026-02-28 16:23:43 -05:00
parent 5565dc3e05
commit 78c8d4256c
31 changed files with 3089 additions and 5 deletions
@@ -0,0 +1,291 @@
+# 🎯 How to Switch Database Connections
+
+## Quick Answer
+
+**Edit `db-config.ps1`** and change this line:
+```powershell
+$DB_NAME = "jellyfin_testsdata"  # ← Change this
+```
+
+To:
+```powershell
+$DB_NAME = "your_database_name"  # ← Your database
+```
+
+Then reload:
+```powershell
+. .\db-config.ps1
+```
+
+---
+
+## Step-by-Step Guide
+
+### Method 1: Edit Configuration File (Recommended)
+
+**Step 1: Open `db-config.ps1`**
+```powershell
+code db-config.ps1  # Or notepad db-config.ps1
+```
+
+**Step 2: Change the database name**
+```powershell
+# Line 5:
+$DB_NAME = "jellyfin"              # ← Original
+$DB_NAME = "jellyfin_testsdata"    # ← Testing database
+$DB_NAME = "your_database"         # ← Your choice
+```
+
+**Step 3: Save and reload**
+```powershell
+. .\db-config.ps1
+```
+
+**Step 4: Verify**
+```powershell
+Write-Host "Connected to: $DB_NAME"
+```
+
+---
+
+### Method 2: Temporary Override (For One Command)
+
+Override just for one command without changing the config:
+
+```powershell
+# Run diagnostics against a different database
+$DB_NAME = "other_database"
+& "C:\Program Files\PostgreSQL\18\bin\psql.exe" -U jellyfin -d $DB_NAME -f sql\diagnostics.sql
+```
+
+---
+
+### Method 3: Use the Quick Runner
+
+**Step 1: Run the menu**
+```powershell
+.\db-quick.ps1
+```
+
+**Step 2: Select option 6** (Change database)
+
+**Step 3: Follow the instructions** shown
+
+---
+
+## What Gets Updated
+
+When you change `db-config.ps1`, these scripts will use the new database:
+
+| Script | What It Does |
+|--------|--------------|
+| `db-quick.ps1` | Interactive menu for common tasks |
+| `Add-All-Indexes.bat` | Add performance indexes |
+| Any script that uses `. .\db-config.ps1` | Uses the configured database |
+
+---
+
+## Common Database Names
+
+Based on your setup:
+
+```powershell
+# Production
+$DB_NAME = "jellyfin"
+
+# Testing
+$DB_NAME = "jellyfin_testsdata"
+
+# Development
+$DB_NAME = "jellyfin_dev"
+
+# Backup
+$DB_NAME = "jellyfin_backup"
+```
+
+---
+
+## Switching Between Multiple Databases
+
+### Option A: Multiple Config Files
+
+Create separate config files:
+
+**db-config-prod.ps1**
+```powershell
+$DB_NAME = "jellyfin"
+# ... rest of config
+```
+
+**db-config-test.ps1**
+```powershell
+$DB_NAME = "jellyfin_testsdata"
+# ... rest of config
+```
+
+**Usage:**
+```powershell
+# Use production
+. .\db-config-prod.ps1
+
+# Use testing
+. .\db-config-test.ps1
+```
+
+### Option B: Profile Selection
+
+Add to `db-config.ps1`:
+
+```powershell
+# At the top of db-config.ps1
+param(
+    [ValidateSet("prod", "test", "dev")]
+    [string]$Profile = "test"
+)
+
+switch ($Profile) {
+    "prod" { $DB_NAME = "jellyfin" }
+    "test" { $DB_NAME = "jellyfin_testsdata" }
+    "dev"  { $DB_NAME = "jellyfin_dev" }
+}
+```
+
+**Usage:**
+```powershell
+# Use production
+. .\db-config.ps1 -Profile prod
+
+# Use testing
+. .\db-config.ps1 -Profile test
+```
+
+---
+
+## Connection String for .NET/Jellyfin
+
+If you need to update Jellyfin's connection string:
+
+**Location**: `config/system.xml` or `config/network.xml`
+
+```xml
+<PostgresConnectionString>
+  Host=localhost;
+  Port=5432;
+  Database=jellyfin_testsdata;  <!-- Change this -->
+  Username=jellyfin;
+  Password=your_password
+</PostgresConnectionString>
+```
+
+Or environment variable:
+```powershell
+$env:ConnectionStrings__DefaultConnection = "Host=localhost;Port=5432;Database=jellyfin_testsdata;Username=jellyfin;Password=..."
+```
+
+---
+
+## Verify Connection
+
+Check which database you're connected to:
+
+```powershell
+# Load config
+. .\db-config.ps1
+
+# Test connection
+& "C:\Program Files\PostgreSQL\18\bin\psql.exe" -U $DB_USER -d $DB_NAME -c "SELECT current_database();"
+```
+
+**Expected output:**
+```
+ current_database
+------------------
+ jellyfin_testsdata
+(1 row)
+```
+
+---
+
+## Quick Examples
+
+### Run diagnostics against test database
+```powershell
+# Edit db-config.ps1 to use jellyfin_testsdata
+. .\db-config.ps1
+.\db-quick.ps1  # Select option 1
+```
+
+### Check indexes on production database
+```powershell
+# Edit db-config.ps1 to use jellyfin
+. .\db-config.ps1
+.\db-quick.ps1  # Select option 2
+```
+
+### Apply indexes to specific database
+```powershell
+# Edit db-config.ps1
+$DB_NAME = "my_database"
+
+# Run
+.\Add-All-Indexes.bat
+```
+
+---
+
+## Troubleshooting
+
+### "database does not exist"
+```powershell
+# List available databases
+& "C:\Program Files\PostgreSQL\18\bin\psql.exe" -U jellyfin -l
+
+# Create database if needed
+& "C:\Program Files\PostgreSQL\18\bin\psql.exe" -U jellyfin -d postgres -c "CREATE DATABASE jellyfin_testsdata;"
+```
+
+### "password authentication failed"
+Update the username in `db-config.ps1`:
+```powershell
+$DB_USER = "your_username"
+```
+
+### Changes not taking effect
+Reload the configuration:
+```powershell
+. .\db-config.ps1
+```
+
+---
+
+## Summary
+
+**To change database:**
+1. Edit `db-config.ps1`
+2. Change `$DB_NAME = "your_database"`
+3. Save
+4. Run `. .\db-config.ps1`
+5. Done! ✅
+
+**All scripts will now use the new database!** 🎉
+
+---
+
+## Quick Reference Card
+
+```powershell
+# Switch to testing database
+# 1. Edit db-config.ps1:
+$DB_NAME = "jellyfin_testsdata"
+
+# 2. Reload:
+. .\db-config.ps1
+
+# 3. Verify:
+Write-Host $DB_NAME
+
+# 4. Use:
+.\db-quick.ps1
+```
+
+That's it! 🚀