@libredb/studio 0.9.7

package/docs/backlogs/005-QUERY_PLAYGROUND.md

@@ -0,0 +1,352 @@
+# Query Playground (Sandbox Mode)
+
+## Overview
+A safe environment to test dangerous queries (DELETE, UPDATE, DROP) without affecting production data. Preview the impact before committing.
+
+## Problem Statement
+Database users face anxiety when running destructive queries:
+- "Will this DELETE remove the right rows?"
+- "How many records will this UPDATE affect?"
+- "What if I make a mistake with this DROP TABLE?"
+
+Current mitigations are inadequate:
+- Running on a test database (data may differ)
+- Adding WHERE 1=0 to test syntax (doesn't show impact)
+- Manual review (error-prone, time-consuming)
+- Hoping for the best (risky)
+
+## Proposed Solution
+A sandbox mode that:
+1. Analyzes destructive queries before execution
+2. Shows exactly what will be affected
+3. Provides one-click rollback capability
+4. Allows "dry run" execution
+
+## Features
+
+### 1. Query Impact Preview
+```
+┌─────────────────────────────────────────────────────────────┐
+│ ⚠️ DESTRUCTIVE QUERY DETECTED                               │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ DELETE FROM orders WHERE status = 'cancelled'              │
+│                                                             │
+│ Impact Analysis:                                            │
+│ ┌─────────────────────────────────────────────────────────┐ │
+│ │ 🗑️  847 rows will be deleted                            │ │
+│ │ 📊 This is 12% of the orders table                      │ │
+│ │ 🔗 0 foreign key constraints affected                   │ │
+│ │ 💾 Estimated freed space: 2.3 MB                        │ │
+│ └─────────────────────────────────────────────────────────┘ │
+│                                                             │
+│ Preview of affected rows (first 10):                        │
+│ ┌────┬──────────┬────────────┬─────────────┐               │
+│ │ id │ customer │ amount     │ created_at  │               │
+│ ├────┼──────────┼────────────┼─────────────┤               │
+│ │ 42 │ John D.  │ $150.00    │ 2024-01-15  │               │
+│ │ 78 │ Jane S.  │ $89.50     │ 2024-02-20  │               │
+│ │... │ ...      │ ...        │ ...         │               │
+│ └────┴──────────┴────────────┴─────────────┘               │
+│                                                             │
+│ [View All 847 Rows]                                         │
+│                                                             │
+│        [Cancel]  [Execute with Rollback]  [Execute]         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2. Sandbox Execution Mode
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 🧪 SANDBOX MODE                              [Exit Sandbox] │
+├─────────────────────────────────────────────────────────────┤
+│ All changes are temporary and can be rolled back            │
+│                                                             │
+│ Pending Changes:                                            │
+│ • DELETE orders (847 rows) - 2 min ago                     │
+│ • UPDATE users SET status='inactive' (23 rows) - 1 min ago │
+│                                                             │
+│                         [Rollback All]  [Commit All]        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3. Transaction Wrapper
+Behind the scenes:
+```sql
+BEGIN TRANSACTION;
+-- User's dangerous query runs here
+-- Results shown to user
+-- Wait for user decision
+COMMIT;   -- If user confirms
+ROLLBACK; -- If user cancels
+```
+
+### 4. Visual Diff for UPDATE
+```
+┌─────────────────────────────────────────────────────────────┐
+│ UPDATE users SET email = LOWER(email) WHERE id < 100       │
+├─────────────────────────────────────────────────────────────┤
+│ 23 rows will be modified:                                   │
+│                                                             │
+│ id │ email (before)          │ email (after)               │
+│ ───┼─────────────────────────┼───────────────────────────  │
+│ 1  │ John@Example.COM        │ john@example.com            │
+│ 2  │ JANE@Test.Org           │ jane@test.org               │
+│ 5  │ Bob.Smith@COMPANY.com   │ bob.smith@company.com       │
+│ ...│                         │                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5. Undo History
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 📜 Undo History                                             │
+├─────────────────────────────────────────────────────────────┤
+│ ↩️  DELETE orders (847 rows) - Committed 5 min ago    [Undo]│
+│ ↩️  UPDATE users (23 rows) - Committed 3 min ago      [Undo]│
+│ ✓  INSERT products (5 rows) - Committed 1 min ago          │
+└─────────────────────────────────────────────────────────────┘
+```
+- Keep backup data for recent destructive operations
+- One-click restore from backup
+- Configurable retention period
+
+### 6. Query Safety Checks
+Before execution, analyze for:
+- Missing WHERE clause: `DELETE FROM users` → "No WHERE clause! This will delete ALL rows"
+- Overly broad conditions: `WHERE 1=1` → "Condition matches all rows"
+- Cascade effects: Foreign key deletions
+- Index impact: Updating indexed columns
+- Lock warnings: Table-level locks on large operations
+
+## Technical Considerations
+
+### Implementation Strategy
+
+#### Option A: Transaction Wrapping
+```typescript
+async function sandboxExecute(query: string, connection: Connection) {
+  await connection.query('BEGIN');
+
+  try {
+    // Get affected rows count first
+    const countResult = await analyzeImpact(query, connection);
+
+    // Execute and capture changes
+    const result = await connection.query(query);
+
+    // Return result without committing
+    return {
+      result,
+      impact: countResult,
+      rollback: () => connection.query('ROLLBACK'),
+      commit: () => connection.query('COMMIT'),
+    };
+  } catch (error) {
+    await connection.query('ROLLBACK');
+    throw error;
+  }
+}
+```
+
+#### Option B: Clone & Execute
+For very destructive operations:
+1. Create temporary table copy
+2. Execute on copy
+3. Show diff
+4. If confirmed, execute on real table
+
+#### Option C: Query Rewriting
+```sql
+-- Original
+DELETE FROM orders WHERE status = 'cancelled'
+
+-- Rewritten for preview
+SELECT * FROM orders WHERE status = 'cancelled'
+-- Shows what would be deleted
+```
+
+### Impact Analysis API
+```typescript
+interface ImpactAnalysis {
+  queryType: 'DELETE' | 'UPDATE' | 'DROP' | 'TRUNCATE' | 'ALTER';
+  affectedRows: number;
+  affectedTables: string[];
+  cascadeEffects: CascadeEffect[];
+  estimatedDuration: number;
+  warnings: Warning[];
+  previewData: any[];
+}
+
+async function analyzeQuery(
+  query: string,
+  connection: Connection
+): Promise<ImpactAnalysis>;
+```
+
+### Undo Implementation
+```typescript
+interface UndoRecord {
+  id: string;
+  timestamp: Date;
+  queryType: string;
+  table: string;
+  affectedRows: number;
+  backupData: any[];  // Snapshot of affected rows
+  undoQuery: string;  // Generated reverse query
+}
+```
+
+For DELETE:
+- Store deleted rows in undo buffer
+- Generate INSERT statements for undo
+
+For UPDATE:
+- Store before-values
+- Generate UPDATE with original values for undo
+
+### API Endpoints
+```
+POST /api/db/sandbox/analyze
+  → Returns impact analysis
+
+POST /api/db/sandbox/execute
+  → Executes in transaction, returns preview
+
+POST /api/db/sandbox/commit
+  → Commits pending transaction
+
+POST /api/db/sandbox/rollback
+  → Rolls back pending transaction
+
+GET /api/db/sandbox/undo-history
+  → Returns undo-able operations
+
+POST /api/db/sandbox/undo/:id
+  → Undoes a specific operation
+```
+
+## UI Components
+
+### New Components
+- `SandboxBanner.tsx` - Top banner showing sandbox mode status
+- `ImpactPreview.tsx` - Shows affected rows preview
+- `DiffView.tsx` - Before/after comparison for UPDATE
+- `UndoHistory.tsx` - List of undo-able operations
+- `SafetyWarnings.tsx` - Displays query safety issues
+- `ConfirmationModal.tsx` - Confirm destructive action
+
+### Editor Integration
+- Detect destructive keywords (DELETE, UPDATE, DROP, TRUNCATE, ALTER)
+- Show warning icon in gutter
+- Auto-trigger sandbox mode for dangerous queries
+- Toggle: "Always use sandbox for destructive queries"
+
+## User Flow
+
+### Automatic Sandbox (Default)
+```
+1. User writes DELETE/UPDATE query
+   ↓
+2. Clicks "Run" (or Cmd+Enter)
+   ↓
+3. System detects destructive query
+   ↓
+4. Impact analysis runs automatically
+   ↓
+5. Preview modal shows affected rows
+   ↓
+6. User reviews and decides:
+   - Cancel: Nothing happens
+   - Execute with Rollback: Runs in sandbox
+   - Execute: Runs directly (if confident)
+```
+
+### Manual Sandbox Mode
+```
+1. User enables "Sandbox Mode" toggle
+   ↓
+2. All queries run in transaction
+   ↓
+3. Changes accumulate without committing
+   ↓
+4. User can preview, test, experiment
+   ↓
+5. Finally: Commit All or Rollback All
+```
+
+## Safety Levels
+
+### Level 1: Warning Only
+- Show warning banner
+- User can proceed immediately
+- For: UPDATE with WHERE clause
+
+### Level 2: Preview Required
+- Must view affected rows before executing
+- For: DELETE with WHERE clause
+
+### Level 3: Confirmation Required
+- Type table name to confirm
+- For: DROP TABLE, TRUNCATE
+
+### Level 4: Blocked
+- Cannot execute in UI
+- For: DROP DATABASE
+- Must use CLI with explicit flag
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ ⛔ DROP TABLE users                                         │
+├─────────────────────────────────────────────────────────────┤
+│ This action cannot be undone.                               │
+│                                                             │
+│ Type "users" to confirm:                                    │
+│ ┌─────────────────────────────────────────────────────────┐ │
+│ │                                                         │ │
+│ └─────────────────────────────────────────────────────────┘ │
+│                                                             │
+│                                    [Cancel]  [Drop Table]   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Configuration Options
+- Sandbox mode: Auto (destructive only) / Always / Never
+- Undo history retention: 1 hour / 1 day / 1 week
+- Preview row limit: 10 / 50 / 100
+- Safety level overrides per table
+- Excluded tables (never sandbox)
+
+## Edge Cases
+- Long-running transactions (timeout handling)
+- Concurrent modifications (lock detection)
+- Very large affected sets (sampling for preview)
+- Queries with side effects (triggers, functions)
+- Read replica connections (write detection)
+
+## Acceptance Criteria
+- [ ] Destructive queries trigger impact preview
+- [ ] Affected row count is shown before execution
+- [ ] Preview shows sample of affected rows
+- [ ] UPDATE shows before/after diff
+- [ ] User can cancel, execute, or execute with rollback
+- [ ] Sandbox mode allows multiple operations before commit
+- [ ] Undo history allows reverting recent operations
+- [ ] Safety warnings appear for risky patterns
+- [ ] Works with PostgreSQL, MySQL, SQLite
+
+## Dependencies
+- Transaction support in database providers
+- Query parsing for type detection
+- Backup/restore functionality for undo
+
+## Estimated Effort
+Medium-High complexity
+
+## Priority
+P1 - Safety critical
+
+## Related Features
+- Query History (existing)
+- Inline Data Editing (planned - will use sandbox)
+- Query Time Machine (planned - can use for comparison)