cmdb-insight/docs/DATABASE-RESET-GUIDE.md

# Complete Database Reset Guide

This guide explains how to force a complete reset of the database so that the cache/data is built completely from scratch.

## Overview

There are three main approaches to resetting the database:

1. **API-based reset** (Recommended) - Clears cache via API and triggers rebuild
2. **Database volume reset** - Completely removes PostgreSQL volume and recreates
3. **Manual SQL reset** - Direct database commands to clear all data

## Option 1: API-Based Reset (Recommended)

This is the cleanest approach as it uses the application's built-in endpoints.

### Using the Script

```bash
# Run the automated reset script
./scripts/reset-and-rebuild.sh
```

The script will:
1. Clear all cached data via `DELETE /api/cache/clear`
2. Trigger a full sync via `POST /api/cache/sync`
3. Monitor the process

### Manual API Calls

If you prefer to do it manually:

```bash
# Set your backend URL
BACKEND_URL="http://localhost:3001"
API_URL="$BACKEND_URL/api"

# Step 1: Clear all cache
curl -X DELETE "$API_URL/cache/clear" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Step 2: Trigger full sync
curl -X POST "$API_URL/cache/sync" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Note:** You need to be authenticated. Either:
- Use a valid JWT token from your session
- Or authenticate via the UI first and copy the token from browser dev tools

### Via the UI

1. Navigate to **Settings → Cache Management**
2. Click **"Clear All Cache"** button
3. Click **"Full Sync"** button
4. Monitor progress in the same page

## Option 2: Database Volume Reset (Nuclear Option)

This completely removes the PostgreSQL database and recreates it from scratch.

### Using the Reset Script

```bash
# Run the PostgreSQL reset script
./scripts/reset-postgres.sh
```

This will:
1. Stop containers
2. Remove the PostgreSQL volume (deletes ALL data)
3. Restart PostgreSQL with a fresh database
4. Wait for PostgreSQL to be ready

**⚠️ Warning:** This deletes ALL data including:
- All cached CMDB objects
- All relations
- All attribute values
- Schema discovery cache
- Sync metadata

### Manual Volume Reset

```bash
# Step 1: Stop containers
docker-compose down

# Step 2: Remove PostgreSQL volume
docker volume ls | grep postgres
docker volume rm cmdb-insight_postgres_data

# Step 3: Start PostgreSQL again
docker-compose up -d postgres

# Step 4: Wait for PostgreSQL to be ready
docker-compose exec postgres pg_isready -U cmdb
```

### After Volume Reset

After resetting the volume, you need to:

1. **Start the backend** - The schema will be created automatically:
   ```bash
   docker-compose up -d backend
   ```

2. **Check logs** to verify schema creation:
   ```bash
   docker-compose logs -f backend
   ```
   
   You should see:
   - `NormalizedCacheStore: Database schema initialized`
   - `SchemaDiscovery: Schema discovery complete`

3. **Trigger a full sync** to rebuild data:
   - Via UI: Settings → Cache Management → Full Sync
   - Via API: `POST /api/cache/sync`
   - Or use the reset script: `./scripts/reset-and-rebuild.sh`

## Option 3: Manual SQL Reset

If you want to clear data but keep the database structure:

### For PostgreSQL

```bash
# Connect to database
docker-compose exec postgres psql -U cmdb -d cmdb_cache

# Clear all data (keeps schema)
TRUNCATE TABLE attribute_values CASCADE;
TRUNCATE TABLE object_relations CASCADE;
TRUNCATE TABLE objects CASCADE;
TRUNCATE TABLE sync_metadata CASCADE;
TRUNCATE TABLE schema_cache CASCADE;
TRUNCATE TABLE schema_mappings CASCADE;

# Exit
\q
```

Then trigger a full sync:
```bash
curl -X POST "http://localhost:3001/api/cache/sync" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### For SQLite (if using SQLite)

```bash
# Connect to backend container
docker-compose exec backend sh

# Clear all data
sqlite3 /app/data/cmdb-cache.db <<EOF
DELETE FROM attribute_values;
DELETE FROM object_relations;
DELETE FROM objects;
DELETE FROM sync_metadata;
DELETE FROM schema_cache;
DELETE FROM schema_mappings;
VACUUM;
EOF
```

## What Gets Reset?

### Cleared by `DELETE /api/cache/clear`:
- ✅ All cached CMDB objects (`objects` table)
- ✅ All attribute values (`attribute_values` table)
- ✅ All relations (`object_relations` table)
- ❌ Schema cache (kept for faster schema discovery)
- ❌ Schema mappings (kept for configuration)
- ❌ User data and classifications (separate database)

### Cleared by Volume Reset:
- ✅ Everything above
- ✅ Schema cache
- ✅ Schema mappings
- ✅ All database structure (recreated on next start)

## Verification

After reset, verify the database is empty and ready for rebuild:

```bash
# Check object counts (should be 0)
docker-compose exec postgres psql -U cmdb -d cmdb_cache -c "
  SELECT 
    (SELECT COUNT(*) FROM objects) as objects,
    (SELECT COUNT(*) FROM attribute_values) as attributes,
    (SELECT COUNT(*) FROM object_relations) as relations;
"

# Check sync status
curl "$BACKEND_URL/api/cache/status" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Troubleshooting

### Authentication Issues

If you get authentication errors:

1. **Get a token from the UI:**
   - Log in via the UI
   - Open browser dev tools → Network tab
   - Find any API request → Copy the `Authorization` header value
   - Use it in your curl commands

2. **Or use the UI directly:**
   - Navigate to Settings → Cache Management
   - Use the buttons there (no token needed)

### Backend Not Running

```bash
# Check if backend is running
docker-compose ps backend

# Start backend if needed
docker-compose up -d backend

# Check logs
docker-compose logs -f backend
```

### Sync Not Starting

Check that Jira credentials are configured:

```bash
# Check environment variables
docker-compose exec backend env | grep JIRA

# Required:
# - JIRA_HOST
# - JIRA_SERVICE_ACCOUNT_TOKEN (for sync operations)
```

### Database Connection Issues

```bash
# Test PostgreSQL connection
docker-compose exec postgres pg_isready -U cmdb

# Check database exists
docker-compose exec postgres psql -U cmdb -l

# Check connection from backend
docker-compose exec backend node -e "
  const { createDatabaseAdapter } = require('./src/services/database/factory.js');
  const db = createDatabaseAdapter();
  db.query('SELECT 1').then(() => console.log('OK')).catch(e => console.error(e));
"
```

## Complete Reset Workflow

For a complete "green field" reset:

```bash
# 1. Stop everything
docker-compose down

# 2. Remove PostgreSQL volume (nuclear option)
docker volume rm cmdb-insight_postgres_data

# 3. Start PostgreSQL
docker-compose up -d postgres

# 4. Wait for PostgreSQL
sleep 5
docker-compose exec postgres pg_isready -U cmdb

# 5. Start backend (creates schema automatically)
docker-compose up -d backend

# 6. Wait for backend to initialize
sleep 10
docker-compose logs backend | grep "initialization complete"

# 7. Clear cache and trigger sync (via script)
./scripts/reset-and-rebuild.sh

# OR manually via API
curl -X DELETE "http://localhost:3001/api/cache/clear" \
  -H "Authorization: Bearer YOUR_TOKEN"
curl -X POST "http://localhost:3001/api/cache/sync" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Quick Reference

| Method | Speed | Data Loss | Schema Loss | Recommended For |
|--------|-------|-----------|-------------|-----------------|
| API Clear + Sync | Fast | Cache only | No | Regular resets |
| Volume Reset | Medium | Everything | Yes | Complete rebuild |
| SQL TRUNCATE | Fast | Cache only | No | Quick clear |

## Related Documentation

- [Local PostgreSQL Reset](./LOCAL-POSTGRES-RESET.md) - Detailed PostgreSQL reset guide
- [Local Development Setup](./LOCAL-DEVELOPMENT-SETUP.md) - Initial setup guide
- [Database Schema](./DATABASE-DRIVEN-SCHEMA-IMPLEMENTATION-PLAN.md) - Schema documentation