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 |
|
DuckDB |
Sites, accounts, API keys, folders, alerts, and model registry |
|
redb |
Monthly usage counters |
|
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:
Stop
antics.service.Copy
antics.duckdbandantics.duckdb.walaside (do not overwrite the only copy).Run
CHECKPOINTwith the DuckDB CLI against the live file (consolidates WAL).Start
antics.serviceand confirm/api/healthisstatus=okwith a realtotal_events, then hit the public share overview for the demo token.The fit worker reads
antics.snapshot.duckdb, not the live file.runmode retries a failed open on the next interval; restartantics-attention-fit-workeronly if the unit is down (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.
Schema generation 4#
Generation 4 adds a nullable bot_class column on events. The writer
appends that column. A binary from before this generation cannot append
to a file this release has opened. There is no downgrade path. Do not
point an older binary at the migrated file, and do not drop the column.
To run an older binary again, restore the backup taken before the upgrade.
See Backup and disaster recovery for snapshot and restore guidance.