@libredb/studio 0.9.7

package/docs/ARCHITECTURE.md

@@ -0,0 +1,218 @@
+# High-Level Architecture - LibreDB Studio
+
+This document outlines the architectural patterns, tech stack, and system design for LibreDB Studio, a web-based SQL IDE for cloud-native teams.
+
+## System Overview
+
+LibreDB Studio is a hybrid, cloud-native database management tool that provides an IDE-like experience in the browser. It supports **8 database backends** via a Strategy Pattern abstraction: PostgreSQL, MySQL, SQLite, Oracle, SQL Server, MongoDB, Redis.
+
+## 1. Core Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | Next.js 16 (App Router) with React 19 |
+| Runtime | Bun / Node.js |
+| Language | TypeScript (strict mode) |
+| Styling | Tailwind CSS 4 + Shadcn/UI |
+| Animations | Framer Motion v12 |
+| SQL Editor | Monaco Editor |
+| Data Grid | TanStack React Table + react-virtual |
+| AI | Multi-model (Gemini, OpenAI, Ollama, Custom) |
+| Auth | JWT (`jose`) + OIDC SSO (`openid-client`) |
+| Charts | Recharts |
+| Containerization | Docker (multi-stage Bun build) |
+
+## 2. High-Level Architecture Diagram
+
+```mermaid
+graph TD
+    User((User)) -->|HTTPS| Frontend[Next.js Frontend<br/>App Router + React 19]
+    Frontend -->|API Calls| API[Next.js API Routes<br/>src/app/api]
+
+    subgraph "Application Core"
+        API -->|Auth| AuthLib[src/lib/auth.ts<br/>JWT + OIDC]
+        API -->|Query| DBFactory[Provider Factory<br/>src/lib/db/factory.ts]
+        API -->|AI| LLMFactory[LLM Factory<br/>src/lib/llm/]
+    end
+
+    subgraph "Database Providers (Strategy Pattern)"
+        DBFactory --> SQL[SQL Providers]
+        DBFactory --> Document[Document Providers]
+        DBFactory --> KeyValue[Key-Value Providers]
+
+        SQL --> PG[(PostgreSQL)]
+        SQL --> MySQL[(MySQL)]
+        SQL --> SQLite[(SQLite)]
+        SQL --> Oracle[(Oracle)]
+        SQL --> MSSQL[(SQL Server)]
+        Document --> MongoDB[(MongoDB)]
+        KeyValue --> Redis[(Redis)]
+    end
+
+    subgraph "AI Providers (Strategy Pattern)"
+        LLMFactory --> Gemini[[Gemini]]
+        LLMFactory --> OpenAI[[OpenAI]]
+        LLMFactory --> Ollama[[Ollama]]
+        LLMFactory --> CustomLLM[[Custom]]
+    end
+
+    subgraph "Security"
+        AuthLib -->|Session| JWT[HTTP-Only JWT Cookies]
+        AuthLib -->|SSO| OIDC[OIDC Provider<br/>Auth0 / Keycloak / Okta / Azure AD]
+    end
+```
+
+## 3. Database Provider Architecture
+
+```mermaid
+classDiagram
+    class BaseDatabaseProvider {
+        <<abstract>>
+        +connect()
+        +disconnect()
+        +executeQuery()
+        +getSchema()
+        +getHealth()
+        +getCapabilities() ProviderCapabilities
+        +getLabels() ProviderLabels
+        +prepareQuery() PreparedQuery
+    }
+
+    class SQLBaseProvider {
+        <<abstract>>
+        +beginTransaction()
+        +commitTransaction()
+        +rollbackTransaction()
+        +cancelQuery()
+    }
+
+    BaseDatabaseProvider <|-- SQLBaseProvider
+    BaseDatabaseProvider <|-- MongoDBProvider
+    BaseDatabaseProvider <|-- RedisProvider
+
+    SQLBaseProvider <|-- PostgresProvider
+    SQLBaseProvider <|-- MySQLProvider
+    SQLBaseProvider <|-- SQLiteProvider
+    SQLBaseProvider <|-- OracleProvider
+    SQLBaseProvider <|-- MSSQLProvider
+```
+
+Each provider implements:
+- **`getCapabilities()`** - queryLanguage, supportsExplain, supportsCreateTable, maintenanceOperations, etc.
+- **`getLabels()`** - entityName, selectAction, searchPlaceholder, etc. (drives all UI text)
+- **`prepareQuery()`** - handles query limiting per-provider (SQL LIMIT injection vs MongoDB native)
+
+Adding a new database type requires: **1 provider class** + **1 entry in `db-ui-config.ts`**.
+
+## 4. Key Architectural Patterns
+
+### 4.1. Strategy Pattern (Database & LLM)
+
+Both database and LLM layers use the Strategy Pattern with a factory:
+- `src/lib/db/factory.ts` - Creates the correct database provider based on connection type
+- `src/lib/llm/factory.ts` - Creates the correct LLM provider based on configuration
+
+No `isMongoDB` / `=== 'mongodb'` checks outside provider classes. All behavior differences are driven through capabilities and labels.
+
+### 4.2. Authentication Flow
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant F as Frontend
+    participant A as API (/api/auth)
+    participant O as OIDC Provider
+
+    alt Local Auth
+        U->>F: Email + Password
+        F->>A: POST /api/auth/login
+        A->>F: Set HTTP-Only JWT Cookie
+    else OIDC SSO
+        U->>F: Click SSO Login
+        F->>O: Redirect (PKCE)
+        O->>F: Authorization Code
+        F->>A: GET /api/auth/oidc/callback
+        A->>O: Token Exchange
+        A->>F: Set HTTP-Only JWT Cookie
+    end
+```
+
+Controlled by `NEXT_PUBLIC_AUTH_PROVIDER` (`local` | `oidc`). Both flows result in the same JWT session cookie. Proxy (`src/proxy.ts`) enforces RBAC (admin vs user roles).
+
+### 4.3. Multi-Statement Execution
+
+`src/lib/sql/statement-splitter.ts` splits SQL input into individual statements, handling:
+- String literals (single/double quotes)
+- Block and line comments
+- Dollar-quoting (PostgreSQL)
+
+Multi-statement queries execute sequentially via `POST /api/db/multi-query`.
+
+### 4.4. Storage Abstraction Layer
+
+- **Write-through cache architecture**: localStorage (L1 cache) + optional server storage (L2 persistent)
+- **Three storage modes** controlled by `STORAGE_PROVIDER` env var:
+  - `local` (default): Browser localStorage only, zero configuration
+  - `sqlite`: Server-side SQLite file via `better-sqlite3`
+  - `postgres`: Server-side PostgreSQL via `pg`
+- **`useStorageSync` hook** in Studio.tsx: discovers mode at runtime via `/api/storage/config`, pulls on mount, pushes mutations (debounced 500ms)
+- **Migration**: First login auto-migrates localStorage to server; `libredb_server_migrated` flag prevents re-migration
+- **Graceful degradation**: If server unreachable, localStorage continues working
+
+### 4.5. Client State Management
+
+- **Storage module** (`src/lib/storage/`) for persistent data: connections, query history, saved queries, schema snapshots, chart configs, audit log, masking config, threshold config
+- **React hooks** for UI state: tabs, active connection, execution status
+- **Custom hooks** extracted from Studio.tsx: `useAuth`, `useConnectionManager`, `useTabManager`, `useTransactionControl`, `useQueryExecution`, `useInlineEditing`
+
+## 5. Directory Structure
+
+```
+src/
+├── app/                    # Next.js App Router
+│   ├── api/
+│   │   ├── auth/           # Login/logout/me + OIDC (PKCE, callback)
+│   │   ├── ai/             # Chat, NL2SQL, explain, safety
+│   │   ├── db/             # Query, schema, health, maintenance, transactions
+│   │   ├── storage/        # Storage sync API (config, CRUD, migrate)
+│   │   └── admin/          # Fleet health, audit
+│   ├── admin/              # Admin dashboard (RBAC protected)
+│   └── login/              # Login page
+├── components/
+│   ├── Studio.tsx           # Main application shell
+│   ├── QueryEditor.tsx      # Monaco SQL editor wrapper
+│   ├── ResultsGrid.tsx      # Virtualized data grid
+│   ├── sidebar/             # ConnectionsList, ConnectionItem
+│   ├── studio/              # StudioTabBar, QueryToolbar, BottomPanel
+│   ├── admin/               # AdminDashboard (5 tabs)
+│   ├── schema-explorer/     # SchemaExplorer
+│   └── ui/                  # Shadcn/UI primitives
+├── hooks/                   # Custom React hooks
+└── lib/
+    ├── db/                  # Database provider module
+    │   ├── providers/
+    │   │   ├── sql/         # postgres, mysql, sqlite, oracle, mssql
+    │   │   ├── document/    # mongodb
+    │   │   └── keyvalue/    # redis
+    │   ├── factory.ts       # Provider factory
+    │   └── types.ts         # Database types
+    ├── llm/                 # LLM provider module
+    ├── schema-diff/         # Diff engine + migration SQL generator
+    ├── sql/                 # Statement splitter, alias extractor
+    ├── ssh/                 # SSH tunnel support
+    ├── auth.ts              # JWT utilities
+    ├── oidc.ts              # OIDC utilities
+    └── storage/             # Storage abstraction layer
+        ├── index.ts         # Barrel export
+        ├── storage-facade.ts # Public sync API + CustomEvent dispatch
+        ├── local-storage.ts  # Pure localStorage CRUD
+        ├── factory.ts       # Env-based provider factory
+        └── providers/       # SQLite + PostgreSQL backends
+```
+
+## 6. Deployment
+
+- **Docker**: Multi-stage Bun build with standalone Next.js output
+- **Health Check**: `GET /api/db/health`
+- **Stateless API**: API routes are stateless, suitable for horizontal scaling
+- **Environment**: Configured via `.env.local` (see CLAUDE.md for full variable list)

package/docs/DATABASE_PROVIDERS.md

@@ -0,0 +1,358 @@
+# Database Provider Architecture
+
+This document describes the modular database provider architecture implemented using the Strategy Pattern.
+
+## Overview
+
+The database abstraction layer (`src/lib/db/`) provides a unified interface for multiple database types while maintaining type safety, connection pooling, and consistent error handling.
+
+## Architecture
+
+```
+src/lib/db/
+├── index.ts                    # Public exports
+├── types.ts                    # Interfaces & Types
+├── errors.ts                   # Custom error classes
+├── factory.ts                  # Provider Factory
+├── base-provider.ts            # Abstract base class
+├── providers/
+│   ├── sql/                    # SQL Database Providers
+│   │   ├── index.ts            # SQL exports
+│   │   ├── sql-base.ts         # SQL-specific base class
+│   │   ├── postgres.ts         # PostgreSQL Strategy
+│   │   ├── mysql.ts            # MySQL Strategy
+│   │   └── sqlite.ts           # SQLite Strategy
+│   ├── document/               # Document Database Providers
+│   │   ├── index.ts            # Document exports
+│   │   └── mongodb.ts          # MongoDB Strategy
+└── utils/
+    └── pool-manager.ts         # Connection pool utilities
+```
+
+## Provider Hierarchy
+
+```
+BaseDatabaseProvider (abstract)
+├── SQLBaseProvider (abstract) ─────────────┐
+│   ├── PostgresProvider                    │ SQL Databases
+│   ├── MySQLProvider                       │ (shared SQL utilities)
+│   └── SQLiteProvider                      │
+├── MongoDBProvider ────────────────────────┤ Document Databases
+```
+
+## Supported Databases
+
+| Category | Database   | Status | Driver           | Pooling | Notes                    |
+|----------|------------|--------|------------------|---------|--------------------------|
+| SQL      | PostgreSQL | Full   | `pg`             | Yes     | Production ready         |
+| SQL      | MySQL      | Full   | `mysql2`         | Yes     | Production ready         |
+| SQL      | SQLite     | Full   | `better-sqlite3` | No      | File-based, sync driver  |
+| Document | MongoDB    | Full   | `mongodb`        | Yes     | JSON-based queries       |
+| SQL      | Oracle     | Full   | `oracledb`       | Yes     | Production ready         |
+| SQL      | SQL Server | Full   | `mssql`          | Yes     | Production ready         |
+
+## Core Interface
+
+```typescript
+interface DatabaseProvider {
+  readonly type: DatabaseType;
+  readonly config: DatabaseConnection;
+
+  // Connection lifecycle
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+
+  // Query execution
+  query(sql: string, params?: unknown[]): Promise<QueryResult>;
+
+  // Schema operations
+  getSchema(): Promise<TableSchema[]>;
+  getTables(): Promise<string[]>;
+
+  // Health & monitoring
+  getHealth(): Promise<HealthInfo>;
+
+  // Maintenance operations
+  runMaintenance(type: MaintenanceType, target?: string): Promise<MaintenanceResult>;
+
+  // Validation
+  validate(): void;
+}
+```
+
+## Usage
+
+### Basic Usage (Recommended)
+
+```typescript
+import { getOrCreateProvider } from '@/lib/db';
+
+// SQL Database
+const sqlConnection = {
+  id: 'my-postgres',
+  name: 'Production DB',
+  type: 'postgres',
+  host: 'localhost',
+  port: 5432,
+  database: 'mydb',
+  user: 'admin',
+  password: 'secret',
+  createdAt: new Date(),
+};
+
+const sqlProvider = await getOrCreateProvider(sqlConnection);
+const result = await sqlProvider.query('SELECT * FROM users LIMIT 10');
+
+// MongoDB
+const mongoConnection = {
+  id: 'my-mongo',
+  name: 'MongoDB Atlas',
+  type: 'mongodb',
+  connectionString: 'mongodb+srv://user:pass@cluster.mongodb.net/mydb',
+  createdAt: new Date(),
+};
+
+const mongoProvider = await getOrCreateProvider(mongoConnection);
+const docs = await mongoProvider.query(JSON.stringify({
+  collection: 'users',
+  operation: 'find',
+  filter: { age: { $gt: 18 } },
+  options: { limit: 10 }
+}));
+```
+
+### Direct Provider Creation
+
+```typescript
+import { createDatabaseProvider } from '@/lib/db';
+
+const provider = createDatabaseProvider(connection, {
+  pool: { min: 2, max: 10 },
+  queryTimeout: 30000,
+});
+
+await provider.connect();
+const schema = await provider.getSchema();
+await provider.disconnect();
+```
+
+## MongoDB Query Format
+
+MongoDB queries are JSON-formatted with the following structure:
+
+```typescript
+interface MongoQuery {
+  collection: string;  // Required: collection name
+  operation: string;   // Required: find, findOne, aggregate, count, distinct,
+                       //           insertOne, insertMany, updateOne, updateMany,
+                       //           deleteOne, deleteMany
+  filter?: object;     // Optional: query filter
+  pipeline?: object[]; // Optional: aggregation pipeline
+  update?: object;     // Optional: update document
+  documents?: object[];// Optional: documents to insert
+  options?: {
+    limit?: number;
+    skip?: number;
+    sort?: object;
+    projection?: object;
+  };
+}
+```
+
+### MongoDB Query Examples
+
+```json
+// Find documents
+{"collection": "users", "operation": "find", "filter": {"status": "active"}, "options": {"limit": 50}}
+
+// Find one document
+{"collection": "users", "operation": "findOne", "filter": {"_id": "123"}}
+
+// Aggregate
+{"collection": "orders", "operation": "aggregate", "pipeline": [
+  {"$match": {"status": "completed"}},
+  {"$group": {"_id": "$customerId", "total": {"$sum": "$amount"}}}
+]}
+
+// Count documents
+{"collection": "users", "operation": "count", "filter": {"role": "admin"}}
+
+// Insert one document
+{"collection": "users", "operation": "insertOne", "documents": [{"name": "John", "email": "john@example.com"}]}
+
+// Update documents
+{"collection": "users", "operation": "updateOne", "filter": {"_id": "123"}, "update": {"$set": {"status": "inactive"}}}
+
+// Delete documents
+{"collection": "users", "operation": "deleteMany", "filter": {"status": "deleted"}}
+```
+
+## Configuration
+
+### Pool Configuration
+
+```typescript
+interface PoolConfig {
+  min: number;          // Minimum connections (default: 2)
+  max: number;          // Maximum connections (default: 10)
+  idleTimeout: number;  // Close idle after ms (default: 30000)
+  acquireTimeout: number; // Wait timeout ms (default: 60000)
+}
+```
+
+### Query Timeout
+
+Default query timeout is 60 seconds (60000ms). Configure per-provider:
+
+```typescript
+const provider = createDatabaseProvider(connection, {
+  queryTimeout: 30000, // 30 seconds
+});
+```
+
+## Error Handling
+
+Custom error classes provide detailed error information:
+
+```typescript
+import {
+  DatabaseError,
+  ConnectionError,
+  QueryError,
+  TimeoutError,
+  isDatabaseError,
+  isConnectionError,
+  isQueryError,
+} from '@/lib/db';
+
+try {
+  await provider.query(sql);
+} catch (error) {
+  if (isConnectionError(error)) {
+    console.log(`Connection failed to ${error.host}:${error.port}`);
+  } else if (isQueryError(error)) {
+    console.log(`Query error: ${error.message}, SQL: ${error.sql}`);
+  } else if (isDatabaseError(error)) {
+    console.log(`Database error: ${error.code}`);
+  }
+}
+```
+
+### Error Hierarchy
+
+```
+DatabaseError (base)
+├── DatabaseConfigError  - Configuration errors
+├── ConnectionError      - Connection failures
+├── AuthenticationError  - Invalid credentials
+├── PoolExhaustedError   - No available connections
+├── QueryError           - SQL/MQL syntax/execution errors
+└── TimeoutError         - Query/connection timeouts
+```
+
+## Adding New Providers
+
+### Adding a New SQL Database (e.g., Oracle)
+
+1. Create provider class extending `SQLBaseProvider`:
+
+```typescript
+// src/lib/db/providers/sql/oracle.ts
+import { SQLBaseProvider } from './sql-base';
+
+export class OracleProvider extends SQLBaseProvider {
+  public async connect(): Promise<void> { /* ... */ }
+  public async disconnect(): Promise<void> { /* ... */ }
+  public async query(sql: string): Promise<QueryResult> { /* ... */ }
+  public async getSchema(): Promise<TableSchema[]> { /* ... */ }
+  public async getHealth(): Promise<HealthInfo> { /* ... */ }
+  public async runMaintenance(type: MaintenanceType): Promise<MaintenanceResult> { /* ... */ }
+}
+```
+
+2. Export from `sql/index.ts`:
+
+```typescript
+export { OracleProvider } from './oracle';
+```
+
+3. Register in factory:
+
+```typescript
+case 'oracle':
+  return new OracleProvider(connection, options);
+```
+
+4. Update types:
+
+```typescript
+export type DatabaseType = 'postgres' | 'mysql' | 'sqlite' | 'oracle' | 'mongodb';
+```
+
+### Adding a New Document Database (e.g., Couchbase)
+
+1. Create provider class extending `BaseDatabaseProvider`:
+
+```typescript
+// src/lib/db/providers/document/couchbase.ts
+import { BaseDatabaseProvider } from '../../base-provider';
+
+export class CouchbaseProvider extends BaseDatabaseProvider {
+  // Implement all required methods
+}
+```
+
+2. Export and register in factory.
+
+### Adding a New Database Category (e.g., Key-Value)
+
+1. Create new folder: `src/lib/db/providers/keyvalue/`
+2. Optionally create base class if shared logic exists: `keyvalue-base.ts`
+3. Create provider: `redis.ts`
+4. Follow same registration pattern
+
+## Provider-Specific Features
+
+### PostgreSQL
+
+- Full connection pooling via `pg.Pool`
+- SSL auto-detection for cloud providers (Supabase, Render, Neon)
+- `pg_stat_statements` integration for slow query monitoring
+- VACUUM, ANALYZE, REINDEX maintenance operations
+
+### MySQL
+
+- Connection pooling via `mysql2`
+- Performance schema integration
+- ANALYZE, OPTIMIZE, CHECK table operations
+
+### SQLite
+
+- Synchronous operations (file-based)
+- WAL mode enabled by default
+- VACUUM, ANALYZE, INTEGRITY_CHECK support
+
+### MongoDB
+
+- Connection pooling via official MongoDB driver
+- JSON-based MQL queries
+- Automatic schema inference from documents
+- Compact, validate, reIndex maintenance operations
+- Profiler integration for slow query monitoring
+
+## Security Considerations
+
+- Parameterized queries prevent SQL injection
+- MongoDB queries are JSON-parsed, preventing injection
+- Connection credentials are never logged
+- Pool connections are properly cleaned up
+- SSL is auto-enabled for known cloud providers
+
+## Performance Notes
+
+- Connection pooling provides 5-10x speedup for repeated queries
+- Idle connections are automatically closed after 30 seconds
+- Query timeouts prevent runaway queries
+- Schema queries are optimized with LIMIT clauses
+- MongoDB uses estimated document counts for performance

package/docs/FEATURES.md

@@ -0,0 +1,116 @@
+# LibreDB Studio Expert Features
+
+## 🚀 Implemented Features
+
+  ### 1. Monaco SQL IDE Experience
+  *   **VS Code Engine:** Integrated Monaco Editor for a professional coding environment.
+  *   **Pro SQL Autocomplete:** Advanced schema-aware completion for tables, columns (`table.col`), SQL keywords, and built-in functions.
+  *   **SQL Formatter:** Built-in "Format" button and `Alt + Shift + F` shortcut for clean, readable SQL code.
+  *   **Custom DB Theme:** Specialized `db-dark` theme for high-contrast SQL syntax highlighting.
+  *   **Power Snippets:** Integrated templates for CTEs, Joins, and complex CRUD operations.
+  *   **Modern Editor Specs:** Font ligatures, smooth scrolling, bracket pair colorization, and parameter hints enabled.
+  *   **Keyboard Shortcuts:** `Cmd/Ctrl + Enter` to execute, `Alt + Shift + F` to format.
+
+### 2. Multi-Tab Query Management
+*   **Workspace Tabs:** Open multiple queries simultaneously in separate tabs.
+*   **Independent Results:** Each tab maintains its own execution state and results grid.
+*   **Persistent Tabs:** Switch between tasks without losing your work.
+
+### 3. Pro Data Grid (Excel-Style)
+*   **High Performance:** Virtualized rendering using TanStack Virtual for smooth scrolling through millions of rows.
+*   **Inline Editing:** Double-click any cell to edit data directly (coming soon: batch save).
+*   **Data-Type Formatting:** Specialized rendering for Numbers, Booleans, and Nulls.
+*   **Column Management:** Resizable columns and advanced sorting.
+
+### 4. Smart SQL Toolbar
+*   **One-Click Snippets:** Quick access to common SQL commands (`SELECT`, `JOIN`, `WHERE`, `INSERT`, etc.).
+*   **Mobile Optimized:** Touch-friendly buttons for easy SQL writing on the go.
+
+  ### 5. Visual EXPLAIN (Query Analyzer)
+  *   **Performance Visualization:** Visual execution plan to identify performance bottlenecks.
+  *   **Detailed Metrics:** Graphical representation of database scan types, join operations, costs, and execution times.
+  *   **Multi-DB Support:** Optimized for PostgreSQL and MySQL query plans.
+  
+  ### 6. AI Query Assistant (Gemini 2.5 Flash)
+    *   **Natural Language to SQL:** Convert natural language requests into high-precision SQL code.
+    *   **AI SQL Explanation:** One-click "AI Explain" button to translate complex SQL logic into plain English for easier debugging and onboarding.
+    *   **Schema-Aware Generation:** AI automatically understands your tables and columns for accurate query generation.
+    *   **Interactive UI:** Floating `⌘+K` style command bar for a seamless "AI-first" workflow.
+    *   **Streaming Responses:** Real-time SQL generation using the latest Gemini models.
+
+  ### 7. Multi-Database Engine Support
+  *   **Strategy Pattern Architecture:** Modular, extensible database provider system with clear separation by database category.
+  *   **SQL Databases:**
+      *   **PostgreSQL:** Full support with connection pooling (`pg`), schema inspection, and maintenance tools.
+      *   **MySQL:** Full support with connection pooling (`mysql2`), performance schema integration.
+      *   **SQLite:** File-based database support (`better-sqlite3`) with WAL mode.
+      *   **Oracle:** Full support with connection pooling (`oracledb`), performance schema integration.
+      *   **SQL Server:** Full support with connection pooling (`mssql`), performance schema integration.
+  *   **Document Databases:**
+      *   **MongoDB:** Full support with official driver, JSON-based MQL queries, automatic schema inference, and aggregation pipelines.
+  *   **Connection Pooling:** Configurable pool settings (min/max connections, idle timeout) for production workloads.
+  *   **Query Timeout:** 60-second default timeout with per-provider configuration.
+
+  ### 8. Database Health Dashboard (Live Stats)
+  *   **Real-time Monitoring:** Track active connections, database size, and cache hit ratios.
+  *   **Performance Insights:** Automatic detection of the slowest queries in your database.
+  *   **Session Management:** View and monitor active database sessions and their current states.
+  *   **Visual Gauges:** Intuitive dashboards for quick health assessments.
+
+    ### 8. Advanced Schema Explorer (2025 Edition)
+    *   **Deep Tree Inspection:** Expand tables to view column definitions, data types, and Primary Key (PK) constraints with intuitive iconography.
+    *   **Global Search & Filter:** Real-time, high-performance filtering across both table names and column names.
+    *   **Precision Row Counts:** Optimized PostgreSQL integration using `pg_class` statistics for fast, accurate (estimated) row counts even on large datasets.
+    *   **Visual Table Designer:** Create new tables directly from the explorer with a modern, column-based UI. No SQL knowledge required for basic structures.
+    *   **Contextual Actions:** Quick access menus for each table including "Select Top 100", "Generate Template Query", and "Copy Name".
+    *   **DBA Quick Tools:** (Admin Only) Instant access to "Analyze Table" and "Vacuum Table" directly from the table context menu.
+    *   **Visual Clarity:** Modern glassmorphic design with Framer Motion animations for smooth transitions.
+    *   **Database Stats:** Integrated table counts and connection health monitoring directly in the sidebar.
+
+    ### 9. DBA Maintenance Toolkit (Admin Exclusive)
+    *   **Centralized Control Panel:** Dedicated "Database Maintenance" modal for high-level administration tasks.
+    *   **Global Optimizations:** Trigger database-wide `ANALYZE`, `VACUUM`, and `REINDEX` operations to maintain peak performance.
+    *   **Live Session Management:** Real-time monitoring of active database PIDs (Process IDs).
+    *   **Process Termination:** Ability to safely terminate (kill) hung or resource-intensive queries with a single click.
+    *   **Health Dashboard Integration:** Real-time feedback on connection states and session durations.
+
+    ### 10. AI Reliability & Error Management
+  *   **Intelligent Error Handling:** Comprehensive English error messages for API quotas, rate limits, and service availability issues.
+  *   **Modern Alert UI:** Dedicated error notification system within the AI panel for immediate developer feedback.
+  *   **Graceful Degradation:** Robust backend logic to handle API timeouts and authentication failures without crashing the UI.
+
+  ### 10. DevOps & Enterprise Deployment
+  *   **Containerization Ready:** Optimized Dockerfile using multi-stage Bun builds for minimal image size.
+  *   **Kubernetes Support:** Pre-configured `standalone` Next.js mode for efficient production orchestration.
+  *   **Local Development Pro:** Integrated `docker-compose` setup for consistent environment across the entire team.
+
+  ### 11. Advanced Query History (DBA-Level)
+  *   **Full Audit Trail:** Searchable history of every query executed, including SQL content, success status, and error details.
+  *   **Performance Tracking:** Precise execution time measurement (ms) for every query to identify slow operations.
+  *   **Metadata Insights:** Automatic tracking of execution timestamps and row counts for historical analysis.
+  *   **Instant Restore:** Re-run any previous query with a single click directly from the history panel.
+
+  ### 12. Saved Queries Library
+  *   **Query Repository:** Save complex queries with custom names, detailed descriptions, and organizational tags.
+  *   **Schema Filtering:** Automatically organizes queries based on the target database/schema to reduce clutter.
+  *   **Team Knowledge Base:** Centralized storage for frequently used business logic and maintenance scripts.
+
+  ### 13. Enterprise Results Hub
+  *   **Tabbed Workspace:** Professional interface managing Results, History, and Saved Queries in one unified panel.
+  *   **Live Metrics:** Real-time feedback on query performance and status directly in the results header.
+  *   **Editor Integration:** Seamlessly save current editor content or load previous scripts with dedicated UI controls.
+
+  ### 14. Professional Data Export
+  *   **Format Versatility:** Instantly export query result sets to CSV or JSON formats.
+  *   **Developer-Ready:** Clean data output optimized for external analysis, reporting, or database migrations.
+
+    ### 15. Authentication & Identity Management
+    *   **Secure User Onboarding:** Full-featured login/logout flows and session management via Next.js middleware and API routes.
+    *   **Context-Aware UI:** Personalized experience based on authenticated user state (e.g., "Me" endpoint integration).
+    *   **Enterprise Security First:** Environment variable protection with `.env.example` templates and strict Git tracking policies for credentials.
+
+    ## 🛠 Planned "Expert" Features
+    
+  ### 16. Visual Schema Explorer (ERD)
+*   Interactive Entity-Relationship diagrams.
+*   Drag-and-drop relationship mapping.