Backup and restore
What is in the database, how to back it up, and how to put it back
What is in the database
Everything you would miss lives in Postgres. Secrets live in .env. Back up both.
| Table | Holds |
|---|---|
categories | Your categories |
sources | One row per feed: URL, category, status, last fetch and last error |
items | One row per fetched item: title, link, summary, topics, media details, and the article text until retention clears it |
digests | Every generated digest: window, status, the digest text, model and token usage |
digest_items | The verdict and reason per item in each digest |
feedback | Your 👍/👎 and comments on item verdicts |
section_feedback | Your 👍/👎 and comments on section narratives |
preference_profile | The reader profile (one row) |
digest_schedule | The digest slot (one row) |
schema_migrations | Which migrations have been applied |
There is no export or import feature (no OPML); a database dump is the archive.
Back up
Dump the bundled database to a file on the host, and copy .env alongside it:
docker compose exec -T postgres pg_dump -U owly owly > owly-$(date +%F).sql
cp .env owly-$(date +%F).envAdjust the user and database name if you changed POSTGRES_USER or POSTGRES_DB. A cron line
that runs this nightly and keeps a few weeks of files is all the backup strategy a single-user
install needs:
15 3 * * * cd /path/to/owlypost && docker compose exec -T postgres pg_dump -U owly owly > backups/owly-$(date +\%F).sqlRestore
On a fresh machine, with the repository cloned and the saved .env in place:
docker compose up -d postgres
docker compose exec -T postgres psql -U owly owly < owly-2026-08-31.sql
docker compose up -dThe migrate service then runs and finds the schema already applied (or applies anything newer
than the dump). Your sources, digests, feedback and profile are back as they were.
External Postgres
If you pointed DATABASE_URL at a managed database, use that provider's backup and restore. The
tables above are all there is; nothing else needs to be saved.
About retention
The daily cleanup clears the full article text of items older than
ITEM_CONTENT_RETENTION_DAYS (default 30). That text is only ever used to write the summary, so a
backup taken later still contains everything the app shows. Set the variable to 0 to keep
article text forever. See Configuration.