@neverinfamous/mysql-mcp 2.1.0

package/src/adapters/mysql/tools/performance/__tests__/analysis.test.ts

@@ -0,0 +1,302 @@
+/**
+ * mysql-mcp - Performance Analysis Tools Unit Tests
+ * 
+ * Comprehensive tests for analysis.ts module functions.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+    createExplainTool,
+    createExplainAnalyzeTool,
+    createSlowQueriesTool,
+    createQueryStatsTool,
+    createIndexUsageTool,
+    createTableStatsTool,
+    createBufferPoolStatsTool,
+    createThreadStatsTool
+} from '../analysis.js';
+import type { MySQLAdapter } from '../../../MySQLAdapter.js';
+import { createMockMySQLAdapter, createMockRequestContext, createMockQueryResult } from '../../../../../__tests__/mocks/index.js';
+
+describe('Performance Analysis Tools', () => {
+    let mockAdapter: ReturnType<typeof createMockMySQLAdapter>;
+    let mockContext: ReturnType<typeof createMockRequestContext>;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockAdapter = createMockMySQLAdapter();
+        mockContext = createMockRequestContext();
+    });
+
+    describe('createExplainTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createExplainTool(mockAdapter as unknown as MySQLAdapter);
+
+            expect(tool.name).toBe('mysql_explain');
+            expect(tool.group).toBe('performance');
+            expect(tool.requiredScopes).toContain('read');
+            expect(tool.annotations?.readOnlyHint).toBe(true);
+        });
+
+        it('should run EXPLAIN for query', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([{
+                id: 1, select_type: 'SIMPLE', table: 'users', type: 'ALL'
+            }]));
+
+            const tool = createExplainTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ query: 'SELECT * FROM users', format: 'TRADITIONAL' }, mockContext);
+
+            expect(mockAdapter.executeReadQuery).toHaveBeenCalledWith('EXPLAIN SELECT * FROM users');
+            expect(result).toHaveProperty('plan');
+        });
+
+        it('should run EXPLAIN with TREE format', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([{
+                EXPLAIN: '-> Table scan on users  (cost=1.00 rows=100)'
+            }]));
+
+            const tool = createExplainTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ query: 'SELECT * FROM users', format: 'TREE' }, mockContext);
+
+            expect(mockAdapter.executeReadQuery).toHaveBeenCalledWith('EXPLAIN FORMAT=TREE SELECT * FROM users');
+            expect(result).toHaveProperty('plan');
+        });
+
+        it('should run EXPLAIN with JSON format', async () => {
+            const mockPlan = {
+                query_block: {
+                    select_id: 1,
+                    table: { table_name: 'users', access_type: 'ALL' }
+                }
+            };
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([{
+                EXPLAIN: JSON.stringify(mockPlan)
+            }]));
+
+            const tool = createExplainTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ query: 'SELECT * FROM users', format: 'JSON' }, mockContext) as { plan: unknown };
+
+            expect(mockAdapter.executeReadQuery).toHaveBeenCalledWith('EXPLAIN FORMAT=JSON SELECT * FROM users');
+            expect(result.plan).toEqual(mockPlan);
+        });
+
+        it('should fall back to raw rows if JSON parsing fails or not string', async () => {
+            const mockRows = [{ EXPLAIN: null }];
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult(mockRows));
+
+            const tool = createExplainTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ query: 'SELECT * FROM users', format: 'JSON' }, mockContext) as { plan: unknown };
+
+            expect(result.plan).toBe(mockRows);
+        });
+    });
+
+    describe('createExplainAnalyzeTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createExplainAnalyzeTool(mockAdapter as unknown as MySQLAdapter);
+
+            expect(tool.name).toBe('mysql_explain_analyze');
+            expect(tool.group).toBe('performance');
+            expect(tool.requiredScopes).toContain('read');
+        });
+
+        it('should run EXPLAIN ANALYZE', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([{
+                EXPLAIN: '-> Table scan on users  (actual time=0.05..0.10 rows=100 loops=1)'
+            }]));
+
+            const tool = createExplainAnalyzeTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ query: 'SELECT * FROM users' }, mockContext);
+
+            expect(mockAdapter.executeReadQuery).toHaveBeenCalledWith('EXPLAIN ANALYZE FORMAT=TREE SELECT * FROM users');
+            expect(result).toHaveProperty('analysis');
+        });
+
+        it('should handle JSON format for EXPLAIN ANALYZE', async () => {
+            const mockAnalysis = { query_block: { table: { table_name: 't1' } } };
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([{
+                EXPLAIN: JSON.stringify(mockAnalysis)
+            }]));
+
+            const tool = createExplainAnalyzeTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ query: 'SELECT 1', format: 'JSON' }, mockContext) as { analysis: unknown };
+
+            expect(mockAdapter.executeReadQuery).toHaveBeenCalledWith('EXPLAIN ANALYZE FORMAT=JSON SELECT 1');
+            expect(result.analysis).toEqual(mockAnalysis);
+        });
+    });
+
+    describe('createSlowQueriesTool', () => {
+        it('should query performance_schema for slow queries', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([{
+                query: 'SELECT * FROM big_table',
+                executions: 5,
+                avg_time_ms: 1000
+            }]));
+
+            const tool = createSlowQueriesTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ limit: 5 }, mockContext);
+
+            expect(mockAdapter.executeReadQuery).toHaveBeenCalled();
+            const call = mockAdapter.executeReadQuery.mock.calls[0][0] as string;
+            expect(call).toContain('events_statements_summary_by_digest');
+            expect(call).toContain('LIMIT 5');
+            expect(result).toHaveProperty('slowQueries');
+        });
+
+        it('should filter by minTime', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createSlowQueriesTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({ limit: 10, minTime: 0.5 }, mockContext);
+
+            const call = mockAdapter.executeReadQuery.mock.calls[0][0] as string;
+            // 0.5 sec = 500,000,000 picoseconds? No, performance_schema uses picoseconds usually, 
+            // the code multiplies by 1,000,000,000 (10^9), suggesting nanoseconds or something. 
+            // Wait, TIMER_WAIT is usually picoseconds (10^-12). 10^9 conversion suggests seconds?
+            // Code: AVG_TIMER_WAIT > ${minTime * 1000000000}
+            expect(call).toContain('AVG_TIMER_WAIT > 500000000');
+        });
+    });
+
+    describe('createQueryStatsTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createQueryStatsTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_query_stats');
+        });
+
+        it('should order by total_time by default', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createQueryStatsTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({}, mockContext);
+
+            const call = mockAdapter.executeReadQuery.mock.calls[0][0] as string;
+            expect(call).toContain('ORDER BY SUM_TIMER_WAIT DESC');
+        });
+
+        it('should order by executions when requested', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createQueryStatsTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({ orderBy: 'executions' }, mockContext);
+
+            const call = mockAdapter.executeReadQuery.mock.calls[0][0] as string;
+            expect(call).toContain('ORDER BY COUNT_STAR DESC');
+        });
+
+        it('should order by avg_time when requested', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createQueryStatsTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({ orderBy: 'avg_time' }, mockContext);
+
+            const call = mockAdapter.executeReadQuery.mock.calls[0][0] as string;
+            expect(call).toContain('ORDER BY AVG_TIMER_WAIT DESC');
+        });
+    });
+
+    describe('createIndexUsageTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createIndexUsageTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_index_usage');
+        });
+
+        it('should query index usage stats', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createIndexUsageTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({}, mockContext);
+
+            expect(mockAdapter.executeReadQuery).toHaveBeenCalled();
+            const call = mockAdapter.executeReadQuery.mock.calls[0][0] as string;
+            expect(call).toContain('table_io_waits_summary_by_index_usage');
+            expect(result).toHaveProperty('indexUsage');
+        });
+
+        it('should filter by table name', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createIndexUsageTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({ table: 'users' }, mockContext);
+
+            const call = mockAdapter.executeReadQuery.mock.calls[0][0] as string;
+            expect(call).toContain('object_name = ?');
+            const args = mockAdapter.executeReadQuery.mock.calls[0][1];
+            expect(args).toEqual(['users']);
+        });
+    });
+
+    describe('createTableStatsTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createTableStatsTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_table_stats');
+        });
+
+        it('should query table statistics', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([{
+                table_name: 'users',
+                estimated_rows: 1000
+            }]));
+
+            const tool = createTableStatsTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ table: 'users' }, mockContext) as { stats: unknown };
+
+            expect(mockAdapter.executeReadQuery).toHaveBeenCalled();
+            const call = mockAdapter.executeReadQuery.mock.calls[0][0] as string;
+            expect(call).toContain('information_schema.TABLES');
+            expect(result.stats).toBeDefined();
+        });
+
+        it('should return undefined stats if table not found', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createTableStatsTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ table: 'nonexistent' }, mockContext) as { stats: unknown };
+
+            expect(result.stats).toBeUndefined();
+        });
+    });
+
+    describe('createBufferPoolStatsTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createBufferPoolStatsTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_buffer_pool_stats');
+        });
+
+        it('should query buffer pool stats', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([{
+                POOL_ID: 0,
+                POOL_SIZE: 8192
+            }]));
+
+            const tool = createBufferPoolStatsTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({}, mockContext);
+
+            expect(mockAdapter.executeReadQuery).toHaveBeenCalledWith('SELECT * FROM information_schema.INNODB_BUFFER_POOL_STATS');
+            expect(result).toHaveProperty('bufferPoolStats');
+        });
+    });
+
+    describe('createThreadStatsTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createThreadStatsTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_thread_stats');
+        });
+
+        it('should query thread stats', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([{
+                THREAD_ID: 1,
+                NAME: 'thread/sql/one_connection'
+            }]));
+
+            const tool = createThreadStatsTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({}, mockContext);
+
+            expect(mockAdapter.executeReadQuery).toHaveBeenCalled();
+            const call = mockAdapter.executeReadQuery.mock.calls[0][0] as string;
+            expect(call).toContain('performance_schema.threads');
+            expect(result).toHaveProperty('threads');
+        });
+    });
+});

package/src/adapters/mysql/tools/performance/__tests__/optimization.test.ts

@@ -0,0 +1,201 @@
+/**
+ * mysql-mcp - Performance Optimization Tools Unit Tests
+ * 
+ * Comprehensive tests for optimization.ts module functions.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+    createIndexRecommendationTool,
+    createQueryRewriteTool,
+    createForceIndexTool,
+    createOptimizerTraceTool
+} from '../optimization.js';
+import type { MySQLAdapter } from '../../../MySQLAdapter.js';
+import { createMockMySQLAdapter, createMockRequestContext, createMockQueryResult, createMockTableInfo } from '../../../../../__tests__/mocks/index.js';
+
+describe('Performance Optimization Tools', () => {
+    let mockAdapter: ReturnType<typeof createMockMySQLAdapter>;
+    let mockContext: ReturnType<typeof createMockRequestContext>;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockAdapter = createMockMySQLAdapter();
+        mockContext = createMockRequestContext();
+    });
+
+    describe('createIndexRecommendationTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createIndexRecommendationTool(mockAdapter as unknown as MySQLAdapter);
+
+            expect(tool.name).toBe('mysql_index_recommendation');
+            expect(tool.group).toBe('optimization');
+            expect(tool.requiredScopes).toContain('read');
+        });
+
+        it('should recommend indexes for ID and foreign key columns', async () => {
+            const mockTableInfo = createMockTableInfo('orders');
+            mockTableInfo.columns = [
+                { name: 'id', type: 'int', nullable: false, primaryKey: true },
+                { name: 'user_id', type: 'int', nullable: false, primaryKey: false },
+                { name: 'status', type: 'varchar', nullable: false, primaryKey: false },
+                { name: 'created_at', type: 'datetime', nullable: false, primaryKey: false }
+            ];
+            mockAdapter.describeTable.mockResolvedValue(mockTableInfo);
+
+            // Return only primary key index
+            mockAdapter.getTableIndexes.mockResolvedValue([{
+                name: 'PRIMARY',
+                tableName: 'orders',
+                columns: ['id'],
+                unique: true,
+                type: 'BTREE'
+            }]);
+
+            const tool = createIndexRecommendationTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ table: 'orders' }, mockContext) as { recommendations: unknown[] };
+
+            expect(mockAdapter.describeTable).toHaveBeenCalledWith('orders');
+            expect(result.recommendations).toHaveLength(3);
+
+            // Check specific recommendations
+            const recs = result.recommendations as { column: string; reason: string }[];
+            expect(recs.find(r => r.column === 'user_id')).toBeDefined(); // Foreign key pattern
+            expect(recs.find(r => r.column === 'status')).toBeDefined();  // Status column
+            expect(recs.find(r => r.column === 'created_at')).toBeDefined(); // Timestamp
+        });
+
+        it('should not recommend indexes for already indexed columns', async () => {
+            const mockTableInfo = createMockTableInfo('orders');
+            mockTableInfo.columns = [
+                { name: 'user_id', type: 'int', nullable: false, primaryKey: false }
+            ];
+            mockAdapter.describeTable.mockResolvedValue(mockTableInfo);
+
+            // user_id is already indexed
+            mockAdapter.getTableIndexes.mockResolvedValue([{
+                name: 'idx_user_id',
+                tableName: 'orders',
+                columns: ['user_id'],
+                unique: false,
+                type: 'BTREE'
+            }]);
+
+            const tool = createIndexRecommendationTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ table: 'orders' }, mockContext) as { recommendations: unknown[] };
+
+            expect(result.recommendations).toHaveLength(0);
+        });
+    });
+
+    describe('createQueryRewriteTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createQueryRewriteTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_query_rewrite');
+        });
+
+        it('should suggest optimizations for SELECT *', async () => {
+            const tool = createQueryRewriteTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ query: 'SELECT * FROM users' }, mockContext) as { suggestions: string[] };
+
+            expect(result.suggestions).toContain('Consider selecting only needed columns instead of SELECT *');
+        });
+
+        it('should suggest optimizations for missing LIMIT', async () => {
+            const tool = createQueryRewriteTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ query: 'SELECT id FROM users' }, mockContext) as { suggestions: string[] };
+
+            expect(result.suggestions).toContain('Consider adding LIMIT to prevent large result sets');
+        });
+
+        it('should suggest optimizations for leading wildcard LIKE', async () => {
+            const tool = createQueryRewriteTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ query: "SELECT id FROM users WHERE name LIKE '%Bob'" }, mockContext) as { suggestions: string[] };
+
+            expect(result.suggestions).toContain('Leading wildcard in LIKE prevents index usage; consider FULLTEXT search');
+        });
+
+        it('should return explain plan if possible', async () => {
+            mockAdapter.executeReadQuery.mockResolvedValue(createMockQueryResult([{
+                EXPLAIN: JSON.stringify({ query_block: {} })
+            }]));
+
+            const tool = createQueryRewriteTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ query: 'SELECT * FROM users' }, mockContext) as { explainPlan: unknown };
+
+            expect(mockAdapter.executeReadQuery).toHaveBeenCalled();
+            expect(result.explainPlan).toBeDefined();
+        });
+
+        it('should handle explain failure gracefully', async () => {
+            mockAdapter.executeReadQuery.mockRejectedValue(new Error('Explain failed'));
+
+            const tool = createQueryRewriteTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ query: 'SELECT * FROM users' }, mockContext) as { explainPlan: unknown };
+
+            expect(result.explainPlan).toBeUndefined();
+        });
+    });
+
+    describe('createForceIndexTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createForceIndexTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_force_index');
+        });
+
+        it('should rewrite query with FORCE INDEX', async () => {
+            const tool = createForceIndexTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({
+                table: 'users',
+                query: 'SELECT * FROM users WHERE id = 1',
+                indexName: 'PRIMARY'
+            }, mockContext) as { rewrittenQuery: string };
+
+            expect(result.rewrittenQuery).toBe('SELECT * FROM `users` FORCE INDEX (`PRIMARY`) WHERE id = 1');
+        });
+
+        it('should handle table name with backticks in query', async () => {
+            const tool = createForceIndexTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({
+                table: 'users',
+                query: 'SELECT * FROM `users` WHERE id = 1',
+                indexName: 'idx_name'
+            }, mockContext) as { rewrittenQuery: string };
+
+            expect(result.rewrittenQuery).toBe('SELECT * FROM `users` FORCE INDEX (`idx_name`) WHERE id = 1');
+        });
+    });
+
+    describe('createOptimizerTraceTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createOptimizerTraceTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_optimizer_trace');
+        });
+
+        it('should execute optimizer trace flow', async () => {
+            mockAdapter.executeReadQuery
+                .mockResolvedValueOnce(createMockQueryResult([])) // The query
+                .mockResolvedValueOnce(createMockQueryResult([{ TRACE: '{}' }])); // The trace
+
+            const tool = createOptimizerTraceTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ query: 'SELECT * FROM users' }, mockContext);
+
+            expect(mockAdapter.executeQuery).toHaveBeenNthCalledWith(1, 'SET optimizer_trace="enabled=on"');
+            expect(mockAdapter.executeReadQuery).toHaveBeenNthCalledWith(1, 'SELECT * FROM users');
+            expect(mockAdapter.executeReadQuery).toHaveBeenNthCalledWith(2, 'SELECT * FROM information_schema.OPTIMIZER_TRACE');
+            expect(mockAdapter.executeQuery).toHaveBeenNthCalledWith(2, 'SET optimizer_trace="enabled=off"');
+
+            expect(result).toHaveProperty('trace');
+        });
+
+        it('should disable optimizer trace even on error', async () => {
+            mockAdapter.executeReadQuery.mockRejectedValue(new Error('Query failed'));
+
+            const tool = createOptimizerTraceTool(mockAdapter as unknown as MySQLAdapter);
+
+            await expect(tool.handler({ query: 'SELECT * FROM users' }, mockContext)).rejects.toThrow('Query failed');
+
+            expect(mockAdapter.executeQuery).toHaveBeenCalledWith('SET optimizer_trace="enabled=off"');
+        });
+    });
+});