runMaintenance method

Future<MaintenanceResult> runMaintenance({ Duration? ttl, })

Runs maintenance tasks to clean up expired cached data.

This method removes:

• Synced records cached more than cacheTtl ago (default: 60 days)
• Cached responses older than cacheTtl
• Expired file blobs, and blobs of records no longer cached

You can optionally override the TTL for this specific run. With a null TTL these steps are skipped.

Independent of the TTL, it applies maxFileCacheBytes and returns up to 16 MB of free database pages to the file system (databases created by 0.7.0 or later; see DataBase.compact).

Note: This only affects synced data. Unsynced local changes, local-only records, and pending deletions are preserved.

Example:

// Run maintenance with the default TTL (60 days)
final result = await client.runMaintenance();
print('Cleaned up ${result.totalDeleted} items');

// Run with a custom TTL
await client.runMaintenance(ttl: Duration(days: 7));

Implementation

Future<MaintenanceResult> runMaintenance({Duration? ttl}) async {
  final effectiveTtl = ttl ?? cacheTtl;
  var deletedRecords = 0, deletedResponses = 0, deletedFiles = 0;

  if (effectiveTtl == null) {
    logger.info('Maintenance: TTL is disabled (null), expiry skipped');
  } else {
    final cutoffDate = DateTime.now().toUtc().subtract(effectiveTtl);
    logger.info('Running maintenance (TTL: ${effectiveTtl.inDays} days)...');
    deletedRecords = await db.cleanupExpiredRecords(cutoffDate: cutoffDate);
    deletedResponses = await db.cleanupExpiredResponses(
      cutoffDate: cutoffDate,
    );
    deletedFiles = await db.cleanupExpiredFiles(orphanCutoff: cutoffDate);
  }
  final max = maxFileCacheBytes;
  final evicted = max == null
      ? (count: 0, bytes: 0, remaining: 0)
      : await _evictFiles(max);
  final releasedPages = await db.compact();

  final result = MaintenanceResult(
    deletedRecords: deletedRecords,
    deletedResponses: deletedResponses,
    deletedFiles: deletedFiles,
    evictedFiles: evicted.count,
    evictedBytes: evicted.bytes,
  );

  logger.info(
    'Maintenance complete: ${result.totalDeleted} items cleaned '
    'up ($deletedRecords records, $deletedResponses responses, '
    '$deletedFiles expired files, ${evicted.count} evicted files of '
    '${evicted.bytes} bytes, $releasedPages pages released)',
  );
  return result;
}