/**
* MySQL Group Replication Tools
*
* Tools for managing MySQL Group Replication.
* 5 tools total: status, members, primary, transactions, flow control.
*/
import { z } from 'zod';
import type { MySQLAdapter } from '../../MySQLAdapter.js';
import type { ToolDefinition, RequestContext } from '../../../../types/index.js';
// =============================================================================
// Schemas
// =============================================================================
const MemberSchema = z.object({
memberId: z.string().optional().describe('Filter by specific member UUID')
});
// =============================================================================
// Tool Creation Functions
// =============================================================================
/**
* Get Group Replication status
*/
export function createGRStatusTool(adapter: MySQLAdapter): ToolDefinition {
return {
name: 'mysql_gr_status',
title: 'MySQL Group Replication Status',
description: 'Get comprehensive Group Replication status including mode and member state.',
group: 'cluster',
inputSchema: z.object({}),
requiredScopes: ['read'],
annotations: {
readOnlyHint: true,
idempotentHint: true
},
handler: async (_params: unknown, _context: RequestContext) => {
// Check if GR is running
const pluginResult = await adapter.executeQuery("SELECT PLUGIN_STATUS FROM information_schema.PLUGINS WHERE PLUGIN_NAME = 'group_replication'");
if ((pluginResult.rows?.[0])?.['PLUGIN_STATUS'] !== 'ACTIVE') {
return { enabled: false, message: 'Group Replication plugin is not active' };
}
const statusResult = await adapter.executeQuery(`
SELECT
@@group_replication_group_name as groupName,
@@group_replication_single_primary_mode as singlePrimaryMode,
@@group_replication_local_address as localAddress,
@@group_replication_group_seeds as groupSeeds,
@@group_replication_bootstrap_group as bootstrapGroup
`);
const config = statusResult.rows?.[0];
// Get member status from performance_schema
const memberResult = await adapter.executeQuery(`
SELECT
CHANNEL_NAME,
MEMBER_ID,
MEMBER_HOST,
MEMBER_PORT,
MEMBER_STATE,
MEMBER_ROLE,
MEMBER_VERSION
FROM performance_schema.replication_group_members
`);
// Get local member info
const localResult = await adapter.executeQuery(`
SELECT @@server_uuid as serverUuid
`);
const localUuid = (localResult.rows?.[0])?.['serverUuid'] as string;
const members = memberResult.rows ?? [];
const localMember = members.find(m => (m)['MEMBER_ID'] === localUuid);
return {
enabled: members.length > 0,
groupName: config?.['groupName'] ?? null,
singlePrimaryMode: config?.['singlePrimaryMode'] === 1,
localAddress: config?.['localAddress'] ?? null,
localMember: localMember ?? null,
memberCount: members.length,
members: members.map(m => {
const member = m;
return {
id: member['MEMBER_ID'],
host: member['MEMBER_HOST'],
port: member['MEMBER_PORT'],
state: member['MEMBER_STATE'],
role: member['MEMBER_ROLE'],
version: member['MEMBER_VERSION'],
isLocal: member['MEMBER_ID'] === localUuid
};
})
};
}
};
}
/**
* Get Group Replication members
*/
export function createGRMembersTool(adapter: MySQLAdapter): ToolDefinition {
return {
name: 'mysql_gr_members',
title: 'MySQL GR Members',
description: 'List all Group Replication members with detailed state information.',
group: 'cluster',
inputSchema: MemberSchema,
requiredScopes: ['read'],
annotations: {
readOnlyHint: true,
idempotentHint: true
},
handler: async (params: unknown, _context: RequestContext) => {
const { memberId } = MemberSchema.parse(params);
// Check if GR is running
const pluginResult = await adapter.executeQuery("SELECT PLUGIN_STATUS FROM information_schema.PLUGINS WHERE PLUGIN_NAME = 'group_replication'");
if ((pluginResult.rows?.[0])?.['PLUGIN_STATUS'] !== 'ACTIVE') {
return { members: [], count: 0, message: 'Group Replication not active' };
}
let query = `
SELECT
m.MEMBER_ID as memberId,
m.MEMBER_HOST as host,
m.MEMBER_PORT as port,
m.MEMBER_STATE as state,
m.MEMBER_ROLE as role,
m.MEMBER_VERSION as version,
s.COUNT_TRANSACTIONS_IN_QUEUE as txInQueue,
s.COUNT_TRANSACTIONS_CHECKED as txChecked,
s.COUNT_CONFLICTS_DETECTED as conflictsDetected,
s.COUNT_TRANSACTIONS_ROWS_VALIDATING as rowsValidating
FROM performance_schema.replication_group_members m
LEFT JOIN performance_schema.replication_group_member_stats s
ON m.MEMBER_ID = s.MEMBER_ID
`;
const queryParams: unknown[] = [];
if (memberId) {
query += ' WHERE m.MEMBER_ID = ?';
queryParams.push(memberId);
}
const result = await adapter.executeQuery(query, queryParams);
return {
members: result.rows ?? [],
count: result.rows?.length ?? 0
};
}
};
}
/**
* Identify current primary
*/
export function createGRPrimaryTool(adapter: MySQLAdapter): ToolDefinition {
return {
name: 'mysql_gr_primary',
title: 'MySQL GR Primary',
description: 'Identify the current primary member in a single-primary GR cluster.',
group: 'cluster',
inputSchema: z.object({}),
requiredScopes: ['read'],
annotations: {
readOnlyHint: true,
idempotentHint: true
},
handler: async (_params: unknown, _context: RequestContext) => {
const result = await adapter.executeQuery(`
SELECT
MEMBER_ID as memberId,
MEMBER_HOST as host,
MEMBER_PORT as port,
MEMBER_STATE as state,
MEMBER_VERSION as version
FROM performance_schema.replication_group_members
WHERE MEMBER_ROLE = 'PRIMARY'
`);
const primary = result.rows?.[0];
// Check if we are the primary
const localResult = await adapter.executeQuery(
'SELECT @@server_uuid as serverUuid'
);
const localUuid = (localResult.rows?.[0])?.['serverUuid'];
return {
primary: primary ?? null,
hasPrimary: !!primary,
isLocalPrimary: primary?.['memberId'] === localUuid
};
}
};
}
/**
* Get transaction status
*/
export function createGRTransactionsTool(adapter: MySQLAdapter): ToolDefinition {
return {
name: 'mysql_gr_transactions',
title: 'MySQL GR Transactions',
description: 'Get Group Replication transaction statistics and pending transactions.',
group: 'cluster',
inputSchema: z.object({}),
requiredScopes: ['read'],
annotations: {
readOnlyHint: true,
idempotentHint: true
},
handler: async (_params: unknown, _context: RequestContext) => {
// Check if GR is running
const pluginResult = await adapter.executeQuery("SELECT PLUGIN_STATUS FROM information_schema.PLUGINS WHERE PLUGIN_NAME = 'group_replication'");
if ((pluginResult.rows?.[0])?.['PLUGIN_STATUS'] !== 'ACTIVE') {
return { memberStats: [], gtid: { executed: '', purged: '' }, message: 'Group Replication not active' };
}
// Get transaction statistics
const statsResult = await adapter.executeQuery(`
SELECT
MEMBER_ID as memberId,
COUNT_TRANSACTIONS_IN_QUEUE as txInQueue,
COUNT_TRANSACTIONS_CHECKED as txChecked,
COUNT_CONFLICTS_DETECTED as conflictsDetected,
COUNT_TRANSACTIONS_ROWS_VALIDATING as rowsValidating,
COUNT_TRANSACTIONS_REMOTE_IN_APPLIER_QUEUE as remoteInApplierQueue,
COUNT_TRANSACTIONS_REMOTE_APPLIED as remoteApplied,
COUNT_TRANSACTIONS_LOCAL_PROPOSED as localProposed,
COUNT_TRANSACTIONS_LOCAL_ROLLBACK as localRollback
FROM performance_schema.replication_group_member_stats
`);
// Get GTID info
const gtidResult = await adapter.executeQuery(`
SELECT
@@gtid_executed as gtidExecuted,
@@gtid_purged as gtidPurged
`);
const gtid = gtidResult.rows?.[0];
return {
memberStats: statsResult.rows ?? [],
gtid: {
executed: gtid?.['gtidExecuted'] ?? '',
purged: gtid?.['gtidPurged'] ?? ''
}
};
}
};
}
/**
* Get flow control statistics
*/
export function createGRFlowControlTool(adapter: MySQLAdapter): ToolDefinition {
return {
name: 'mysql_gr_flow_control',
title: 'MySQL GR Flow Control',
description: 'Get Group Replication flow control statistics and throttling info.',
group: 'cluster',
inputSchema: z.object({}),
requiredScopes: ['read'],
annotations: {
readOnlyHint: true,
idempotentHint: true
},
handler: async (_params: unknown, _context: RequestContext) => {
// Check if GR is running
const pluginResult = await adapter.executeQuery("SELECT PLUGIN_STATUS FROM information_schema.PLUGINS WHERE PLUGIN_NAME = 'group_replication'");
if ((pluginResult.rows?.[0])?.['PLUGIN_STATUS'] !== 'ACTIVE') {
return { configuration: {}, memberQueues: [], isThrottling: false, message: 'Group Replication not active' };
}
// Get flow control configuration
const configResult = await adapter.executeQuery(`
SELECT
@@group_replication_flow_control_mode as flowControlMode,
@@group_replication_flow_control_certifier_threshold as certifierThreshold,
@@group_replication_flow_control_applier_threshold as applierThreshold,
@@group_replication_flow_control_min_quota as minQuota,
@@group_replication_flow_control_min_recovery_quota as minRecoveryQuota,
@@group_replication_flow_control_max_quota as maxQuota
`);
const config = configResult.rows?.[0];
// Get current queue depths
const queueResult = await adapter.executeQuery(`
SELECT
MEMBER_ID as memberId,
COUNT_TRANSACTIONS_IN_QUEUE as certifyQueue,
COUNT_TRANSACTIONS_REMOTE_IN_APPLIER_QUEUE as applierQueue
FROM performance_schema.replication_group_member_stats
`);
// Determine if flow control is active
const isThrottling = (queueResult.rows ?? []).some(row => {
const r = row;
const certQueue = r['certifyQueue'] as number;
const appQueue = r['applierQueue'] as number;
const certThreshold = config?.['certifierThreshold'] as number ?? 25000;
const appThreshold = config?.['applierThreshold'] as number ?? 25000;
return certQueue > certThreshold || appQueue > appThreshold;
});
return {
configuration: config ?? {},
memberQueues: queueResult.rows ?? [],
isThrottling,
recommendation: isThrottling
? 'Flow control is active. Consider investigating slow members or adjusting thresholds.'
: 'Flow control is not currently throttling.'
};
}
};
}
