@libredb/studio 0.9.7

package/docs/backlogs/000-PLATFORM_DATA_SYNC_DATABASE.md

@@ -0,0 +1,360 @@
+# 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

@@ -0,0 +1,118 @@
+# 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

@@ -0,0 +1,215 @@
+# 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)