DNS Record Cache

Sloth Manager stores a local copy of all synced DNS records in backend/dns-cache.json. This document explains how the cache works, why it exists, and how to manage it.

Why a local cache?

Some DNS providers (notably Loopia) enforce strict API rate limits. Reading records directly from the provider API on every page load would quickly exhaust those limits. Instead, Sloth Manager separates reads from writes:

Reads always come from the local cache — instant, no API calls.
Writes (add, edit, delete) go directly to the provider API and immediately update the cache.
Sync is the only action that calls the provider API to fetch fresh records.

How it works

Syncing

Pressing ⟳ Sync on a zone sends a single request to the provider API, replaces all cached records for that zone, and records the sync timestamp. The cache is also updated from the Provider Overview page, where each zone has its own Sync button.

Writes

When you add, edit, or delete a record through the app, the change is applied to the provider immediately. The local cache is updated in the same request so the table stays accurate without needing a re-sync.

Zone names

The first time a zone is synced, its human-readable name (e.g. example.com) is stored alongside the records. This name is used in Gotify notifications. If a notification shows a raw zone ID instead of a domain name, syncing that zone will fix it.

Cache file structure

dns-cache.json is a plain JSON file stored in the backend/ folder:

{
  "cloudflare": {
    "abc123zoneId": {
      "zone_name": "example.com",
      "synced_at": "2026-06-01T12:00:00.000Z",
      "records": [
        {
          "id": "rec123",
          "type": "A",
          "name": "sub.example.com",
          "content": "1.2.3.4",
          "ttl": 3600,
          "priority": null
        }
      ]
    }
  },
  "loopia": { ... },
  "pihole": { ... },
  "azure":  { ... },
  "cpanel": { ... }
}

Each provider is a top-level key. Within each provider, zones are keyed by their provider-specific zone ID. Each zone stores the friendly name, the last sync timestamp, and the flat list of records.

Managing the cache

Clearing via the app

Go to ⚙️ Settings → Cache and press Clear Cache. This empties the entire cache file. All zones will show "Never synced" and will need to be re-synced before records are visible.

Clearing manually

Delete or empty backend/dns-cache.json. The backend does not need to be restarted — the file is read fresh on every request.

Clearing a single zone

The cache does not currently support clearing individual zones. The cleanest workaround is to sync the zone immediately after clearing the full cache, which repopulates just that zone.

Custom file location

Set DB_PATH in .env to store the cache somewhere else:

DB_PATH=/data/dns-cache.json

Important notes

The cache reflects the state of records at the time of the last sync. Changes made directly in the provider's dashboard (outside of Sloth Manager) will not appear until you sync.
Deleting the cache file does not affect any records at the provider — it only removes the local copy.
The cache is not encrypted. Do not store it in a publicly accessible location.
Record IDs are provider-specific. Cloudflare uses UUID strings, Loopia uses subdomain::lineNumber composites, Pi-hole uses dns::domain::ip composites, and so on. These IDs are internal to Sloth Manager and should not be relied upon externally.

3.5 KiB Raw Permalink Blame History