@libredb/studio 0.9.7 → 0.9.12

package/docs/backlogs/000-PLATFORM_DATA_SYNC_DATABASE.md

@@ -1,360 +0,0 @@
-# LibreDB Studio - Platform Architecture
-
-> **Status:** Backlog  
-> **Date:** 2025-12-25  
-> **Priority:** High
-
----
-
-## 1. Operating Modes
-
-The system can operate in **two modes**. It works flawlessly in both scenarios:
-
-### 1.1 Browser-Only Mode (Default)
-
-```
-┌─────────────────────────────────────────┐
-│  PGlite (WASM PostgreSQL)               │
-│         │                               │
-│         ▼                               │
-│  IndexedDB (browser)                    │
-│                                         │
-│  ✅ No external DB required             │
-│  ✅ Zero-config, works immediately      │
-│  ✅ Single browser usage                │
-└─────────────────────────────────────────┘
-```
-
-- Platform data stays **only in the browser**
-- No external database **required**
-- No installation or configuration **needed**
-- Data is **lost** if browser is cleared
-
-### 1.2 Database Sync Mode (Optional)
-
-```
-┌─────────────────────────────────────────┐
-│  PGlite (WASM PostgreSQL)               │
-│         │                               │
-│         ▼                               │
-│  IndexedDB (browser)                    │
-│         │                               │
-│         ▼ (sync enabled)                │
-│  ElectricSQL ──▶ External PostgreSQL    │
-│                                         │
-│  ✅ Data in both browser and DB         │
-│  ✅ Access from multiple devices        │
-│  ✅ Recoverable even if browser cleared │
-└─────────────────────────────────────────┘
-```
-
-- Platform data is stored **first in browser**, then **synced to external DB**
-- User enables it if desired, **not mandatory**
-- **Continues to work** offline
-- Data is **persistent** and **shareable**
-
-### 1.3 Mode Selection
-
-| Parameter | Value | Behavior |
-|-----------|-------|----------|
-| `SYNC_MODE` or UI setting | `browser` (default) | Browser only |
-| `SYNC_MODE` or UI setting | `database` | Browser + sync |
-
-```typescript
-// Example usage
-if (syncConfig.enabled && syncConfig.databaseUrl) {
-  await startSync(); // Start sync to external DB
-}
-// else: PGlite only, no errors
-```
-
----
-
-## 2. Requirements Analysis
-
-### 2.1 Core Requirements
-
-| # | Requirement | Description |
-|---|-------------|-------------|
-| 1 | **User/Role Management** | Create users, assign roles (admin, user, viewer) |
-| 2 | **Query Logging** | User-based query history (query, row count, execution time, status) |
-| 3 | **Saved Queries** | Allow users to save and edit their queries |
-| 4 | **Account Management** | Profile, preferences, account settings |
-| 5 | **Platform Structure** | Future collaborative workspace and sharing features |
-
-### 2.2 Technical Requirements
-
-| Requirement | Description |
-|-------------|-------------|
-| Zero-config startup | Must work without any installation |
-| Database necessity | Persistent storage needed for users, query logs, saved queries |
-| Optional persistence | Users who want can sync their data to external DB |
-| Minimal complexity | Should not significantly change existing architecture |
-
-### 2.3 Current Problems
-
-- LocalStorage 5-10MB limit
-- No user-based separation
-- No cross-device data sharing
-- Data loss when browser is cleared
-
----
-
-## 3. Solution: PGlite + ElectricSQL
-
-### 3.1 Vision
-
-```
-Default:   PGlite in browser (WASM PostgreSQL) → Persistent in IndexedDB
-Optional:  If user wants → Sync to external PostgreSQL (ElectricSQL)
-```
-
-### 3.2 Why This Solution?
-
-| Alternative | Problem |
-|-------------|---------|
-| LocalStorage | 5-10MB limit, no SQL |
-| IndexedDB (raw) | NoSQL, complex queries are difficult |
-| Mandatory External DB | No zero-config, requires installation |
-| **PGlite** | ✅ Real PostgreSQL, 100GB+ limit, zero-config |
-
-### 3.3 Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        Browser                               │
-│                                                              │
-│   React Components                                           │
-│         │                                                    │
-│         ▼                                                    │
-│   storage.ts (API unchanged)                                 │
-│         │                                                    │
-│         ▼                                                    │
-│   PGlite (WASM PostgreSQL)                                   │
-│         │                                                    │
-│         ▼                                                    │
-│   IndexedDB (100GB+ limit)                                   │
-│         │                                                    │
-│         ▼ (optional)                                         │
-│   ElectricSQL Sync ──────────▶ External PostgreSQL           │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Important:** The existing `storage.ts` API is preserved, only the backend changes.
-
----
-
-## 4. Database Schema
-
-### 4.1 Tables
-
-```sql
--- Users
-CREATE TABLE users (
-    id TEXT PRIMARY KEY,
-    username TEXT UNIQUE NOT NULL,
-    email TEXT,
-    role TEXT DEFAULT 'user',  -- admin, user, viewer
-    preferences JSONB DEFAULT '{}',
-    created_at TEXT DEFAULT (datetime('now')),
-    updated_at TEXT DEFAULT (datetime('now'))
-);
-
--- Connections (passwords excluded - stay in localStorage)
-CREATE TABLE connections (
-    id TEXT PRIMARY KEY,
-    user_id TEXT REFERENCES users(id),
-    name TEXT NOT NULL,
-    type TEXT NOT NULL,  -- postgres, mysql, sqlite, mongodb
-    host TEXT,
-    port INTEGER,
-    database_name TEXT,
-    username TEXT,
-    created_at TEXT DEFAULT (datetime('now'))
-);
-
--- Query History
-CREATE TABLE query_logs (
-    id TEXT PRIMARY KEY,
-    user_id TEXT REFERENCES users(id),
-    connection_id TEXT,
-    connection_name TEXT,
-    tab_name TEXT,
-    query TEXT NOT NULL,
-    row_count INTEGER,
-    execution_time_ms INTEGER,
-    status TEXT NOT NULL,  -- success, error
-    error_message TEXT,
-    executed_at TEXT DEFAULT (datetime('now'))
-);
-
--- Saved Queries
-CREATE TABLE saved_queries (
-    id TEXT PRIMARY KEY,
-    user_id TEXT REFERENCES users(id),
-    name TEXT NOT NULL,
-    description TEXT,
-    query TEXT NOT NULL,
-    connection_type TEXT,
-    tags TEXT,  -- JSON array as text
-    created_at TEXT DEFAULT (datetime('now')),
-    updated_at TEXT DEFAULT (datetime('now'))
-);
-
--- Sync Config (optional)
-CREATE TABLE sync_config (
-    id TEXT PRIMARY KEY,
-    sync_enabled INTEGER DEFAULT 0,
-    sync_url TEXT,
-    last_sync_at TEXT
-);
-```
-
----
-
-## 5. Implementation Plan
-
-### 5.1 File Structure (Minimal)
-
-```
-src/lib/
-├── storage.ts           # Existing API preserved, PGlite backend
-├── pglite/
-│   ├── client.ts        # PGlite singleton
-│   ├── migrations.ts    # Schema migrations
-│   └── sync.ts          # ElectricSQL integration (Phase 2)
-└── crypto/
-    └── vault.ts         # Password encryption (localStorage)
-```
-
-### 5.2 Phase 1: PGlite Integration (1 week)
-
-**Goal:** LocalStorage → PGlite migration
-
-| Task | Description |
-|------|-------------|
-| PGlite client | Singleton instance, lazy loading |
-| Migrations | Initial schema, version tracking |
-| storage.ts refactor | Same API, PGlite backend |
-| Data migration | Migrate existing localStorage data to PGlite |
-
-**storage.ts change:**
-
-```typescript
-// BEFORE
-export const storage = {
-  getHistory: () => {
-    const stored = localStorage.getItem(HISTORY_KEY);
-    return JSON.parse(stored);
-  }
-};
-
-// AFTER
-export const storage = {
-  getHistory: async () => {
-    const db = await getPGlite();
-    const result = await db.query('SELECT * FROM query_logs ORDER BY executed_at DESC');
-    return result.rows;
-  }
-};
-```
-
-### 5.3 Phase 2: User Management (1 week)
-
-**Goal:** Real user system
-
-| Task | Description |
-|------|-------------|
-| User CRUD | Create, read, update users |
-| Auth integration | Connect with existing JWT system |
-| Role-based queries | User-based data filtering |
-| Settings UI | User preferences page |
-
-### 5.4 Phase 3: ElectricSQL Sync (1 week)
-
-**Goal:** Optional external sync
-
-| Task | Description |
-|------|-------------|
-| Electric client | Sync client setup |
-| Sync UI | Connection form, status indicator |
-| Conflict handling | Last-write-wins |
-
----
-
-## 6. API Compatibility
-
-**Existing API is preserved, only becomes async:**
-
-```typescript
-// Current usage (Studio.tsx)
-storage.addToHistory(item);
-const history = storage.getHistory();
-
-// New usage (minimal change)
-await storage.addToHistory(item);
-const history = await storage.getHistory();
-```
-
-**Studio.tsx changes are minimal:**
-- `storage.xxx()` → `await storage.xxx()`
-- Async wrapper inside useEffect
-
----
-
-## 7. Security
-
-| Data | Storage | Sync |
-|------|---------|------|
-| Passwords | localStorage (encrypted) | ❌ Never |
-| User information | PGlite | ✅ Optional |
-| Query history | PGlite | ✅ Optional |
-| Saved queries | PGlite | ✅ Optional |
-
----
-
-## 8. Dependencies
-
-```json
-{
-  "@electric-sql/pglite": "^0.2.x"
-}
-```
-
-**Note:** ElectricSQL sync client will be added in Phase 3.
-
----
-
-## 9. Timeline
-
-| Phase | Duration | Output |
-|-------|----------|--------|
-| Phase 1: PGlite | 5-7 days | LocalStorage → PGlite migration |
-| Phase 2: Users | 5-7 days | User management |
-| Phase 3: Sync | 5-7 days | Optional external sync |
-
-**Total:** ~3 weeks
-
----
-
-## 10. Summary
-
-```
-Requirement                →  Solution
-─────────────────────────────────────────────────
-User/Role Management       →  users table + role column
-Query Logging              →  query_logs table
-Saved Queries              →  saved_queries table
-Account Management         →  users.preferences JSONB
-Platform (future)          →  ElectricSQL sync
-Zero-config                →  PGlite (in-browser)
-Optional persistence       →  ElectricSQL → External PostgreSQL
-```
-
----
-
-## 11. References
-
-- [PGlite](https://pglite.dev/) - In-browser PostgreSQL
-- [ElectricSQL](https://electric-sql.com/) - Postgres sync

package/docs/backlogs/001-INLINE_DATA_EDITING.md

@@ -1,118 +0,0 @@
-# Inline Data Editing
-
-## Overview
-Enable direct data manipulation in the Results Grid without writing SQL queries manually.
-
-## Problem Statement
-Currently, users must write UPDATE, INSERT, or DELETE statements manually to modify data. This is time-consuming for quick fixes and requires SQL knowledge for simple operations.
-
-## Proposed Solution
-Add inline editing capabilities to the ResultsGrid component, allowing users to:
-- Edit cell values directly by double-clicking
-- Insert new rows
-- Delete existing rows
-- Review pending changes before committing
-
-## Features
-
-### 1. Cell Editing
-- Double-click on a cell to enter edit mode
-- Press Enter to confirm, Escape to cancel
-- Visual indicator for modified cells (highlight/border)
-- Type-aware input fields (text, number, date, boolean)
-
-### 2. Row Operations
-- "Add Row" button in toolbar
-- Row selection with checkbox
-- "Delete Selected" button with confirmation
-- Right-click context menu for row operations
-
-### 3. Change Tracking
-- Pending changes indicator (badge count)
-- Changes panel showing all modifications
-- Diff view: original value → new value
-- Undo individual changes
-
-### 4. Commit/Rollback
-- "Commit Changes" button - executes all pending changes
-- "Rollback" button - discards all pending changes
-- Transaction support (all-or-nothing)
-- Success/error feedback per operation
-
-### 5. Safety Features
-- Confirmation dialog for destructive operations
-- Primary key requirement for UPDATE/DELETE
-- Row count limit for bulk operations
-- Read-only mode toggle
-
-## Technical Considerations
-
-### Database Requirements
-- Table must have a PRIMARY KEY for UPDATE/DELETE
-- User must have appropriate permissions
-- Connection must support transactions
-
-### UI Components
-- Extend `ResultsGrid.tsx` with edit mode
-- New `PendingChanges` component
-- New `EditableCell` component
-- Toolbar additions
-
-### API Endpoints
-```
-POST /api/db/mutation
-{
-  connection: DatabaseConnection,
-  operations: [
-    { type: 'UPDATE', table: string, pk: object, changes: object },
-    { type: 'INSERT', table: string, values: object },
-    { type: 'DELETE', table: string, pk: object }
-  ]
-}
-```
-
-## UI Mockup
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ Results                                    [3 pending] [+]  │
-├─────────────────────────────────────────────────────────────┤
-│ ☐ │ id │ name        │ email              │ status   │     │
-├───┼────┼─────────────┼────────────────────┼──────────┼─────┤
-│ ☐ │ 1  │ John Doe    │ john@example.com   │ active   │     │
-│ ☑ │ 2  │ [Jane Doe]* │ jane@example.com   │ active   │ 🗑  │
-│ ☐ │ 3  │ Bob Smith   │ bob@example.com    │ inactive │     │
-│ + │ -- │ New row...  │ --                 │ --       │     │
-└─────────────────────────────────────────────────────────────┘
-│                              [Rollback] [Commit Changes]    │
-└─────────────────────────────────────────────────────────────┘
-
-* = modified cell (highlighted)
-```
-
-## Acceptance Criteria
-- [ ] User can double-click a cell to edit its value
-- [ ] Modified cells are visually distinct
-- [ ] User can add new rows to the result set
-- [ ] User can delete selected rows
-- [ ] Pending changes are tracked and displayed
-- [ ] User can commit all changes in a single transaction
-- [ ] User can rollback all pending changes
-- [ ] Confirmation dialog appears before destructive operations
-- [ ] Error handling with clear feedback
-- [ ] Works with PostgreSQL, MySQL, SQLite
-
-## Dependencies
-- Primary key detection from schema
-- Transaction support in database providers
-- Permission checking
-
-## Estimated Effort
-Medium-High complexity
-
-## Priority
-P2 - Nice to have
-
-## Related Issues
-- Query Results Export (existing)
-- Schema Explorer (existing)

package/docs/backlogs/002-DATA_IMPORT.md

@@ -1,215 +0,0 @@
-# Data Import
-
-## Overview
-Enable importing data from external files (CSV, JSON, Excel) into database tables.
-
-## Problem Statement
-Users currently have no way to bulk import data through the UI. They must either:
-- Write INSERT statements manually
-- Use external tools (psql COPY, mysql LOAD DATA)
-- Use command-line utilities
-
-This creates friction for common workflows like data migration, seeding test data, or importing spreadsheet data.
-
-## Proposed Solution
-Add a data import feature accessible from the Schema Explorer, allowing users to:
-- Upload files via drag & drop or file picker
-- Preview and validate data before import
-- Map file columns to table columns
-- Configure import options (batch size, error handling)
-- Execute import with progress tracking
-
-## Supported Formats
-
-### CSV
-- Delimiter detection (comma, semicolon, tab)
-- Header row option
-- Quote character handling
-- Encoding support (UTF-8, Latin-1)
-
-### JSON
-- Array of objects format
-- Nested object flattening (optional)
-- JSON Lines (.jsonl) support
-
-### Excel (.xlsx)
-- Sheet selection
-- Header row configuration
-- Date format handling
-
-## Features
-
-### 1. File Upload
-- Drag & drop zone
-- File picker button
-- File size limit (configurable, default 50MB)
-- Format auto-detection
-
-### 2. Data Preview
-- First 100 rows preview
-- Column type inference
-- Error/warning indicators
-- Row count display
-
-### 3. Column Mapping
-- Auto-mapping by column name
-- Manual mapping dropdown
-- Ignore column option
-- Type conversion warnings
-- Required field validation
-
-### 4. Import Options
-- Batch size (default: 1000 rows)
-- On error: Stop / Skip / Replace
-- Truncate table before import (with confirmation)
-- Dry run mode (validate only)
-
-### 5. Progress & Results
-- Progress bar with percentage
-- Rows processed / total
-- Success / error counts
-- Error log with row numbers
-- Cancel button
-
-## Technical Considerations
-
-### File Processing
-- Client-side parsing for preview (Papa Parse for CSV)
-- Server-side processing for large files
-- Streaming for memory efficiency
-- Chunked uploads for large files
-
-### API Endpoints
-```
-POST /api/db/import/preview
-{
-  connection: DatabaseConnection,
-  file: FormData,
-  options: { format, delimiter, hasHeader }
-}
-Response: { columns: [], preview: [], rowCount: number }
-
-POST /api/db/import/execute
-{
-  connection: DatabaseConnection,
-  table: string,
-  mapping: { fileColumn: tableColumn }[],
-  options: { batchSize, onError, truncate }
-}
-Response: { success: number, failed: number, errors: [] }
-```
-
-### Libraries
-- CSV: `papaparse` (client) + `csv-parse` (server)
-- Excel: `xlsx` or `exceljs`
-- JSON: Native parsing
-
-## UI Flow
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│                     Import Data to "users"                    │
-├──────────────────────────────────────────────────────────────┤
-│  Step 1: Upload File                                         │
-│  ┌────────────────────────────────────────────────────────┐  │
-│  │                                                        │  │
-│  │     📁 Drag & drop your file here                     │  │
-│  │        or click to browse                              │  │
-│  │                                                        │  │
-│  │     Supported: CSV, JSON, Excel (.xlsx)               │  │
-│  └────────────────────────────────────────────────────────┘  │
-└──────────────────────────────────────────────────────────────┘
-
-┌──────────────────────────────────────────────────────────────┐
-│  Step 2: Preview & Map Columns                               │
-├──────────────────────────────────────────────────────────────┤
-│  File: users_export.csv (1,234 rows)                         │
-│                                                              │
-│  Column Mapping:                                             │
-│  ┌─────────────────┬─────────────────┬──────────────────┐   │
-│  │ File Column     │ Table Column    │ Status           │   │
-│  ├─────────────────┼─────────────────┼──────────────────┤   │
-│  │ name            │ [name ▼]        │ ✓ Mapped         │   │
-│  │ email           │ [email ▼]       │ ✓ Mapped         │   │
-│  │ age             │ [age ▼]         │ ⚠ Type mismatch  │   │
-│  │ created         │ [-- Ignore --]  │ Skipped          │   │
-│  └─────────────────┴─────────────────┴──────────────────┘   │
-│                                                              │
-│  Preview (first 5 rows):                                     │
-│  ┌────────────────┬────────────────┬─────┐                  │
-│  │ name           │ email          │ age │                  │
-│  ├────────────────┼────────────────┼─────┤                  │
-│  │ John Doe       │ john@test.com  │ 25  │                  │
-│  │ Jane Smith     │ jane@test.com  │ 30  │                  │
-│  └────────────────┴────────────────┴─────┘                  │
-└──────────────────────────────────────────────────────────────┘
-
-┌──────────────────────────────────────────────────────────────┐
-│  Step 3: Import Options                                      │
-├──────────────────────────────────────────────────────────────┤
-│  Batch Size: [1000 ▼]                                        │
-│  On Error:   (•) Skip row  ( ) Stop import  ( ) Replace      │
-│  [ ] Truncate table before import ⚠                         │
-│  [ ] Dry run (validate only)                                 │
-│                                                              │
-│                         [Cancel]  [Start Import]             │
-└──────────────────────────────────────────────────────────────┘
-
-┌──────────────────────────────────────────────────────────────┐
-│  Importing...                                                │
-├──────────────────────────────────────────────────────────────┤
-│  ████████████████████░░░░░░░░░░  67%                        │
-│  823 / 1,234 rows processed                                  │
-│  ✓ 820 successful  ✗ 3 failed                               │
-│                                                              │
-│                                              [Cancel]        │
-└──────────────────────────────────────────────────────────────┘
-```
-
-## Entry Points
-
-1. **Schema Explorer Context Menu**
-   - Right-click on table → "Import Data..."
-
-2. **Table Actions Dropdown**
-   - Table row → More menu → "Import"
-
-3. **Toolbar Button** (when table is selected)
-   - Import icon in schema explorer toolbar
-
-## Acceptance Criteria
-- [ ] User can upload CSV, JSON, and Excel files
-- [ ] File format is auto-detected
-- [ ] Preview shows first 100 rows
-- [ ] Columns can be mapped to table columns
-- [ ] Unmapped columns can be ignored
-- [ ] Type mismatches show warnings
-- [ ] Import options are configurable
-- [ ] Progress is displayed during import
-- [ ] Errors are logged with row numbers
-- [ ] Import can be cancelled
-- [ ] Success message shows final counts
-- [ ] Works with PostgreSQL, MySQL, SQLite
-
-## Security Considerations
-- File size limits
-- Sanitize input data
-- SQL injection prevention (parameterized queries)
-- Rate limiting on import endpoint
-- Validate file types (not just extension)
-
-## Dependencies
-- Schema information (column names, types)
-- Database write permissions
-- Bulk insert support in providers
-
-## Estimated Effort
-High complexity
-
-## Priority
-P2 - Nice to have
-
-## Related Issues
-- Data Export (existing feature)
-- Inline Data Editing (backlog)
-- Schema Explorer (existing)