feat: v2.1.0 - Add full database backup management

[StuMason]

Features

Full Database Backup Control via MCP

Adds create/update/delete functionality to the database_backups tool, enabling complete backup lifecycle management through the MCP API.

New Capabilities

Create backups:

mcp__coolify__database_backups({
  action: 'create',
  database_uuid: 'xxx',
  frequency: 'daily',
  enabled: true,
  save_s3: true,
  s3_storage_uuid: 'xxx',
  database_backup_retention_days_locally: 7,
  database_backup_retention_days_s3: 7
})

Update backups:

mcp__coolify__database_backups({
  action: 'update',
  database_uuid: 'xxx',
  backup_uuid: 'xxx',
  database_backup_retention_days_s3: 30  // Change retention
})

Delete backups:

mcp__coolify__database_backups({
  action: 'delete',
  database_uuid: 'xxx',
  backup_uuid: 'xxx'
})

Changes

Types (src/types/coolify.ts)

• Updated CreateDatabaseBackupRequest with all retention parameters
• Added UpdateDatabaseBackupRequest interface

Client (src/lib/coolify-client.ts)

• Added createDatabaseBackup() method
• Added updateDatabaseBackup() method
• Added deleteDatabaseBackup() method

MCP Tool (src/lib/mcp-server.ts)

• Expanded database_backups tool with create/update/delete actions
• Added all backup configuration parameters:
  • frequency, enabled, save_s3, s3_storage_uuid
  • database_backup_retention_days_locally/s3
  • database_backup_retention_amount_locally/s3
  • databases_to_backup, dump_all

Testing

• ✅ All existing tests pass
• ✅ Build successful
• ✅ TypeScript types validated

Version

2.0.0 → 2.1.0 (minor bump for new features)

Use Case

This enables automated backup management for databases, allowing users to:

• Set up daily backups with 7-day retention to R2/S3
• Manage backup schedules programmatically
• Clean up old backup configurations

Tested during emergency database recovery scenario where automated backups would have prevented data loss.

[claude]

PR Review: feat: v2.1.0 - Add full database backup management

Summary

This PR adds create/update/delete functionality to the database_backups tool, completing the CRUD operations for database backup management. The implementation follows existing patterns well and adds useful functionality.

---

Code Quality & Best Practices

Strengths:

• Follows the established pattern of consolidated tools with action parameters
• Types are well-defined and consistent with existing interfaces
• Client methods have explicit return types as required by the project standards
• Code style matches the existing codebase

Issues:

1. Missing tests for new client methods (src/lib/coolify-client.ts:968-993)

   The PR adds three new client methods but doesn't include corresponding tests:

   • createDatabaseBackup()
   • updateDatabaseBackup()
   • deleteDatabaseBackup()

   Per CLAUDE.md guidelines: "Add mocked test" is part of the workflow when adding new endpoints. The existing coolify-client.test.ts has tests for listDatabaseBackups, getDatabaseBackup, etc. The new methods should follow the same pattern.

2. Missing test coverage for new MCP tool actions (src/lib/mcp-server.test.ts)

   The test file should verify the new client methods exist:

   expect(typeof client.createDatabaseBackup).toBe('function');
   expect(typeof client.updateDatabaseBackup).toBe('function');
   expect(typeof client.deleteDatabaseBackup).toBe('function');

3. Documentation not updated (per CLAUDE.md requirements)

   • CHANGELOG.md - No entry for v2.1.0 changes
   • README.md - Tool count may need updating if this changes the count

---

Potential Bugs

1. Type mismatch in backupData destructuring (src/lib/mcp-server.ts:707)

   When destructuring args, backupData will include frequency even though it's handled separately for the create action:

   const { action, database_uuid, backup_uuid, execution_uuid, ...backupData } = args;

   Then in the create case:

   this.client.createDatabaseBackup(database_uuid, {
     ...backupData,
     frequency: args.frequency!,  // frequency is already in backupData
   });

   This isn't a bug per se (the explicit frequency will override), but it's cleaner to exclude frequency from the spread or not spread it at all for the create case.

2. OpenAPI spec validation concern

   The database backup endpoints (POST /databases/{uuid}/backups, PATCH /databases/{uuid}/backups/{backup_uuid}, DELETE /databases/{uuid}/backups/{backup_uuid}) are not documented in docs/openapi-chunks/databases-api.yaml.

   Per CLAUDE.md: "Verify endpoint exists in docs/openapi-chunks/" should be done before adding. This could mean either:

   • The OpenAPI docs are outdated (likely)
   • These endpoints may not exist in all Coolify versions

   Consider adding a note in the PR about which Coolify version introduced these endpoints.

---

Performance Considerations

No performance concerns - the implementation is straightforward HTTP calls with appropriate async handling.

---

Security Concerns

No security issues identified. The implementation:

• Uses proper authentication via the existing bearer token mechanism
• Doesn't expose sensitive data
• Follows the existing secure patterns

---

Test Coverage

Current state: Tests are missing for the new functionality.

Recommended additions to src/__tests__/coolify-client.test.ts:

it('should create a database backup', async () => {
  const mockBackup = { uuid: 'backup-uuid', frequency: '0 0 * * *' };
  mockFetch.mockResolvedValueOnce(mockResponse(mockBackup));

  const result = await client.createDatabaseBackup('db-uuid', {
    frequency: '0 0 * * *',
    enabled: true,
  });

  expect(result).toEqual(mockBackup);
  expect(mockFetch).toHaveBeenCalledWith(
    'http://localhost:3000/api/v1/databases/db-uuid/backups',
    expect.objectContaining({ method: 'POST' }),
  );
});

it('should update a database backup', async () => {
  mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Backup updated' }));

  const result = await client.updateDatabaseBackup('db-uuid', 'backup-uuid', {
    enabled: false,
  });

  expect(mockFetch).toHaveBeenCalledWith(
    'http://localhost:3000/api/v1/databases/db-uuid/backups/backup-uuid',
    expect.objectContaining({ method: 'PATCH' }),
  );
});

it('should delete a database backup', async () => {
  mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Backup deleted' }));

  const result = await client.deleteDatabaseBackup('db-uuid', 'backup-uuid');

  expect(mockFetch).toHaveBeenCalledWith(
    'http://localhost:3000/api/v1/databases/db-uuid/backups/backup-uuid',
    expect.objectContaining({ method: 'DELETE' }),
  );
});

---

Minor Suggestions

1. Consider adding validation for retention values - The API accepts negative numbers which likely makes no sense. While this is server-side validation territory, a quick check could improve UX.

2. Tool description could be more descriptive - The current description 'Manage backups: list_schedules/get_schedule/list_executions/get_execution/create/update/delete' is functional but dense. Consider grouping: 'Manage backups: list/get schedules and executions, create/update/delete schedules'

---

Verdict

Approve with minor changes requested

The core implementation is solid and follows project patterns well. The main gap is missing tests and documentation updates. Once those are addressed, this is ready to merge.

Required before merge:

1. Add tests for new client methods in coolify-client.test.ts
2. Update mcp-server.test.ts to verify new methods exist
3. Add CHANGELOG.md entry for v2.1.0

Nice to have:

• Note about Coolify API version compatibility

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.00%. Comparing base (283ec9c) to head (0c18464).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #60      +/-   ##
==========================================
+ Coverage   89.91%   90.00%   +0.08%     
==========================================
  Files           1        1              
  Lines         357      360       +3     
  Branches       95       95              
==========================================
+ Hits          321      324       +3     
  Misses          8        8              
  Partials       28       28              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.