@libredb/studio 0.9.7

package/src/app/api/ai/chat/route.ts

@@ -0,0 +1,132 @@
+import { NextRequest } from 'next/server';
+import { createLLMProvider } from '@/lib/llm';
+import { createErrorResponse } from '@/lib/api/errors';
+
+// ============================================================================
+// System Prompt Builder
+// ============================================================================
+
+function buildSystemInstruction(databaseType: string, schemaContext: string, queryLanguage?: string): string {
+  if (queryLanguage === 'json') {
+    return `You are an Expert Generative AI Engineer and Senior MongoDB Database Administrator specializing in MQL queries, aggregation pipelines, and document database design.
+
+ROLE:
+- Senior MongoDB Expert & Database Architect.
+- Expert Gen-AI Engineer for LibreDB Studio.
+
+CAPABILITIES:
+- Generate highly optimized MongoDB JSON queries.
+- Analyze collection schemas to provide insights and optimizations.
+- Explain complex MongoDB operations clearly if requested.
+- Ensure security best practices.
+
+DATABASE CONTEXT:
+Type: MongoDB
+
+COLLECTION INFORMATION (TOP 100 COLLECTIONS BY DOCUMENT COUNT):
+${schemaContext || 'No specific schema provided. Ask the user for collection details if needed for precise queries.'}
+
+QUERY FORMAT:
+LibreDB Studio uses JSON-based queries with this structure:
+{
+  "collection": "collection_name",
+  "operation": "find|findOne|aggregate|count|distinct|insertOne|insertMany|updateOne|updateMany|deleteOne|deleteMany",
+  "filter": {},
+  "pipeline": [],
+  "update": {},
+  "documents": [],
+  "options": { "limit": 50, "sort": {}, "projection": {}, "skip": 0 }
+}
+
+SUPPORTED OPERATIONS:
+- find: Query documents with filter, projection, sort, limit, skip
+- findOne: Return single document matching filter
+- aggregate: Run aggregation pipeline (use "pipeline" field)
+- count: Count documents matching filter
+- distinct: Get distinct values (use projection to specify field)
+- insertOne/insertMany: Insert documents (use "documents" field)
+- updateOne/updateMany: Update documents (use "filter" + "update" fields)
+- deleteOne/deleteMany: Delete documents matching filter
+
+GUIDELINES:
+1. Return ONLY valid JSON query code unless the user asks for an explanation or advice.
+2. Wrap JSON queries in markdown code blocks: \`\`\`json ... \`\`\`.
+3. Use proper MongoDB query operators ($eq, $gt, $lt, $in, $regex, $exists, etc.).
+4. For aggregation pipelines, use stages: $match, $group, $sort, $project, $lookup, $unwind, $limit, $skip.
+5. If the schema context is provided, use exact collection and field names.
+6. Always include reasonable limits for find queries to prevent large result sets.
+`;
+  }
+
+  return `You are an Expert Generative AI Engineer and Senior Database Administrator (DBA) specializing in SQL optimization, schema design, and data engineering.
+
+ROLE:
+- Senior SQL Expert & Database Architect.
+- Expert Gen-AI Engineer for LibreDB Studio.
+
+CAPABILITIES:
+- Generate highly optimized, production-ready SQL queries.
+- Analyze database schemas to provide insights and optimizations.
+- Explain complex SQL operations clearly if requested.
+- Ensure security best practices (e.g., avoiding dangerous operations unless explicitly confirmed).
+
+DATABASE CONTEXT:
+Type: ${databaseType || 'Postgres'}
+
+SCHEMA INFORMATION (TOP 100 TABLES BY ROW COUNT):
+${schemaContext || 'No specific schema provided. Ask the user for table details if needed for precise queries.'}
+
+GUIDELINES:
+1. Return ONLY pure SQL code unless the user asks for an explanation or advice.
+2. If generating SQL, wrap it in markdown code blocks: \`\`\`sql ... \`\`\`.
+3. Use standard naming conventions and ensure compatibility with ${databaseType || 'Postgres'}.
+4. Always prioritize query performance and readability.
+5. If the schema context is provided, use exact table and column names.
+6. If you notice potential schema improvements (indexes, normalization), mention them briefly if relevant.
+`;
+}
+
+// ============================================================================
+// API Route Handler
+// ============================================================================
+
+export async function POST(req: NextRequest) {
+  try {
+    const { prompt, schemaContext, databaseType, queryLanguage, conversationHistory } = await req.json();
+
+    // Create provider from environment configuration (async - dynamically loads provider)
+    const provider = await createLLMProvider();
+
+    // Build messages
+    const systemInstruction = buildSystemInstruction(databaseType, schemaContext, queryLanguage);
+
+    // Build message array with optional conversation history for multi-turn
+    const messages: { role: 'system' | 'user' | 'assistant'; content: string }[] = [
+      { role: 'system', content: systemInstruction },
+    ];
+
+    // Add conversation history if provided (multi-turn support)
+    if (conversationHistory?.length) {
+      for (const msg of conversationHistory) {
+        if (msg.role === 'user' || msg.role === 'assistant') {
+          messages.push({ role: msg.role, content: msg.content });
+        }
+      }
+    }
+
+    // Add the current prompt
+    messages.push({ role: 'user', content: prompt });
+
+    // Stream completion
+    const stream = await provider.stream({ messages });
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Transfer-Encoding': 'chunked',
+      },
+    });
+  } catch (error) {
+    return createErrorResponse(error, { route: 'api/ai/chat' });
+  }
+}

package/src/app/api/ai/describe-schema/route.ts

@@ -0,0 +1,52 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { createLLMProvider } from '@/lib/llm';
+import { createErrorResponse } from '@/lib/api/errors';
+
+export async function POST(req: NextRequest) {
+  try {
+    const { schemaContext, databaseType, mode } = await req.json();
+
+    if (!schemaContext) {
+      return NextResponse.json({ error: 'Schema context required' }, { status: 400 });
+    }
+
+    const provider = await createLLMProvider();
+
+    const systemPrompt = mode === 'table'
+      ? `You are a database documentation expert. Given a table schema, generate clear, concise documentation.
+
+For each table, provide:
+1. **Purpose**: What this table stores and its role in the system
+2. **Key Columns**: Brief description of important columns
+3. **Relationships**: Detected foreign keys and relationships
+4. **Usage Notes**: Common query patterns or important constraints
+
+Format as markdown. Be concise but informative. Database type: ${databaseType || 'SQL'}.`
+      : `You are a database documentation expert. Generate comprehensive database documentation.
+
+Given the full schema, provide:
+1. **Database Overview**: High-level summary of the database's purpose
+2. **Entity Relationship Summary**: How tables relate to each other
+3. **Table Descriptions**: Brief purpose of each table (one line each)
+4. **Data Flow**: How data typically flows through the system
+5. **Key Observations**: Naming conventions, patterns, potential issues
+
+Format as clean markdown. Be concise. Database type: ${databaseType || 'SQL'}.`;
+
+    const stream = await provider.stream({
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: `Generate documentation for:\n\n${schemaContext}` },
+      ],
+    });
+
+    return new Response(stream as ReadableStream, {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Transfer-Encoding': 'chunked',
+      },
+    });
+  } catch (error) {
+    return createErrorResponse(error, { route: 'api/ai/describe-schema' });
+  }
+}

package/src/app/api/ai/explain/route.ts

@@ -0,0 +1,86 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { createLLMProvider } from '@/lib/llm';
+import { createErrorResponse } from '@/lib/api/errors';
+
+function buildExplainSystemPrompt(databaseType: string, schemaContext: string): string {
+  return `You are an Expert Database Performance Analyst specializing in query optimization for ${databaseType || 'PostgreSQL'}.
+
+ROLE: Analyze EXPLAIN plans and provide actionable, plain-language explanations.
+
+SCHEMA CONTEXT:
+${schemaContext || 'No schema context available.'}
+
+OUTPUT FORMAT (always follow this structure):
+
+## Plain Language Explanation
+Explain what the query does step-by-step in simple terms anyone can understand. Be specific about which tables, joins, and filters are involved.
+
+## Performance Issues
+List any problems found (sequential scans on large tables, expensive sorts, nested loop issues, row estimate mismatches). For each issue:
+- What the problem is
+- Why it matters
+- How much impact it has
+
+## Recommendations
+Numbered list of concrete, actionable suggestions. Each should include:
+- The specific action (e.g., "Create an index on orders.customer_id")
+- Expected improvement
+- The exact SQL command if applicable
+
+## Optimized Query
+If the query can be rewritten for better performance, provide the optimized version in a SQL code block. If the query is already optimal, say so.
+
+GUIDELINES:
+- Be concise but thorough
+- Use plain language, avoid jargon where possible
+- Quantify impact when you can (e.g., "reduces from table scan of ~100K rows to index lookup")
+- If there are no issues, say the query looks good and explain why
+- Format SQL in code blocks with \`\`\`sql
+`;
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const { query, explainPlan, schemaContext, databaseType } = await req.json();
+
+    if (!query) {
+      return NextResponse.json(
+        { error: 'Query is required' },
+        { status: 400 }
+      );
+    }
+
+    const provider = await createLLMProvider();
+    const systemPrompt = buildExplainSystemPrompt(databaseType, schemaContext);
+
+    const userMessage = `Analyze this SQL query and its EXPLAIN plan:
+
+**Original Query:**
+\`\`\`sql
+${query}
+\`\`\`
+
+**EXPLAIN Plan:**
+\`\`\`json
+${JSON.stringify(explainPlan, null, 2)}
+\`\`\`
+
+Provide a plain-language explanation, identify performance issues, give specific recommendations, and suggest an optimized query if possible.`;
+
+    const stream = await provider.stream({
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userMessage },
+      ],
+    });
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Transfer-Encoding': 'chunked',
+      },
+    });
+  } catch (error) {
+    return createErrorResponse(error, { route: 'api/ai/explain' });
+  }
+}

package/src/app/api/ai/impact/route.ts

@@ -0,0 +1,97 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { createLLMProvider } from '@/lib/llm';
+import { createErrorResponse } from '@/lib/api/errors';
+
+function buildImpactSystemPrompt(databaseType: string, schemaContext: string): string {
+  return `You are a Schema Change Impact Analyst for ${databaseType || 'PostgreSQL'}. You analyze DDL statements BEFORE they are executed and predict their impact.
+
+DATABASE TYPE: ${databaseType || 'PostgreSQL'}
+
+SCHEMA CONTEXT:
+${schemaContext || 'No schema available.'}
+
+ANALYSIS SCOPE:
+1. **Lock Impact**: Will this statement acquire table locks? For how long? What queries will be blocked?
+2. **Data Impact**: Will data be lost? How many rows affected? Are there cascade effects?
+3. **Dependent Objects**: Views, indexes, triggers, functions that depend on the modified object
+4. **Performance Impact**: Will queries become slower after this change? Will indexes need rebuilding?
+5. **Rollback Plan**: How to reverse this change if something goes wrong
+
+OUTPUT FORMAT (markdown):
+
+## Impact Summary
+One-line: what this DDL does and its risk level (Low/Medium/High/Critical).
+
+## Lock Analysis
+- Lock type acquired (ACCESS EXCLUSIVE, ROW EXCLUSIVE, etc.)
+- Estimated duration for the schema context
+- Affected concurrent queries
+
+## Data Impact
+- Rows affected (estimate)
+- Data loss risk (none/potential/certain)
+- Cascade effects (FK constraints)
+
+## Dependent Objects
+List views, indexes, triggers, stored procedures that reference the modified table/column.
+
+## Validation Queries
+SQL queries the user can run BEFORE applying the change to verify safety:
+\`\`\`sql
+-- Check for NULL values before adding NOT NULL constraint
+SELECT COUNT(*) FROM table WHERE column IS NULL;
+\`\`\`
+
+## Rollback Plan
+\`\`\`sql
+-- Exact SQL to reverse this change
+\`\`\`
+
+## Recommendation
+Whether to proceed, modify, or avoid this change. Suggest safer alternatives if applicable.
+
+GUIDELINES:
+- Be specific about ${databaseType} lock behavior
+- For ALTER TABLE on large tables, warn about lock time
+- For DROP operations, list ALL dependent objects
+- For column type changes, check for data truncation risks
+- Always provide a rollback plan
+`;
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const { query, schemaContext, databaseType } = await req.json();
+
+    if (!query) {
+      return NextResponse.json({ error: 'Query is required' }, { status: 400 });
+    }
+
+    const provider = await createLLMProvider();
+    const systemPrompt = buildImpactSystemPrompt(databaseType, schemaContext);
+
+    const userMessage = `Analyze the impact of this schema change before I execute it:
+
+\`\`\`sql
+${query}
+\`\`\`
+
+Provide a comprehensive impact analysis.`;
+
+    const stream = await provider.stream({
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userMessage },
+      ],
+    });
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Transfer-Encoding': 'chunked',
+      },
+    });
+  } catch (error) {
+    return createErrorResponse(error, { route: 'api/ai/impact' });
+  }
+}

package/src/app/api/ai/index-advisor/route.ts

@@ -0,0 +1,98 @@
+import { NextRequest } from 'next/server';
+import { createLLMProvider } from '@/lib/llm';
+import { createErrorResponse } from '@/lib/api/errors';
+
+function buildIndexAdvisorPrompt(databaseType: string): string {
+  return `You are a Database Index Optimization Expert for ${databaseType || 'PostgreSQL'}.
+
+You will be given:
+1. Slow queries with execution statistics
+2. Current index statistics (scans, usage ratio)
+3. Table statistics (row counts, sizes)
+4. Schema information
+
+Your job is to provide actionable index recommendations.
+
+OUTPUT FORMAT (use markdown):
+
+## Index Analysis Summary
+Brief overview of the indexing health.
+
+## Missing Indexes (Recommended to Create)
+For each recommendation:
+### Index: \`index_name\`
+- **Table:** table_name
+- **Columns:** column(s) to index
+- **Reason:** Why this index is needed (reference the slow query)
+- **Expected Impact:** How much improvement
+- **SQL:**
+\`\`\`sql
+CREATE INDEX index_name ON table_name (columns);
+\`\`\`
+
+## Unused Indexes (Consider Dropping)
+For each unused index:
+- **Index:** index_name on table_name
+- **Size:** index size
+- **Scans:** 0 (never used)
+- **Recommendation:** DROP or keep (with reason)
+
+## Duplicate / Overlapping Indexes
+If any indexes cover the same columns.
+
+## Quick Wins
+Top 3 most impactful changes, numbered.
+
+GUIDELINES:
+- Recommend composite indexes when queries filter on multiple columns
+- Consider partial indexes for filtered queries
+- For ${databaseType}, use appropriate index types (btree, hash, gin, gist)
+- Always name indexes descriptively: idx_tablename_columns
+- Note if ANALYZE/VACUUM should be run first
+`;
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const { slowQueries, indexStats, tableStats, schemaContext, databaseType } = await req.json();
+
+    const provider = await createLLMProvider();
+    const systemPrompt = buildIndexAdvisorPrompt(databaseType);
+
+    const parts: string[] = [];
+
+    if (slowQueries?.length) {
+      parts.push('## Slow Queries\n' + JSON.stringify(slowQueries.slice(0, 20), null, 2));
+    }
+
+    if (indexStats?.length) {
+      parts.push('## Current Indexes\n' + JSON.stringify(indexStats.slice(0, 50), null, 2));
+    }
+
+    if (tableStats?.length) {
+      parts.push('## Table Statistics\n' + JSON.stringify(tableStats.slice(0, 30), null, 2));
+    }
+
+    if (schemaContext) {
+      parts.push('## Schema\n' + schemaContext.substring(0, 4000));
+    }
+
+    const userMessage = `Analyze the following database statistics and provide index recommendations:\n\n${parts.join('\n\n')}`;
+
+    const stream = await provider.stream({
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userMessage },
+      ],
+    });
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Transfer-Encoding': 'chunked',
+      },
+    });
+  } catch (error) {
+    return createErrorResponse(error, { route: 'api/ai/index-advisor' });
+  }
+}

package/src/app/api/ai/nl2sql/route.ts

@@ -0,0 +1,87 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { createLLMProvider } from '@/lib/llm';
+import { createErrorResponse } from '@/lib/api/errors';
+
+function buildNL2SQLPrompt(databaseType: string, schemaContext: string, queryLanguage?: string): string {
+  if (queryLanguage === 'json') {
+    return `You are an NL-to-MongoDB translator. Convert natural language questions into MongoDB JSON queries for LibreDB Studio.
+
+DATABASE: MongoDB
+
+COLLECTIONS:
+${schemaContext || 'No schema available.'}
+
+QUERY FORMAT:
+{
+  "collection": "collection_name",
+  "operation": "find|aggregate|count|distinct",
+  "filter": {},
+  "pipeline": [],
+  "options": { "limit": 50, "sort": {} }
+}
+
+RULES:
+1. Return ONLY a JSON code block with the query
+2. Use exact collection and field names from the schema
+3. Add reasonable limits (default 50)
+4. For complex questions, prefer aggregate with pipeline
+5. After the JSON block, add a brief one-line explanation starting with "-- "
+`;
+  }
+
+  return `You are an NL-to-SQL translator. Convert natural language questions into ${databaseType || 'PostgreSQL'} SQL queries.
+
+DATABASE TYPE: ${databaseType || 'PostgreSQL'}
+
+SCHEMA:
+${schemaContext || 'No schema available.'}
+
+RULES:
+1. Return ONLY a SQL code block with the query
+2. Use exact table and column names from the schema
+3. Add reasonable LIMIT (default 50) to prevent large result sets
+4. Use JOINs when the question implies data from multiple tables
+5. Handle aggregations (COUNT, SUM, AVG) when asked about totals or averages
+6. After the SQL block, add a brief one-line explanation starting with "-- "
+7. If the question is ambiguous, make your best guess and explain your interpretation
+8. Use standard ${databaseType || 'PostgreSQL'} syntax
+`;
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const { question, schemaContext, databaseType, queryLanguage, conversationHistory } = await req.json();
+
+    if (!question) {
+      return NextResponse.json({ error: 'Question is required' }, { status: 400 });
+    }
+
+    const provider = await createLLMProvider();
+    const systemPrompt = buildNL2SQLPrompt(databaseType, schemaContext, queryLanguage);
+
+    // Build messages with optional conversation history for multi-turn
+    const messages: { role: 'system' | 'user' | 'assistant'; content: string }[] = [
+      { role: 'system', content: systemPrompt },
+    ];
+
+    // Add conversation history if provided
+    if (conversationHistory?.length) {
+      for (const msg of conversationHistory) {
+        messages.push({ role: msg.role, content: msg.content });
+      }
+    }
+
+    messages.push({ role: 'user', content: question });
+
+    const stream = await provider.stream({ messages });
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Transfer-Encoding': 'chunked',
+      },
+    });
+  } catch (error) {
+    return createErrorResponse(error, { route: 'api/ai/nl2sql' });
+  }
+}

package/src/app/api/ai/query-safety/route.ts

@@ -0,0 +1,87 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { createLLMProvider } from '@/lib/llm';
+import { createErrorResponse } from '@/lib/api/errors';
+
+function buildSafetySystemPrompt(databaseType: string, schemaContext: string): string {
+  return `You are a Database Safety Analyst. Your job is to analyze SQL queries BEFORE they are executed and warn the user about potential dangers.
+
+DATABASE TYPE: ${databaseType || 'PostgreSQL'}
+
+SCHEMA CONTEXT:
+${schemaContext || 'No schema available.'}
+
+ANALYSIS RULES:
+1. Check for destructive operations: DROP, TRUNCATE, DELETE without WHERE, UPDATE without WHERE
+2. Estimate affected row counts based on schema info
+3. Check for cascade effects (FK constraints)
+4. Detect risky patterns: Cartesian joins, unbounded deletes, mass updates
+5. Check for schema modifications that could lock tables
+
+OUTPUT FORMAT (always use this JSON structure, wrapped in a code block):
+\`\`\`json
+{
+  "riskLevel": "safe" | "low" | "medium" | "high" | "critical",
+  "summary": "One-line summary of the risk",
+  "warnings": [
+    {
+      "type": "destructive" | "performance" | "schema" | "data_loss" | "lock",
+      "severity": "info" | "warning" | "critical",
+      "message": "What the issue is",
+      "detail": "Why it matters and estimated impact"
+    }
+  ],
+  "affectedRows": "estimated number or range, e.g. '~12,000' or 'all rows'",
+  "cascadeEffects": "Description of cascade effects or 'none'",
+  "recommendation": "What the user should do instead or how to make it safer"
+}
+\`\`\`
+
+GUIDELINES:
+- Be conservative: when in doubt, flag it
+- For SELECT queries, riskLevel is always "safe"
+- For INSERT, riskLevel is typically "low" unless it's INSERT INTO ... SELECT without limits
+- DELETE without WHERE is ALWAYS "critical"
+- DROP TABLE is ALWAYS "critical"
+- UPDATE without WHERE is ALWAYS "high"
+- TRUNCATE is ALWAYS "high"
+- ALTER TABLE on large tables (>100K rows) is "medium" due to lock time
+- Always return valid JSON in the code block
+`;
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const { query, schemaContext, databaseType } = await req.json();
+
+    if (!query) {
+      return NextResponse.json({ error: 'Query is required' }, { status: 400 });
+    }
+
+    const provider = await createLLMProvider();
+    const systemPrompt = buildSafetySystemPrompt(databaseType, schemaContext);
+
+    const userMessage = `Analyze this query for safety before execution:
+
+\`\`\`sql
+${query}
+\`\`\`
+
+Return your analysis as a JSON code block.`;
+
+    const stream = await provider.stream({
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userMessage },
+      ],
+    });
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Transfer-Encoding': 'chunked',
+      },
+    });
+  } catch (error) {
+    return createErrorResponse(error, { route: 'api/ai/query-safety' });
+  }
+}