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

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

# 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

# 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

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

   docker-compose up -d backend
   

2. Check logs to verify schema creation:

   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

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

curl -X POST "http://localhost:3001/api/cache/sync" \
  -H "Authorization: Bearer YOUR_TOKEN"

For SQLite (if using SQLite)

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

# 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

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

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

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

Database Connection Issues

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

# 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 - Detailed PostgreSQL reset guide
• Local Development Setup - Initial setup guide
• Database Schema - Schema documentation