crowd-funder-for-time-pwa/docs/database-clearing.md

Database Clearing for Development

Author: Matthew Raymer
Date: 2025-07-11
Status: ACTIVE - Production Ready

Overview

TimeSafari provides a simple script-based approach to clear the database for development purposes. This avoids the complexity of programmatic database clearing and provides reliable, platform-specific solutions.

Quick Start

# Run the interactive database clearing script
./scripts/clear-database.sh

# Then restart your development server
npm run build:electron:dev  # For Electron
npm run build:web:dev       # For Web

Platform-Specific Approaches

Electron (Desktop App)

The script automatically detects your platform and clears the SQLite database files:

• Linux: ~/.config/TimeSafari/
• macOS: ~/Library/Application Support/TimeSafari/
• Windows: %APPDATA%\TimeSafari

Web Browser

For web browsers, the script provides two approaches:

1. Custom Data Directory (Recommended)

Create an isolated browser profile for development:

# Create isolated profile
mkdir ~/timesafari-dev-data

# Start browser with custom profile
google-chrome --user-data-dir=~/timesafari-dev-data

# Clear when needed
rm -rf ~/timesafari-dev-data

2. Manual Browser Clearing

Use browser DevTools to clear IndexedDB:

1. Open Developer Tools (F12)
2. Go to Application/Storage tab
3. Find 'IndexedDB' section
4. Delete 'TimeSafari' database
5. Refresh the page

Why Script-Based Approach?

Simplicity

• No complex programmatic database clearing
• No browser storage complications
• No race conditions or permission issues

Reliability

• Direct file system access for Electron
• Isolated browser profiles for web
• Clear, predictable behavior

Safety

• Interactive script guides users
• Platform-specific instructions
• Only clears TimeSafari data

Manual Commands

If you prefer manual commands:

Electron

# Linux
rm -rf ~/.config/TimeSafari/*

# macOS
rm -rf ~/Library/Application\ Support/TimeSafari/*

# Windows
rmdir /s /q %APPDATA%\TimeSafari

Web Browser

# Create and use isolated profile
mkdir ~/timesafari-dev-data
google-chrome --user-data-dir=~/timesafari-dev-data

# Clear when needed
rm -rf ~/timesafari-dev-data

Best Practices

1. Stop the development server before clearing
2. Use isolated browser profiles for web development
3. Restart the development server after clearing
4. Backup important data before clearing
5. Use the script for consistent behavior

Troubleshooting

Script Not Found

# Make sure script is executable
chmod +x scripts/clear-database.sh

# Run from project root
./scripts/clear-database.sh

Permission Errors

# Check file permissions
ls -la ~/.config/TimeSafari/

# Use sudo if needed (rare)
sudo rm -rf ~/.config/TimeSafari/*

Browser Profile Issues

# Ensure browser is completely closed
pkill -f chrome
pkill -f firefox

# Then clear profile
rm -rf ~/timesafari-dev-data

---

Last Updated: 2025-07-11
Version: 1.0.3-beta
Status: Production Ready