@libredb/studio 0.9.7

package/docs/STORAGE_QUICK_SETUP.md

@@ -0,0 +1,419 @@
+# Storage Quick Setup Guide
+
+LibreDB Studio supports three storage modes. Pick the one that fits your use case and follow the steps below.
+
+> For a deep dive into the architecture, see [STORAGE_ARCHITECTURE.md](./STORAGE_ARCHITECTURE.md).
+
+---
+
+## Which Mode Should I Use?
+
+| Mode | Best For | Persistence | Multi-User | Setup |
+|------|----------|-------------|------------|-------|
+| **Local** (default) | Solo dev, quick start | Browser only | No | Zero config |
+| **SQLite** | Small teams, single server | Server file | Yes | 1 env var |
+| **PostgreSQL** | Enterprise, multi-node | External DB | Yes | 2 env vars |
+
+---
+
+## 1. Local Mode (Default)
+
+No configuration needed. All data stays in the browser's `localStorage`.
+
+```bash
+# Just start the app — that's it
+bun dev
+```
+
+**What you get:**
+- Instant start, no database required
+- Data persists across page reloads
+- Data is lost if browser storage is cleared or you switch browsers/devices
+
+**When to move on:** When you need data to survive across devices, browsers, or team members.
+
+---
+
+## 2. SQLite Mode
+
+A single file on the server. Great for self-hosted single-node deployments.
+
+### Minimal Setup (Just One Env Var)
+
+```bash
+# .env.local
+STORAGE_PROVIDER=sqlite
+```
+
+```bash
+bun dev
+```
+
+That's it. When `STORAGE_SQLITE_PATH` is not provided, the default path is `./data/libredb-storage.db`.
+
+### What Happens Automatically
+
+On the first API request, the SQLite provider:
+
+1. **Creates the directory** — `./data/` (or whatever parent directory the path points to) is created recursively if it doesn't exist
+2. **Creates the database file** — `libredb-storage.db` is created by `better-sqlite3`
+3. **Enables WAL mode** — Write-Ahead Logging for better concurrent read performance
+4. **Creates the table** — `user_storage` table with the schema below
+
+No manual setup, no migrations, no SQL scripts needed.
+
+### Custom Path
+
+If you want the database file in a different location:
+
+```bash
+# .env.local
+STORAGE_PROVIDER=sqlite
+STORAGE_SQLITE_PATH=/var/lib/libredb/storage.db
+```
+
+The directory must be writable by the app process. The directory and file are created automatically.
+
+### Docker
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    image: ghcr.io/libredb/libredb-studio:latest
+    ports:
+      - "3000:3000"
+    environment:
+      - STORAGE_PROVIDER=sqlite
+      - STORAGE_SQLITE_PATH=/app/data/libredb-storage.db
+    volumes:
+      - storage-data:/app/data
+
+volumes:
+  storage-data:
+```
+
+```bash
+docker-compose up -d
+```
+
+> **Volume is essential.** Without it, data is lost when the container restarts.
+
+### Verify
+
+```bash
+curl http://localhost:3000/api/storage/config
+# → {"provider":"sqlite","serverMode":true}
+```
+
+### Manual Table Creation (Optional)
+
+The table is auto-created, but if you prefer to create it yourself (e.g., for auditing or version control):
+
+```sql
+CREATE TABLE IF NOT EXISTS user_storage (
+  user_id    TEXT NOT NULL,
+  collection TEXT NOT NULL,
+  data       TEXT NOT NULL,
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (user_id, collection)
+);
+
+-- Recommended: enable WAL mode for concurrent read performance
+PRAGMA journal_mode = WAL;
+```
+
+---
+
+## 3. PostgreSQL Mode
+
+Recommended for production, teams, and high-availability deployments.
+
+> **Important:** Unlike SQLite, `STORAGE_POSTGRES_URL` is **required**. There is no default value. If you set `STORAGE_PROVIDER=postgres` without providing a connection string, the app will throw an error on the first storage request:
+> ```
+> Error: STORAGE_POSTGRES_URL is required when STORAGE_PROVIDER=postgres
+> ```
+
+### Local Development
+
+```bash
+# Start a PostgreSQL instance (if you don't have one)
+docker run -d --name libredb-pg \
+  -e POSTGRES_DB=libredb \
+  -e POSTGRES_USER=libredb \
+  -e POSTGRES_PASSWORD=secret \
+  -p 5432:5432 \
+  postgres:16-alpine
+```
+
+```bash
+# .env.local
+STORAGE_PROVIDER=postgres
+STORAGE_POSTGRES_URL=postgresql://libredb:secret@localhost:5432/libredb?sslmode=disable
+```
+
+```bash
+bun dev
+```
+
+### What Happens Automatically
+
+On the first API request, the PostgreSQL provider:
+
+1. **Creates a connection pool** — max 5 connections, 30s idle timeout
+2. **Creates the table** — `user_storage` table with the schema below via `CREATE TABLE IF NOT EXISTS`
+
+The database itself must already exist. The **table** is auto-created, but the **database** is not.
+
+### Required Privileges
+
+The PostgreSQL user specified in `STORAGE_POSTGRES_URL` needs:
+
+| Privilege | Why |
+|-----------|-----|
+| `CREATE TABLE` | Auto-create `user_storage` on first request (only needed once) |
+| `INSERT` | Save user data |
+| `UPDATE` | Update existing data |
+| `SELECT` | Read user data |
+
+If your DBA restricts `CREATE TABLE`, you can create the table manually (see below) and the user only needs `INSERT`/`UPDATE`/`SELECT`.
+
+### Docker Compose (App + PostgreSQL)
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    image: ghcr.io/libredb/libredb-studio:latest
+    ports:
+      - "3000:3000"
+    environment:
+      - STORAGE_PROVIDER=postgres
+      - STORAGE_POSTGRES_URL=postgresql://libredb:secret@db:5432/libredb?sslmode=disable
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      - POSTGRES_DB=libredb
+      - POSTGRES_USER=libredb
+      - POSTGRES_PASSWORD=secret
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U libredb"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  pgdata:
+```
+
+```bash
+docker-compose up -d
+```
+
+### Using an Existing PostgreSQL
+
+Just set the connection string — the table is auto-created:
+
+```bash
+STORAGE_PROVIDER=postgres
+STORAGE_POSTGRES_URL=postgresql://user:pass@your-pg-host:5432/your_db
+```
+
+Use `sslmode=disable` for local/non-SSL PostgreSQL and `sslmode=require` for managed cloud PostgreSQL:
+
+```bash
+# Local PostgreSQL
+STORAGE_POSTGRES_URL=postgresql://user:pass@localhost:5432/your_db?sslmode=disable
+
+# Cloud PostgreSQL
+STORAGE_POSTGRES_URL=postgresql://user:pass@your-pg-host:5432/your_db?sslmode=require
+```
+
+### Verify
+
+```bash
+curl http://localhost:3000/api/storage/config
+# → {"provider":"postgres","serverMode":true}
+```
+
+### Manual Table Creation (Optional)
+
+The table is auto-created on first request. However, if you prefer to create it yourself — for example, in environments where the app user doesn't have `CREATE TABLE` privileges, or you want to track schema changes in version control:
+
+```sql
+-- PostgreSQL
+CREATE TABLE IF NOT EXISTS user_storage (
+  user_id    TEXT NOT NULL,
+  collection TEXT NOT NULL,
+  data       TEXT NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (user_id, collection)
+);
+
+-- Optional: index for faster lookups by user
+CREATE INDEX IF NOT EXISTS idx_user_storage_user_id ON user_storage (user_id);
+```
+
+#### Minimal Privileges (When Table Already Exists)
+
+If a DBA creates the table, the app user only needs:
+
+```sql
+-- Grant only data access (no DDL needed)
+GRANT SELECT, INSERT, UPDATE ON user_storage TO libredb_app;
+```
+
+---
+
+## Migration: Local to Server
+
+When you switch from local mode to SQLite or PostgreSQL, **existing browser data is automatically migrated** on first login:
+
+1. User opens the app in server mode
+2. The sync hook detects it's the first time (no `libredb_server_migrated` flag)
+3. All localStorage data is sent to the server via `POST /api/storage/migrate`
+4. Server merges the data (ID-based deduplication — no duplicates)
+5. A flag is set in localStorage to prevent re-migration
+6. From this point on, the server is the source of truth
+
+**No manual steps required.** Just change the env var and restart.
+
+> If multiple users were sharing a browser in local mode, only the data from the user who migrates first will be sent. Each user's server storage is isolated by their login email.
+
+---
+
+## Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `STORAGE_PROVIDER` | No | `local` | `local`, `sqlite`, or `postgres` |
+| `STORAGE_SQLITE_PATH` | No | `./data/libredb-storage.db` | Path to SQLite file. Directory and file are auto-created. |
+| `STORAGE_POSTGRES_URL` | **Yes** (postgres mode) | — | PostgreSQL connection string. **No default — app will error without it.** |
+
+> These are **server-side only** variables (no `NEXT_PUBLIC_` prefix). The client discovers the mode at runtime via `GET /api/storage/config`. This means one Docker image works for all modes.
+
+### Default Behavior Summary
+
+| Mode | Config needed | What's auto-created |
+|------|--------------|---------------------|
+| `local` | Nothing | N/A (browser localStorage) |
+| `sqlite` | Just `STORAGE_PROVIDER=sqlite` | Directory + DB file + WAL mode + table |
+| `postgres` | `STORAGE_PROVIDER=postgres` + `STORAGE_POSTGRES_URL` | Table only (database must exist) |
+
+---
+
+## Health Check
+
+Check if the storage backend is reachable:
+
+```bash
+# Storage mode info (always works, no auth needed)
+curl http://localhost:3000/api/storage/config
+
+# Full data fetch (requires auth cookie)
+curl -b cookies.txt http://localhost:3000/api/storage
+```
+
+---
+
+## Troubleshooting
+
+### "Data not syncing to server"
+
+1. Check storage mode: `curl http://localhost:3000/api/storage/config`
+2. Make sure the response shows `"serverMode": true`
+3. Check browser console for sync errors (look for `[StorageSync]` prefixed logs)
+
+### SQLite: "SQLITE_CANTOPEN"
+
+- The directory in `STORAGE_SQLITE_PATH` must be writable by the app process
+- In Docker, make sure the volume is mounted correctly
+
+### PostgreSQL: "STORAGE_POSTGRES_URL is required"
+
+- You set `STORAGE_PROVIDER=postgres` but didn't provide `STORAGE_POSTGRES_URL`
+- Unlike SQLite, PostgreSQL has **no default** — a connection string is always required
+- Fix: add `STORAGE_POSTGRES_URL=postgresql://user:pass@host:5432/dbname` to your env
+
+### PostgreSQL: "Connection refused"
+
+- Verify `STORAGE_POSTGRES_URL` is correct and the database is reachable
+- In Docker Compose, use the service name (`db`) as the host, not `localhost`
+- Check that the PostgreSQL container is healthy: `docker-compose ps`
+
+### PostgreSQL: "server does not support SSL connections"
+
+- Your PostgreSQL server does not accept SSL, but SSL is enabled in the connection URL
+- Fix local setups by adding `?sslmode=disable` to `STORAGE_POSTGRES_URL`
+- For managed cloud PostgreSQL, use `?sslmode=require`
+
+### "Data disappeared after switching modes"
+
+- Switching from server mode **back** to local mode doesn't pull data from the server
+- Local mode only reads from localStorage
+- To recover: switch back to server mode, the data is still in the database
+
+### "Duplicate data after migration"
+
+- Migration uses ID-based deduplication — this shouldn't happen
+- If it does, check if the same user logged in from multiple browsers before migration completed
+
+---
+
+## Database Schema Reference
+
+Both SQLite and PostgreSQL use the same single-table design. The table is auto-created on first request, but the full DDL is provided here for reference.
+
+### SQLite
+
+```sql
+CREATE TABLE IF NOT EXISTS user_storage (
+  user_id    TEXT NOT NULL,
+  collection TEXT NOT NULL,
+  data       TEXT NOT NULL,
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (user_id, collection)
+);
+
+PRAGMA journal_mode = WAL;
+```
+
+### PostgreSQL
+
+```sql
+CREATE TABLE IF NOT EXISTS user_storage (
+  user_id    TEXT NOT NULL,
+  collection TEXT NOT NULL,
+  data       TEXT NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (user_id, collection)
+);
+
+-- Optional: index for faster lookups by user
+CREATE INDEX IF NOT EXISTS idx_user_storage_user_id ON user_storage (user_id);
+```
+
+### Schema Explanation
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `user_id` | TEXT | User's email from JWT token (e.g., `admin@libredb.org`) |
+| `collection` | TEXT | Data category: `connections`, `history`, `saved_queries`, `schema_snapshots`, `saved_charts`, `active_connection_id`, `audit_log`, `masking_config`, `threshold_config` |
+| `data` | TEXT | JSON-serialized collection data |
+| `updated_at` | TEXT / TIMESTAMPTZ | Last modification timestamp |
+
+Each row stores **one user's one collection** as a JSON blob. Adding a new collection type requires no schema changes — just a new row.
+
+---
+
+## What's Next?
+
+- [STORAGE_ARCHITECTURE.md](./STORAGE_ARCHITECTURE.md) — Deep dive into the write-through cache, sync hook, and provider internals
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — Overall system architecture
+- [OIDC_SETUP.md](./OIDC_SETUP.md) — SSO configuration (pairs well with server storage for team deployments)

package/docs/TECHNICAL_PLAN.md

@@ -0,0 +1,36 @@
+# LibreDB Studio: Expert Web/Mobile Database Management System
+
+## Vision
+To provide a zero-install, professional-grade database management experience that rivals desktop tools (DataGrip, DBeaver) while being optimized for both high-end desktop workflows and rapid mobile database administration.
+
+## Top 10 High-Impact Features
+
+1.  **Monaco SQL IntelliSense (IDE Experience)**: Integration of the Monaco Editor (VS Code core) with schema-aware autocomplete. It suggests table names, columns, and keywords based on the active connection.
+2.  **Universal Pro Data Grid**: A virtualized, high-performance table component supporting millions of rows with inline editing, multi-select, and Excel-like copy-paste.
+3.  **Visual Schema Graph (Mini-ERD)**: An interactive visualization of table relationships to help users understand complex schemas at a glance.
+4.  **Multi-Tab Query Workspace**: Support for multiple query buffers with persistent results, allowing parallel work across different tables or databases.
+5.  **Execution Plan Visualizer (EXPLAIN)**: A professional tool to analyze query performance visually, helping experts optimize their SQL.
+6.  **AI SQL Copilot**: Natural language to SQL conversion using OpenAI/Anthropic models to speed up complex query writing.
+7.  **Smart Mobile SQL Toolbar**: A custom, swipeable keyboard extension for mobile devices providing quick access to common SQL operators and keywords.
+8.  **Query History & Cloud Snippets**: Searchable history of all executed queries and a "Favorites" system to sync common snippets across devices.
+9.  **Advanced Data Exporter**: One-click export to CSV, JSON, SQL inserts, Markdown, and Excel with preview capabilities.
+10. **Live DB Health Monitoring**: Real-time dashboard showing active connections, long-running queries, and basic resource metrics (CPU/Memory if API permitted).
+
+## Development Roadmap
+
+### Phase 1: The Expert Core (Now)
+- [ ] Replace basic textareas with **Monaco Editor**.
+- [ ] Implement **Schema-Aware Autocomplete** (fetching table/column metadata).
+- [ ] Introduce **Multi-Tab** support for the editor.
+
+### Phase 2: Professional Data Handling
+- [ ] Transition to a **Virtualized Pro Grid** (TanStack Table + Windowing).
+- [ ] Add **Inline Editing** and **Batch Save** functionality.
+
+### Phase 3: Mobile & UX Excellence
+- [ ] Build the **Mobile SQL Toolbar**.
+- [ ] Implement **Query History & Snippets** sidebar.
+
+### Phase 4: Expert Analysis Tools
+- [ ] Visual **EXPLAIN** integration.
+- [ ] **ER Diagram** viewer for the explorer.