Add InfluxDB 3 Enterprise Support for Database Retention Policy Configuration

[dburton-influxdata]

Add InfluxDB 3 Enterprise Support for Database Retention Policy Configuration

Summary

The update_database tool currently only supports InfluxDB Cloud Dedicated and Cloud Serverless, but does not support InfluxDB 3 Enterprise/Core. This enhancement request adds Enterprise support for configuring database retention policies via the /api/v3/configure/database/{name} HTTP endpoint.

Current Behavior

Error: Operation 'update_database' is not supported for Enterprise. 
Supported types: Cloud Dedicated, Cloud Serverless

Use Case / Real-World Scenario

While monitoring retention cleanup lag on an InfluxDB 3 Enterprise instance, we discovered a critical issue:

• Database: ev_cars
• Issue: No retention policy set (infinite retention)
• Impact: 2.4 years (884 days) of expired data accumulating in object storage
• Storage: 911.78 MB of data that should have been deleted
• Root Cause: retention_period_ns is NULL in system.databases

We attempted to use the MCP server to set a retention policy but discovered it's not supported for Enterprise. This forces users to:

1. Switch to CLI (influxdb3 configure database ev_cars --retention-period 90d)
2. Use HTTP API directly with curl
3. Manually construct API requests

This breaks the workflow and prevents automation via MCP tools.

Proposed Solution

1. Add Enterprise HTTP API Client Method

Add support for the Enterprise configuration API endpoint:

PATCH http://{host}:{port}/api/v3/configure/database/{database_name}
Body: { "retention_period_ns": <nanoseconds> }

2. Update update_database Tool

Modify the tool to detect instance type and route to appropriate endpoint:

async update_database(params: {
  name: string;
  retentionPeriod?: number;
  maxTables?: number;
  maxColumnsPerTable?: number;
  newName?: string;
  description?: string;
}) {
  const instanceType = await this.detectInstanceType();
  
  switch (instanceType) {
    case 'cloud-dedicated':
      // Existing Management API logic
      return this.updateCloudDedicatedDatabase(params);
      
    case 'cloud-serverless':
      // Existing Serverless API logic
      return this.updateServerlessDatabase(params);
      
    case 'enterprise':
    case 'core':
      // NEW: Enterprise Configure API logic
      return this.updateEnterpriseDatabase(params);
      
    default:
      throw new Error(`Unsupported instance type: ${instanceType}`);
  }
}

3. Enterprise-Specific Implementation

private async updateEnterpriseDatabase(params: {
  name: string;
  retentionPeriod?: number;
  // Enterprise only supports retention_period_ns
}) {
  const url = `${this.baseUrl}/api/v3/configure/database/${params.name}`;
  
  const body: any = {};
  if (params.retentionPeriod !== undefined) {
    body.retention_period_ns = params.retentionPeriod;
  }
  
  const response = await fetch(url, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${this.token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  });
  
  if (!response.ok) {
    throw new Error(`Failed to update database: ${response.statusText}`);
  }
  
  return await response.json();
}

API Reference

Enterprise/Core Endpoint

PATCH /api/v3/configure/database/{database_name}
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "retention_period_ns": 7776000000000000  // 90 days
}

Cloud Dedicated Endpoint (existing)

PATCH /api/v1/databases/{database_id}
Authorization: Bearer <management_token>
Content-Type: application/json

{
  "maxTables": 500,
  "maxColumnsPerTable": 200,
  "retentionPeriod": 7776000000000000
}

Cloud Serverless Endpoint (existing)

PATCH /api/v2/buckets/{bucket_id}
Authorization: Token <api_token>
Content-Type: application/json

{
  "name": "new-name",
  "description": "Updated description",
  "retentionRules": [{
    "type": "expire",
    "everySeconds": 7776000
  }]
}

Implementation Checklist

• Add Enterprise database update HTTP client method
• Update update_database tool to support Enterprise
• Add instance type detection for routing
• Add Enterprise-specific parameter validation (only retentionPeriod)
• Update tool description to include Enterprise
• Add tests for Enterprise database updates
• Update README with Enterprise examples
• Add CHANGELOG entry

Testing Plan

Manual Testing

// Test Enterprise retention policy update
await mcp.update_database({
  name: "ev_cars",
  retentionPeriod: 7776000000000000  // 90 days
});

// Verify via query
const result = await mcp.execute_query({
  database: "_internal",
  query: "SELECT database_name, retention_period_ns FROM system.databases WHERE database_name = 'ev_cars'"
});

Expected Results

• Database ev_cars should have retention_period_ns = 7776000000000000
• Compaction should begin marking old data for deletion
• Retention lag dashboard should show decreasing expired data count

Documentation Updates

README.md

Add Enterprise example:

#### Update Database Retention Policy (Enterprise)
\`\`\`typescript
// Set 90-day retention on Enterprise instance
await mcp.update_database({
  name: "my_database",
  retentionPeriod: 7776000000000000  // 90 days in nanoseconds
});
\`\`\`

Common Retention Periods

Duration	Nanoseconds
7 days	604,800,000,000,000
30 days	2,592,000,000,000,000
90 days	7,776,000,000,000,000
180 days	15,552,000,000,000,000
1 year	31,536,000,000,000,000

Related Files

• src/index.ts - Main MCP server implementation
• src/tools/ - Tool implementations
• README.md - Documentation
• CHANGELOG.md - Version history

Additional Context

This enhancement was discovered while building a Grafana dashboard to monitor retention cleanup lag:

• Dashboard: "InfluxDB 3 Retention Cleanup Lag Monitor"
• Plugin: Processing Engine plugin to export compaction metrics
• Discovery: 35 retention-expired run-sets with 2.4 years max age
• Root cause: No retention policy configured

The dashboard now shows database/table information for expired data, making it clear which databases need retention policies. However, setting policies requires leaving the MCP tool ecosystem.

Priority

High - This is a critical gap for Enterprise users who want to manage their databases programmatically via MCP tools.