@libredb/studio 0.9.7

package/docs/SEED_CONNECTIONS.md

@@ -0,0 +1,468 @@
+# Seed Connections — Pre-Configured Database Connections
+
+Seed Connections let administrators pre-configure database connections via a YAML or JSON file. Users see these connections immediately after login — no manual setup required.
+
+**Use cases:**
+- Platform/SaaS: provision databases for all users on signup
+- Enterprise: give teams access to staging/production databases
+- On-prem: DevOps pre-loads connections via Helm values or Docker volumes
+
+## Quick Start
+
+**1.** Create `seed-connections.yaml`:
+
+```yaml
+version: "1"
+
+connections:
+  - id: "prod-db"
+    name: "Production Database"
+    type: postgres
+    host: "${DB_HOST}"
+    port: 5432
+    database: "${DB_NAME}"
+    user: "${DB_USER}"
+    password: "${DB_PASSWORD}"
+    roles: ["*"]
+```
+
+**2.** Mount and set env vars:
+
+```bash
+docker run \
+  -v ./seed-connections.yaml:/app/config/seed-connections.yaml:ro \
+  -e SEED_CONFIG_PATH=/app/config/seed-connections.yaml \
+  -e DB_HOST=mydb.internal -e DB_NAME=mydb \
+  -e DB_USER=reader -e DB_PASSWORD=secret \
+  ghcr.io/libredb/libredb-studio:latest
+```
+
+**3.** Login — the connection appears in the sidebar with a lock icon.
+
+---
+
+## Config File Format
+
+The config file is YAML (`.yaml`, `.yml`) or JSON (`.json`). Format is auto-detected by file extension.
+
+```yaml
+version: "1"
+
+defaults:                    # Optional — merged into every connection
+  managed: true
+  environment: production
+  ssl:
+    mode: require
+    rejectUnauthorized: true
+
+connections:
+  - id: "analytics-pg"       # Required, unique, lowercase slug [a-z0-9-]
+    name: "Analytics DB"      # Required, display name in UI
+    type: postgres            # Required: postgres|mysql|sqlite|mongodb|redis|oracle|mssql
+    host: "${PG_HOST}"
+    port: 5432
+    database: analytics
+    user: "${PG_USER}"
+    password: "${PG_PASSWORD}"
+    environment: production   # production|staging|development|local|other
+    group: "Data Team"        # Group label in sidebar
+    color: "#10B981"          # Hex color for environment badge
+    roles: ["admin"]          # Who can see this connection
+    managed: true             # Read-only in UI (default from `defaults`)
+    ssl:
+      mode: require
+      rejectUnauthorized: true
+    # serviceName: "ORCL"     # Oracle only
+    # instanceName: "MSSQL$"  # SQL Server only
+
+  - id: "dev-mysql"
+    name: "Dev MySQL"
+    type: mysql
+    host: "${MYSQL_HOST}"
+    port: 3306
+    database: devdb
+    user: "${MYSQL_USER}"
+    password: "${MYSQL_PASSWORD}"
+    roles: ["*"]              # Everyone can see this
+    managed: false            # User gets an editable copy
+    environment: development
+```
+
+### Field Reference
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `version` | Yes | — | Must be `"1"` |
+| `defaults` | No | — | Merged into all connections (connection values override) |
+| `defaults.managed` | No | `true` | Default managed state |
+| `defaults.environment` | No | — | Default environment label |
+| `defaults.ssl` | No | — | Default SSL config |
+| `connections` | Yes | — | Array of connection definitions (min 1) |
+| `connections[].id` | Yes | — | Unique slug: `[a-z0-9-]+`, max 64 chars |
+| `connections[].name` | Yes | — | Display name, max 128 chars |
+| `connections[].type` | Yes | — | Database type (see supported list above) |
+| `connections[].host` | No | — | Hostname or IP |
+| `connections[].port` | No | — | Port number (1-65535) |
+| `connections[].database` | No | — | Database name |
+| `connections[].user` | No | — | Username |
+| `connections[].password` | No | — | Password (use `${ENV_VAR}` syntax) |
+| `connections[].connectionString` | No | — | Full connection string (use `${ENV_VAR}`) |
+| `connections[].roles` | Yes | — | Access control: `["*"]`, `["admin"]`, `["user"]`, `["admin", "user"]` |
+| `connections[].managed` | No | from defaults | `true` = read-only, `false` = editable copy |
+| `connections[].environment` | No | from defaults | Environment badge |
+| `connections[].group` | No | — | Group label |
+| `connections[].color` | No | — | Hex color for badge (e.g., `#10B981`) |
+| `connections[].ssl` | No | from defaults | SSL configuration |
+| `connections[].serviceName` | No | — | Oracle service name |
+| `connections[].instanceName` | No | — | SQL Server instance name |
+
+---
+
+## Credential Management
+
+Credentials are never stored in the config file directly. Use `${ENV_VAR}` syntax to reference environment variables:
+
+```yaml
+connections:
+  - id: "prod-db"
+    password: "${PROD_DB_PASSWORD}"        # Resolved from process.env at runtime
+    connectionString: "${MONGO_URI}"       # Also works for connection strings
+    user: "${DB_USER}"                     # Any field can use ${} syntax
+```
+
+**How it works:**
+1. Config file is read from disk (YAML/JSON)
+2. `${VARIABLE_NAME}` patterns are resolved from `process.env`
+3. If an env var is undefined, that connection is **skipped** (others continue working)
+4. Plaintext passwords trigger a warning log (but still work)
+
+**Resolvable fields:** `password`, `connectionString`, `user`, `host`, `database`
+
+### Credential Sources by Deployment
+
+| Deployment | How to provide credentials |
+|------------|---------------------------|
+| **Docker** | `-e DB_PASSWORD=secret` |
+| **Docker Compose** | `environment:` block or `.env` file |
+| **Kubernetes** | `Secret` → `extraEnvFrom` in Helm values |
+| **Vault/SSM** | External Secrets Operator → K8s Secret → `extraEnvFrom` |
+
+### Kubernetes Example
+
+```yaml
+# Create a K8s Secret with credentials
+apiVersion: v1
+kind: Secret
+metadata:
+  name: seed-db-credentials
+type: Opaque
+stringData:
+  PG_PASSWORD: "my-secret-password"
+  MYSQL_PASSWORD: "another-secret"
+
+---
+# Reference in Helm values
+extraEnvFrom:
+  - secretRef:
+      name: seed-db-credentials
+```
+
+---
+
+## Role-Based Access Control
+
+Each connection has a `roles` field that controls which users can see it:
+
+| Config | Who sees it |
+|--------|-------------|
+| `roles: ["*"]` | All authenticated users |
+| `roles: ["admin"]` | Admin users only |
+| `roles: ["user"]` | Regular users only |
+| `roles: ["admin", "user"]` | Both (same as `["*"]`) |
+
+Roles are matched against the JWT session's `role` field. The role is extracted server-side from the JWT token — never from client input.
+
+**Current limitation:** The system supports `admin` and `user` roles only (matching the JWT `role` claim). Custom roles (e.g., `data-team`, `backend`) are planned for a future release with expanded OIDC role claim support.
+
+### How Role Filtering Works
+
+```
+User logs in → JWT contains { role: "user" }
+                    ↓
+GET /api/connections/managed
+                    ↓
+Server reads config → filters by role
+                    ↓
+User sees only connections where roles includes "user" or "*"
+```
+
+---
+
+## Managed vs. Unmanaged Connections
+
+### `managed: true` (default)
+
+- Connection appears with a **lock icon** in the sidebar
+- Users **cannot edit or delete** it
+- Credentials are **never sent to the client** — server resolves them at query time
+- If admin updates the config (e.g., password rotation), all users get the new credentials automatically
+- Best for: production databases, shared resources
+
+### `managed: false`
+
+- On first load, the connection is **copied to the user's local storage** with credentials
+- User **can edit or delete** their copy
+- Once copied, the connection belongs to the user — admin changes to the seed config won't affect existing copies
+- If the user deletes their copy, it will be re-imported on next login
+- Best for: development databases, sandbox environments
+
+### Comparison
+
+| Behavior | `managed: true` | `managed: false` |
+|----------|-----------------|-------------------|
+| UI edit/delete | Locked | Allowed |
+| Credentials on client | Never | Copied once |
+| Password rotation | Automatic | User must re-import |
+| Admin removes from config | Disappears for all | User copy remains |
+| Server-side credential resolution | Yes | No (user has local copy) |
+
+---
+
+## Hot Reload
+
+The config file is **cached in memory** with a TTL (default 60 seconds). When the file changes:
+
+1. Next API request after TTL expires triggers a re-read
+2. New connections appear, removed connections disappear
+3. Updated credentials take effect immediately (for `managed: true`)
+4. **No restart required**
+
+### Tuning the Cache TTL
+
+```bash
+# Default: 60 seconds
+SEED_CACHE_TTL_MS=60000
+
+# Faster refresh (5 seconds) — useful during development
+SEED_CACHE_TTL_MS=5000
+
+# Slower refresh (5 minutes) — production with infrequent changes
+SEED_CACHE_TTL_MS=300000
+```
+
+In Kubernetes, ConfigMap updates propagate in ~60-120s (kubelet sync period). Combined with the cache TTL, expect ~2-3 minutes for changes to take effect.
+
+---
+
+## Deployment Examples
+
+### Docker
+
+```bash
+docker run -d \
+  -v ./seed-connections.yaml:/app/config/seed-connections.yaml:ro \
+  -e SEED_CONFIG_PATH=/app/config/seed-connections.yaml \
+  -e PG_PASSWORD=secret \
+  -e JWT_SECRET=your-32-char-jwt-secret-here!! \
+  -e ADMIN_PASSWORD=MyAdmin123 \
+  -e USER_PASSWORD=MyUser123 \
+  -p 3000:3000 \
+  ghcr.io/libredb/libredb-studio:latest
+```
+
+### Docker Compose
+
+```yaml
+services:
+  libredb:
+    image: ghcr.io/libredb/libredb-studio:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./seed-connections.yaml:/app/config/seed-connections.yaml:ro
+    environment:
+      SEED_CONFIG_PATH: /app/config/seed-connections.yaml
+      JWT_SECRET: your-32-char-jwt-secret-here!!
+      ADMIN_PASSWORD: MyAdmin123
+      USER_PASSWORD: MyUser123
+      PG_PASSWORD: ${PG_PASSWORD}
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
+    env_file:
+      - .env  # Store credentials here
+```
+
+### Kubernetes (Helm)
+
+**Option A — Inline config in values.yaml:**
+
+```yaml
+seedConnections:
+  enabled: true
+  config:
+    version: "1"
+    defaults:
+      managed: true
+      environment: production
+    connections:
+      - id: "prod-analytics"
+        name: "Production Analytics"
+        type: postgres
+        host: analytics-db.internal
+        port: 5432
+        database: analytics
+        user: readonly
+        password: "${ANALYTICS_DB_PASSWORD}"
+        roles: ["admin"]
+        color: "#10B981"
+      - id: "staging-api"
+        name: "Staging API DB"
+        type: mysql
+        host: staging-mysql.internal
+        password: "${STAGING_DB_PASSWORD}"
+        roles: ["*"]
+        managed: false
+        environment: staging
+
+extraEnvFrom:
+  - secretRef:
+      name: seed-db-credentials
+```
+
+**Option B — External ConfigMap:**
+
+```yaml
+seedConnections:
+  enabled: true
+  existingConfigMap: "my-seed-connections"  # Pre-created ConfigMap
+  configMapKey: "connections.yaml"          # Key within the ConfigMap
+
+extraEnvFrom:
+  - secretRef:
+      name: seed-db-credentials
+```
+
+---
+
+## Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| Config file not found | App runs normally, no seed connections. Warning logged. |
+| Invalid YAML/JSON | Endpoint returns 500. Error logged with details. |
+| Invalid config (Zod validation fails) | Endpoint returns 500 with validation errors. |
+| Unrecognized `version` | Endpoint returns 500. Future versions require code update. |
+| `${ENV_VAR}` not defined | That connection is **skipped**. Others work normally. Error logged. |
+| User role doesn't match any connection | Empty list returned. Normal behavior. |
+| Seed connection not found at query time | 404 response. |
+| User doesn't have access to seed connection | 403 response. |
+
+**Design principle:** One broken connection never breaks the others. Each connection is resolved independently.
+
+---
+
+## Security Model
+
+### Credential Protection
+
+- `managed: true` connections: passwords **never reach the client**. The API strips `password` and `connectionString` from responses. Server resolves credentials at query execution time.
+- Config file should be mounted **read-only** (`:ro` in Docker, `readOnly: true` in Kubernetes).
+- Use `${ENV_VAR}` for all secrets. Plaintext passwords trigger a warning log.
+
+### Role Enforcement
+
+- User role is extracted from the JWT session **server-side** — never from client headers or request params.
+- Every database operation (query, schema, health check, etc.) goes through `resolveConnection()` which verifies role access before returning credentials.
+- Role check failures return 403 with no credential information.
+
+### Audit Trail
+
+Every operation on a managed connection is logged:
+
+```json
+{
+  "event": "managed_connection_query",
+  "connectionId": "prod-analytics",
+  "user": "admin@company.com",
+  "role": "admin",
+  "route": "/api/db/query",
+  "timestamp": "2026-03-25T10:30:00Z"
+}
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SEED_CONFIG_PATH` | `/app/config/seed-connections.yaml` | Path to config file |
+| `SEED_CACHE_TTL_MS` | `60000` | Cache TTL in milliseconds |
+
+---
+
+## Troubleshooting
+
+### Connections don't appear after login
+
+1. Check if the config file exists at `SEED_CONFIG_PATH`
+2. Check server logs for `Seed config file not found` warning
+3. Verify the YAML is valid: `cat seed-connections.yaml | python3 -c "import yaml,sys; yaml.safe_load(sys.stdin)"`
+4. Check if `${ENV_VAR}` values are set: connections with unresolvable vars are silently skipped
+
+### "Access denied" error when querying
+
+The user's role doesn't match the connection's `roles` array. Check:
+- User JWT role: login as admin vs user
+- Connection `roles` field in config
+
+### Credentials not updating after config change
+
+- `managed: true`: Wait for TTL to expire (default 60s), or restart the app
+- `managed: false`: The user has a local copy. They need to delete it from the sidebar and re-login to get the updated version
+
+### Two identical connections in sidebar
+
+Clear browser localStorage (`libredb_connections` key) and refresh. This can happen if a connection was persisted before being marked as managed.
+
+---
+
+## Architecture
+
+```
+seed-connections.yaml (volume mount)
+        │
+  ┌─────▼──────────┐
+  │  ConfigLoader   │  Read + YAML/JSON parse + Zod validate + TTL cache
+  └─────┬──────────┘
+        │
+  ┌─────▼──────────────┐
+  │ CredentialResolver  │  ${ENV_VAR} → process.env + plaintext warning
+  └─────┬──────────────┘
+        │
+  ┌─────▼──────────────┐
+  │ ConnectionFilter    │  Role filter + defaults merge → ManagedConnection[]
+  └─────┬──────────────┘
+        │
+  ┌─────▼───────────────────────┐
+  │ GET /api/connections/managed │  Auth + strip credentials for managed:true
+  └─────┬───────────────────────┘
+        │
+  ┌─────▼────────────────────┐
+  │ useConnectionManager     │  Merge managed + user connections
+  └─────┬────────────────────┘
+        │
+  ┌─────▼────────────────────────────┐
+  │ resolveConnection() (all routes) │  seed: prefix → server-side credential resolution
+  └──────────────────────────────────┘
+```
+
+**Module:** `src/lib/seed/` — 6 files, ~350 lines total
+
+| File | Responsibility |
+|------|---------------|
+| `types.ts` | Zod schemas + TypeScript types |
+| `config-loader.ts` | File read + parse + validate + cache |
+| `credential-resolver.ts` | `${ENV_VAR}` resolution |
+| `connection-filter.ts` | Role filter + defaults merge |
+| `resolve-connection.ts` | Shared utility for all API routes |
+| `index.ts` | Public API: `getManagedConnections()` |

package/docs/SQL_ALIAS_COMPLETION.md

@@ -0,0 +1,190 @@
+# SQL Alias-Based Code Completion
+
+This document describes the intelligent SQL code completion feature that provides context-aware autocompletion with alias support in the Monaco Editor.
+
+## Features
+
+### 1. Alias-Based Column Completion
+
+When you define a table alias in your SQL query, typing the alias followed by a dot (`.`) will suggest columns from the referenced table.
+
+**Supported Patterns:**
+
+| Pattern | Example | Result |
+|---------|---------|--------|
+| `FROM table AS alias` | `FROM employee AS e WHERE e.` | employee columns |
+| `FROM table alias` | `FROM employee e WHERE e.` | employee columns |
+| `JOIN table AS alias` | `JOIN department AS d ON d.` | department columns |
+| `JOIN table alias` | `LEFT JOIN salary s ON s.` | salary columns |
+| `schema.table alias` | `FROM employees.employee e WHERE e.` | employee columns |
+| Multiple aliases | `FROM a AS x JOIN b AS y` | Both `x.` and `y.` work |
+| CTE references | `WITH cte AS (...) SELECT cte.` | CTE columns |
+| Direct table | `employee.` | employee columns |
+
+### 2. Context-Aware Completions
+
+The completion system intelligently shows suggestions based on SQL context:
+
+**Columns are shown only after:**
+- `SELECT` keyword
+- `WHERE` clause
+- `AND`, `OR` operators
+- `ON` (in JOIN conditions)
+- `SET` (in UPDATE statements)
+- `HAVING` clause
+- `ORDER BY`, `GROUP BY` clauses
+- Comma (`,`) in column lists
+
+**Columns are NOT shown when:**
+- Typing keywords like `FROM`, `JOIN`, `WHERE`
+- After `SELECT *` (expecting keyword, not column)
+
+### 3. Prioritized Suggestions
+
+Suggestions are sorted by relevance:
+
+| Priority | Type | Description |
+|----------|------|-------------|
+| 1st | Keywords | SQL keywords (SELECT, FROM, WHERE, etc.) |
+| 2nd | Functions | SQL functions (COUNT, SUM, AVG, etc.) |
+| 3rd | Tables | Database tables |
+| 4th | Snippets | Query templates |
+| 5th | Columns | Table columns (context-dependent) |
+
+## Architecture
+
+### Module Structure
+
+```
+src/lib/sql/
+├── alias-extractor.ts   # Core alias extraction logic
+├── types.ts             # TypeScript interfaces
+└── index.ts             # Module exports
+```
+
+### Key Components
+
+#### 1. Alias Extractor (`src/lib/sql/alias-extractor.ts`)
+
+Lightweight regex-based SQL parser that extracts table aliases without external dependencies.
+
+**Functions:**
+- `extractAliases(sql: string)` - Extract all table aliases from a SQL query
+- `resolveAlias(identifier: string, aliases: Map)` - Resolve an alias to its table name
+
+**How it works:**
+1. Preprocesses SQL to remove comments and string literals
+2. Extracts FROM clause aliases
+3. Extracts JOIN clause aliases
+4. Extracts CTE (WITH clause) aliases
+5. Returns a Map of alias → table name
+
+#### 2. Completion Provider (`src/components/QueryEditor.tsx`)
+
+Monaco Editor completion provider that integrates with the alias extractor.
+
+**Dot-triggered completion flow:**
+```
+User types: "e."
+     ↓
+1. Try direct table lookup: columnMap.get("e")
+     ↓ (not found)
+2. Extract aliases from query text
+     ↓
+3. Resolve "e" → "employee"
+     ↓
+4. Find columns: columnMap.get("employee")
+     ↓
+5. Return column suggestions
+```
+
+### Edge Cases Handled
+
+1. **SQL Keywords as Aliases**: Filters out `ON`, `WHERE`, `AND`, etc.
+2. **Comments**: Removes `--` and `/* */` before parsing
+3. **String Literals**: Replaces with placeholder to avoid false matches
+4. **Case Insensitivity**: Alias lookup is case-insensitive
+5. **Schema Prefixes**: Handles `schema.table` format (e.g., `employees.employee`)
+
+## Performance Considerations
+
+- **No external SQL parser**: Keeps bundle size small
+- **Regex-based parsing**: Fast execution (<10ms for typical queries)
+- **Lazy evaluation**: Alias extraction only runs on dot-trigger
+- **Cursor-limited parsing**: Only parses text from start to cursor position
+- **Early exit**: Skips parsing if no FROM/JOIN/WITH keywords found
+
+## Examples
+
+### Basic Alias Usage
+```sql
+SELECT e.first_name, e.last_name
+FROM employee e
+WHERE e.hire_date > '2020-01-01'
+```
+Typing `e.` after defining `FROM employee e` will suggest all employee columns.
+
+### Multiple Table Aliases
+```sql
+SELECT
+  e.first_name,
+  d.dept_name,
+  s.amount
+FROM employee e
+JOIN department_employee de ON de.employee_id = e.id
+JOIN department d ON d.id = de.department_id
+JOIN salary s ON s.employee_id = e.id
+```
+Each alias (`e`, `de`, `d`, `s`) resolves to its respective table.
+
+### CTE Support
+```sql
+WITH active_employees AS (
+  SELECT * FROM employee WHERE status = 'active'
+)
+SELECT ae.first_name
+FROM active_employees ae
+WHERE ae.department_id = 1
+```
+The `ae` alias resolves to the CTE `active_employees`.
+
+## Integration
+
+The alias completion is automatically available in the SQL editor. No configuration required.
+
+### API
+
+```typescript
+import { extractAliases, resolveAlias } from '@/lib/sql';
+
+// Extract aliases from a query
+const { aliases } = extractAliases('SELECT * FROM employee e WHERE e.id = 1');
+
+// Resolve an alias
+const tableName = resolveAlias('e', aliases); // Returns 'employee'
+```
+
+## Type Definitions
+
+```typescript
+interface TableAlias {
+  alias: string;           // e.g., 'e'
+  tableName: string;       // e.g., 'employee'
+  schema?: string;         // e.g., 'employees'
+  source: 'from' | 'join' | 'cte';
+}
+
+interface AliasExtractionResult {
+  aliases: Map<string, TableAlias>;
+  hasTableReferences: boolean;
+}
+```
+
+## Related Files
+
+| File | Description |
+|------|-------------|
+| `src/lib/sql/types.ts` | Type definitions |
+| `src/lib/sql/alias-extractor.ts` | Core parsing logic |
+| `src/lib/sql/index.ts` | Module exports |
+| `src/components/QueryEditor.tsx` | Monaco Editor integration |