Storage Layout and Migration Status#

Antics uses DuckDB analytics and redb control stores. There is no customer-run database cutover in the current release.

Persistent stores#

Purpose

Default path

Format

Analytics events and rollups

ANTICS_DATA_DIR/antics.duckdb

DuckDB

Sites, accounts, API keys, folders, alerts, and model registry

ANTICS_DATA_DIR/antics.redb

redb

Monthly usage counters

ANTICS_DATA_DIR/antics_usage.redb

redb

Set ANTICS_DUCKDB_PATH, ANTICS_CONTROL_PATH, or ANTICS_USAGE_PATH to override an individual path. A self-hosted deployment should keep all three stores on persistent storage and protect them as one operational dataset.

Health verification#

GET /api/health reports ingest, rollup, and snapshot state. Check that each snapshot store has a successful timestamp and a non-zero byte count, and that the ingest and rollup sections are not accumulating errors.

DuckDB can invalidate its in-process handle after a fatal query (for example an ART index delete failure) without crashing the HTTP process. When that happens, ingest probes return total_events: -1 and events_last_hour: -1. Health then sets status to error, sets duckdb_ok to false, and answers with HTTP 503 so golive smoke tests and external monitors (Zazu) treat the service as down instead of green.

Recovery for a file that still opens offline:

  1. Stop antics.service.

  2. Copy antics.duckdb and antics.duckdb.wal aside (do not overwrite the only copy).

  3. Run CHECKPOINT with the DuckDB CLI against the live file (consolidates WAL).

  4. Start antics.service and confirm /api/health is status=ok with a real total_events, then hit the public share overview for the demo token.

  5. Restart antics-attention-fit-worker if it failed while the snapshot was stale; the worker is deployed, not retired (see attention modeling docs).

Managed Antics applies storage migrations as part of service operation. A self-hosted operator should stop the service and preserve a consistent backup of all three stores before installing a release that changes the storage schema. Startup applies supported store migrations idempotently.

See Backup and disaster recovery for snapshot and restore guidance.