SnapAdmin

📦 Installation

SnapAdmin can be installed via PyPI or directly from source.

From PyPI

pip install django-snapadmin

From GitHub

pip install git+https://github.com/drofji/django-snapadmin.git

Compatibility

SnapAdmin requires Python ≥ 3.10 and Django ≥ 5.2 (no upper bound pinned). SnapAdmin is currently a pre-1.0 beta (Development Status :: 4 - Beta); semantic versioning begins once a future 1.0 ships — see SECURITY.md for the current API-stability policy. Pin an exact version in production regardless.

Async support

SnapModel.asave() / .adelete() / .arefresh_from_db() are Django's own native async model methods (available since Django 5.2) — SnapAdmin adds no code for them and needs none: each is a thin wrapper around the matching sync method (self.save() / self.delete() / self.refresh_from_db()), and Python resolves that through the instance's actual class, so they already reach SnapModel's own overrides — the Elasticsearch mirror and a wysiwyg field's sanitize-on-write run identically whether you call save() or await obj.asave(). EsManager / EsQuerySet (the Elasticsearch query layer for ES_ONLY models) gain aget() / afirst() / alast() to match — a DB-backed model already got these for free from Django's own QuerySet.

Out of scope, deliberately: async DRF ViewSets (DRF's own async support is still partial), an async Elasticsearch client (the bundled client is sync-only and would need its own wrapper), and bulk async operations (abulk_create / abulk_update). GraphQL resolvers need nothing extra — Graphene already handles async resolvers transparently.

Configuring INSTALLED_APPS

The Unfold theme is optional (pip install django-snapadmin[theme]) — with it you get the themed UI, without it SnapAdmin renders on Django's built-in admin. If you use Unfold, its contrib apps must come before django.contrib.admin. manage.py check surfaces the stock-admin fallback as one informational message (snapadmin.I001, never an error) so it is never silently mistaken for a bug.

INSTALLED_APPS = [
    # Optional theme — only with the [theme] extra; must precede django.contrib.admin
    "unfold",
    "unfold.contrib.filters",
    "unfold.contrib.forms",
    "unfold.contrib.inlines",

    # WYSIWYG — only with the [wysiwyg] extra (SnapRichTextField / wysiwyg=True)
    # "django_ckeditor_5",

    # Django core
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",

    # REST API — [api] extra; needed only with SNAPADMIN_REST_API_ENABLED/
    # SNAPADMIN_SWAGGER_ENABLED set to True (both default False)
    "rest_framework",
    "drf_spectacular",
    "django_filters",

    # GraphQL — [graphql] extra; needed only with SNAPADMIN_GRAPHQL_ENABLED = True
    # (default False). Independent of [api].
    "graphene_django",

    "snapadmin",

    # Optional — only with the [celery] extra
    # "django_celery_beat",
    # "django_celery_results",

    # Your apps …
]

A bare pip install django-snapadmin pulls only Django, structlog and nh3. djangorestframework, drf-spectacular and django-filter come via the [api] extra, and graphene-django via [graphql] — both features default to off (SNAPADMIN_REST_API_ENABLED / SNAPADMIN_GRAPHQL_ENABLED), so install pip install django-snapadmin[api,graphql] (or [all]) once you turn either on. Turning a feature on with its extra missing fails loudly, both at manage.py check (snapadmin.E010) and, if that step is skipped, the moment snapadmin.urls is imported. django-unfold is not installed by the base package — add the [theme] extra for the Unfold-themed admin; without it the admin renders on stock Django. django-ckeditor-5 is likewise not installed by default (it bundles CKEditor 5, a GPL/commercial editor) — add it via the [wysiwyg] extra only if you use rich-text fields.

snapadmin/
├── api/             # REST & GraphQL API core: views, serializers, auth
├── management/      # Custom management commands
├── migrations/      # Core package migrations (e.g. APIToken)
├── static/          # UI assets (CSS, JS, SVG logos)
├── templates/       # Custom admin templates & dashboard
├── fields.py        # SnapField definitions with admin introspection
├── models.py        # SnapModel base, EsManager, and core logic
└── urls.py          # Auto-configurable API and documentation routes

🏁 New Project — snapadmin-new

snapadmin-new (also python -m snapadmin.scaffold) generates a project you keep — not a throwaway (snapadmin-demo) and not a read-only report (snapadmin-init): manage.py, a settings package, one app carrying a worked SnapModel example, SQLite and a .env/dist.env. migrate then runserver work immediately — no Docker, no manual edits.

pip install django-snapadmin
snapadmin-new myshop
cd myshop
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Open http://127.0.0.1:8000/admin/ — the admin, the REST API (/api/docs/) and the GraphQL endpoint (/api/graphql/) are already wired to the worked Product model in catalog/models.py. Templates ship inside the wheel under snapadmin/scaffold/templates/ and render with the standard library's string.Template — no Jinja, no extra dependency.

Pass --full for the containerised stack — same project, plus a Dockerfile, docker-compose.yml and the PostgreSQL / Redis / Elasticsearch wiring (Postgres when POSTGRES_HOST is set, SQLite otherwise, so manage.py check/migrate still work with no services running):

snapadmin-new myshop --full
cd myshop
docker compose up --build

Flags

🩺 Integrate an existing project — snapadmin-init

Adding SnapAdmin to a project you already have means editing INSTALLED_APPS (with a specific ordering), urls.py, a settings block and your requirements. The snapadmin-init command (also python -m snapadmin.integrate) makes that trivial — and safe.

pip install django-snapadmin
snapadmin-init                    # a per-item present/missing checklist with snippets
snapadmin-init --api --graphql    # also check the REST / GraphQL configuration
snapadmin-init --json             # machine-readable, for your own tooling

For each item it reports ✓ already present or ✗ add this — followed by the block to paste:

• INSTALLED_APPS — the full list with snapadmin in place, and a note that the unfold theme is optional ([theme] extra) — if you use it, its apps must precede django.contrib.admin.
• URL routes — the include("snapadmin.urls") line, honouring --url-prefix.
• SnapAdmin settings — the SNAPADMIN_* feature-toggle block.
• REST / GraphQL config — with --api / --graphql.
• Install line — pip install django-snapadmin[extras] (--extras), and a warning if your requirements pin an incompatible Django.
• Model conversion (advisory) — lists files still subclassing models.Model and shows how to convert one to SnapModel.

Flags

✅ Integration Checklist

Installed doesn't mean correctly integrated. Every row below names the command that proves it — run it, don't take the row's word for it. Stop at whichever group matches where your project actually is; you don't need "Optional / scale" to ship a first version.

Must work

Should be configured before production

Data safety

Optional / scale

🔀 Two Ways to Declare a Model

New, greenfield model? Subclass SnapModel below — that's the full route. Existing models you can't or won't rewrite? @snap_model + snap_field() opt them in from the outside, with no migration.

Both routes end in the same registry — snapadmin.registry.is_registered(model) is the gate every surface asks — so switching later changes nothing else: apply @snap_model to a SnapModel subclass and it overrides exactly the keywords you pass, leaving the rest of the class-level configuration alone.

The same model, both ways

from snapadmin import models as snap_models, fields as snap

class Product(snap_models.SnapModel):
    name = snap.SnapCharField(max_length=200, searchable=True)
    price = snap.SnapDecimalField(max_digits=10, decimal_places=2, filterable=True)
    cost_price = snap.SnapDecimalField(max_digits=10, decimal_places=2)

    api_write_fields = ["name", "price"]
    api_exclude_fields = ["cost_price"]

from django.db import models
from snapadmin import snap_model
from snapadmin.fields import snap_field

@snap_model(
    api_write_fields=["name", "price"],
    api_exclude_fields=["cost_price"],
)
class Product(models.Model):
    name = snap_field(models.CharField(max_length=200), searchable=True)
    price = snap_field(models.DecimalField(max_digits=10, decimal_places=2), filterable=True)
    cost_price = models.DecimalField(max_digits=10, decimal_places=2)

Both register the same model, with the same API write allowlist and the same searchable/ filterable fields. Neither needs a migration: the decorator adds no field or attribute, and snap_field() sets its metadata after Django's Field.__init__ has already recorded its constructor arguments.

The honest comparison

The two routes are not identical — a decorated plain model does not attach SnapModel's runtime machinery, and the surfaces that need it skip a decorated model rather than half-work. This table states plainly which capability lives where; every ❌ links to the task tracking it, or is marked permanent with the reason.

Links onward: Snap Fields (the flags themselves) · snap_field() (the field-level wrapper) · Mixing Snap & plain fields (you never have to convert a whole model at once) · the decorator's full keyword table and precedence rule.

🏗 SnapModel

Subclass SnapModel and you get admin, search, GDPR retention and Elasticsearch mirroring for free — no extra code. Reach for it on a new model, when you want everything SnapAdmin can do.

from snapadmin import models as snap_models, fields as snap

class Product(snap_models.SnapModel):
    name = snap.SnapCharField(max_length=200, searchable=True)
    price = snap.SnapDecimalField(max_digits=10, decimal_places=2, filterable=True)
    available = snap.SnapBooleanField(default=True)

🔌 @snap_model — Plain Django Models

There are two ways to declare a SnapAdmin model. Subclassing SnapModel (above) is the full one. The @snap_model decorator is the other: it opts a plain django.db.models.Model in from the outside, without touching its field layer. Use it for a brownfield schema you cannot rewrite, a model whose base class belongs to a third-party package, or fields that come from packages like django-money, phonenumber_field or model-utils.

from django.db import models
from snapadmin import snap_model

@snap_model(
    api_write_fields=["name", "price"],   # mass-assignment allowlist
    api_exclude_fields=["cost_price"],    # never leaves the server
    search_fields=["name"],               # what ?search= matches on
)
class Product(models.Model):
    name = models.CharField(max_length=200)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    cost_price = models.DecimalField(max_digits=10, decimal_places=2)

The decorator adds no field and no attribute to the class, so it needs no migration. From then on the model is a SnapAdmin model everywhere the question is asked: the REST API mounts CRUD routes for it, the GraphQL schema gains a type, the offline endpoints and the snapadmin.W00x system checks see it, and snapadmin_info inventories it.

What a decorated model does not get — registration and metadata only, none of SnapModel's runtime machinery. See the full capability × door table, covering both the model and field halves, on Two Ways to Declare a Model.

The registry itself is public: snapadmin.registry.is_registered(model) is the gate every surface asks. Applying @snap_model to a SnapModel subclass overrides exactly the keywords you pass and leaves the rest of the class-level configuration alone.

📋 Snap Fields

Every Snap field is a drop-in replacement for the corresponding Django field, with extra admin control attributes.

^* show_in_form's False default is project-wide, not per-field: SNAPADMIN_SHOW_IN_FORM_DEFAULT raises it for every field that never sets it explicitly — useful when adopting SnapAdmin onto models that predate it, where nothing setting it anywhere used to mean every generated change form rendered empty (snapadmin.W015 now catches that whatever the cause). An explicit per-field show_in_form= always wins over the project-wide setting.

Wysiwyg HTML is sanitized on write and on render. Rich-text fields (wysiwyg=True / SnapRichTextField) hold HTML written by whoever can write the field — an API token, a low-privileged staff account, a bulk import — so their value goes through an HTML sanitizer (nh3) that strips <script>, inline event handlers and unsafe URL schemes. Sanitizing happens in the field's pre_save(), so it covers every ORM write path — admin form, REST/GraphQL serializer, Model.save(), bulk_create() — and what lands in the database is already clean. The changelist sanitizes again on render, which keeps rows written before this behaviour existed safe to display.

Two opt-outs, and one gap worth knowing:

• safe_html=True — you vouch for this field's HTML; it is stored and rendered verbatim.
• auto_sanitize=False — store exactly what was submitted (rendering is still sanitized). Useful when another layer owns the cleaning, or when you must preserve the original bytes.
• QuerySet.update() is not covered: Django never calls pre_save() for a bulk update, so a value written that way reaches the column untouched. Sanitize it yourself, or write through the instance.

Point SNAPADMIN_HTML_SANITIZER at a dotted path to your own Callable[[str], str] to replace the allowlist; it is used by both the write and the render path.

Available field types

Every field type below maps 1:1 to a Django field (except the computed ones) and accepts all the flags above.

🔌 The flags on any field — snap_field()

A Snap*Field is sugar over two things: an ordinary Django field, plus the flags above set as plain attributes. snap_field(field, **kwargs) sets those same attributes on a field instance you already have, so a third-party field — django-money's MoneyField, model-utils's StatusField, phonenumber_field's PhoneNumberField, or anything else SnapAdmin has never imported — gets the same admin/API behaviour without a Snap*Field subclass to rewrite it into:

from django.db import models
from snapadmin.fields import snap_field

class Product(models.Model):
    name = snap_field(models.CharField(max_length=255), searchable=True, filterable=True)

Every reader treats the result exactly like a Snap*Field — the searchable filter, the admin's list/search/filter config, the wysiwyg widget, the tab/row layout — because there is nothing new to read: snap_field() writes the identical attribute names a Snap*Field stores on itself, not a second place to look. It returns the field, so the call composes inline with the field declaration, and it adds no migration for every flag above: the attributes are set after Django's Field.__init__ already recorded its constructor arguments, so deconstruct() never reports them. An unrecognised kwarg raises ValueError naming it, rather than doing nothing.

snap_field() reaches full parity with every Snap*Field constructor kwarg, including three that used to be refused:

• wysiwyg=True sanitizes on write, identically to SnapRichTextField. The stored value is cleaned on every ORM write path (Model.save(), the REST API, bulk_create) — the wrapper reuses the exact same sanitizer, not a second one, so a wrapped field and a Snap*Field given the same input store byte-identical output. safe_html=True and auto_sanitize=False opt out the same way on both routes; QuerySet.update() stays uncovered on both (Django never calls pre_save() for it).
• required=True is accepted — the one flag that can produce a migration. It mutates null/blank directly to False, False, exactly what a hand-built Snap*Field(required=True) produces; that is schema-affecting by design, unlike every other flag on this page. required=False (the default) is a deliberate no-op on null/blank — it never loosens a field you explicitly built as non-nullable.
• allowed_extensions / allowed_encodings / max_size_bytes attach the same upload validator SnapFileField/SnapImageField build, on a FileField or ImageField (a non-file field raises ValueError naming the two field types, rather than failing later with a confusing error). No migration: the validator is stripped from deconstruct() by identity, the same technique those two field classes already use for their own auto-built validator.

# wysiwyg sanitize-on-write, required, and file validators — all reachable
description = snap_field(models.TextField(), wysiwyg=True)
sku         = snap_field(models.CharField(max_length=32), required=True)
invoice     = snap_field(models.FileField(), allowed_extensions=["pdf"], max_size_bytes=5_000_000)

🧵 You Don't Have to Snap-ify Everything

A SnapModel is a normal Django model; every Django field works on it, and Snap behaviour is opt-in per field — not an all-or-nothing choice for the whole model.

The demo's SearchLog model mixes all three shapes in one class body:

class SearchLog(snap_models.SnapModel):
    # 1. Snap*Field — the sugar. Gets searchable/filterable/etc. built in.
    query = snap_fields.SnapCharField(max_length=255, searchable=True)
    results_count = snap_fields.SnapIntegerField()

    # 2. snap_field() — a plain Django field plus only the Snap behaviour it needs.
    timestamp = snap_fields.snap_field(
        django_models.DateTimeField(auto_now_add=True),
        filterable=True,
    )

    # 3. Plain on purpose — it needs no Snap behaviour at all.
    user_agent = django_models.CharField(max_length=255, blank=True, default="")

A test proves the contrast rather than just asserting it in prose — see TestGetAdminFields.test_searchlog_bare_field_absent_from_search_and_filter_surface: user_agent stays out of both search_fields and list_filter, while timestamp (wrapped with filterable=True) is in list_filter right alongside fields declared with a Snap*Field.

The same freedom applies one level up, to a whole model: @snap_model opts a plain models.Model in without touching its field layer at all. See Two Ways to Declare a Model for the full picture.

📐 Advanced Layout

Control the visual arrangement of your admin forms using row and tab attributes.

class Customer(snap_models.SnapModel):
    # These two will appear on the same line
    first_name = snap.SnapCharField(max_length=100, row="name")
    last_name = snap.SnapCharField(max_length=100, row="name")

    # This field will appear in the "Contact" tab
    email = snap.SnapEmailField(tab="Contact")

🏷 Status Badges

Render coloured pill badges for any choice/status field directly in the admin list view.

from snapadmin import fields as snap

status_badge = snap.SnapStatusBadgeField(
    "is_active",
    [
        snap.SnapStatusBadgeFieldChoice(True, "#065F46", "#D1FAE5", "#10B981"),
        snap.SnapStatusBadgeFieldChoice(False, "#991B1B", "#FEE2E2", "#EF4444"),
    ],
)

# identical, and still supported
status_badge = snap.SnapStatusBadgeField(
    field_name="is_active",
    choices=[...],
)

🔧 Admin Registration

Call register_all_admins() once in your admin.py to register every SnapModel subclass with Django's admin site.

# admin.py
from snapadmin.models import SnapModel
SnapModel.register_all_admins()

To restrict registration to a specific app, pass the app_label argument:

SnapModel.register_all_admins(app_label="myapp")

Extending the generated admin

register_admin() builds and registers a ModelAdmin from a model's Snap field flags; two of its building blocks are public so a project can extend rather than replace them:

• get_admin_fields() returns an AdminFieldSets named tuple — (form_fields, list_display, search_fields, list_filter, autocomplete_fields), in that order. It is a plain 5-tuple by construction (positional unpacking, indexing and len() all keep working), with named access added on top. A sixth member would still be a breaking change — the point of pinning the shape is that such a change is announced, not discovered as a silent ValueError at admin autodiscover.
• get_admin_media() returns the base (js, css) asset lists — theme-sheet selection, the connectivity.js/offline.js gating and de-duplication with js_admin_files/css_admin_files all included. A project overriding register_admin() can call it to extend the real lists instead of copying a snapshot that rots at the next release.

admin_overrides always wins. It is merged onto the generated ModelAdmin last, so a project's own get_readonly_fields or safe_html_<field> display method always takes precedence over the one SnapAdmin generates — regardless of write order, because the generated versions never touch admin_overrides in the first place.

🌐 REST API

CRUD endpoints are generated automatically for all managed models.

Request Examples

All requests authenticate with an API token (see Token Management):

TOKEN="your-40-char-token-key"
BASE="http://localhost:8000/api"

# Discover every available endpoint and its fields
curl -H "Authorization: Token $TOKEN" "$BASE/models/schema/"

# Plain listing — paginated, served by the database
curl -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/?page=2"

# Auto-generated field filters (full per-model list visible in Swagger).
# Text fields: bare "?field=value" is an exact, index-usable match; substring
# search is explicit via "__icontains" (also: "__startswith", "__in").
curl -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/?available=true&price__gte=100"
curl -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/?name__icontains=laptop"

# JSON key-path filters (only for key-paths declared in api_json_filters)
curl -H "Authorization: Token $TOKEN" "$BASE/models/demo/Showcase/?json_field__a__b=value"

# Create, update, delete
curl -X POST -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
     -d '{"name": "Laptop Pro", "price": "1499.00", "available": true}' \
     "$BASE/models/demo/Product/"
curl -X PATCH -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
     -d '{"available": false}' "$BASE/models/demo/Product/42/"
curl -X DELETE -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/42/"

# Product is DUAL → this search runs on Elasticsearch (typo still matches)
curl -i -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/?search=laptp"
# HTTP/1.1 200 OK
# X-Snap-Query-Backend: elasticsearch     ← the search ran on ES
# {"count": 3, "results": [{"id": 42, "name": "Laptop Pro", …}, …]}

# ES search combined with DB filters and pagination — still one request
curl -H "Authorization: Token $TOKEN" \
     "$BASE/models/demo/Product/?search=laptop&available=true&page=1"

# The same URL shape on a DB_ONLY model transparently uses SQL icontains
curl -i -H "Authorization: Token $TOKEN" "$BASE/models/demo/Customer/?search=7"
# X-Snap-Query-Backend: database          ← no ES mirror, the DB handled it

# settings.py
SNAPADMIN_ES_QUERY_ROUTING     = True    # global switch (default True)
SNAPADMIN_ES_SEARCH_LIMIT      = 1000    # max hits fetched from ES per routed search
SNAPADMIN_QUERY_BACKEND_HEADER = True    # set False to hide the header in production

# models.py — per-model opt-out (e.g. when one model's ES mirror lags)
class Product(SnapModel):
    es_storage_mode  = EsStorageMode.DUAL
    es_query_routing = False   # this model's API searches always run on the DB

# Scalar → a `term` clause, list/tuple/set → a `terms` clause
Product.es_filter(available=True, price=[999, 1299])

# Compose with fuzzy full-text: query_string is added as a scored `must`
Product.es_filter(query_string="laptop", available=True)

# A `text` field auto-targets its keyword sub-field; a `__` path reaches into a
# JSON/object mapping the DB can't index — filtered here by nested key path:
Order.es_filter(payload__status="paid")    # → ES field payload.status

# One facet → {field: [{"key": …, "count": …}, …]}
Product.es_aggregate("available")
# {"available": [{"key": True, "count": 42}, {"key": False, "count": 3}]}

# Multiple facets, narrowed by a filter context, capped at N buckets each
Product.es_aggregate("category", "available", size=20, available=True)

# query_string= adds a scored full-text constraint before counting
Product.es_aggregate("category", query_string="laptop")

# Exact number of matches, regardless of the search limit
Product.es_count(available=True)               # → 4217
Product.es_count(price=[999, 1299])            # list → terms clause
Product.es_count(query_string="laptop")        # scored full-text, still exact
Order.es_count(payload__status="paid")         # → ES field payload.status

# Stream every matching document — no 10k ceiling, memory-bounded
for product in Product.es_scan(available=True):
    ...

# Same filter context as es_filter(); tune the batch size per round-trip
for log in SearchLog.es_scan(query_string="error 404", page_size=5000):
    ...

# Stream just the pks — no _source, no in_bulk() hydration
for pk in Product.es_scan(available=True, source=False):
    enqueue(pk)

# Bound the walk to the first 10k pks
first = list(Product.es_scan(available=True, source=False, limit=10_000))

from snapadmin.models import SnapEsUnavailable

# Default: graceful — falls back to the DB when ES is off
Product.es_count(available=True)                       # → DB count() if ES down

# Fail-fast: raise rather than run a query the DB can't scale
try:
    total = Product.es_count(available=True, db_fallback=False)
except SnapEsUnavailable:
    ...  # surface it, retry, alert — never a silent full-table scan

# Same flag on es_filter / es_aggregate / es_scan
for pk in Product.es_scan(available=True, db_fallback=False):  # raises if ES down
    ...

Counting objects — with & without filters

Every list response is paginated and already reports the total matching count in count — no need to page through everything. Request the smallest page to read just the number:

# Total rows (page_size=1 → tiny payload, full count in "count")
curl -s -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/?page_size=1"
# {"count": 5231, "next": "...", "results": [ ...1 row... ]}

# Count of a filtered set — "count" reflects the filtered queryset
curl -s -H "Authorization: Token $TOKEN" \
     "$BASE/models/demo/Product/?available=true&price__gte=100&page_size=1"

# Count of a full-text match set (DUAL → ES answers; count = ES hits)
curl -s -H "Authorization: Token $TOKEN" "$BASE/models/demo/Product/?search=laptop&page_size=1"

• DB_ONLY / DUAL without search — count is an exact SELECT COUNT(*) over the filtered SQL queryset.
• DUAL with ?search= / ES_ONLY — count is the number of ES hits, capped by SNAPADMIN_ES_SEARCH_LIMIT (default 1000). For an exact large-set count, count on the DB (drop ?search=) or raise the limit.

Exporting / bulk-reading optimally

Read large result sets page by page (bounded query + bounded response) rather than with one huge page_size. Follow the next link the API returns:

URL="$BASE/models/demo/Product/?page_size=200&ordering=id"
while [ "$URL" != "null" ]; do
  PAGE=$(curl -s -H "Authorization: Token $TOKEN" "$URL")
  echo "$PAGE" | python -c "import sys,json;[print(r['id']) for r in json.load(sys.stdin)['results']]"
  URL=$(echo "$PAGE" | python -c "import sys,json;print(json.load(sys.stdin)['next'] or 'null')")
done

The same three modes addressed directly from Python:

# DB_ONLY / DUAL — exact, index-backed count
Product.objects.filter(available=True, price__gte=100).count()

# DUAL / ES_ONLY — fuzzy full-text via Elasticsearch
Product.snap_search("laptp", limit=50)     # DUAL: DB queryset in ES-relevance order
SearchLog.snap_search("checkout")          # ES_ONLY: straight from the index

# Memory-flat export of any DB-backed model
for row in Product.objects.all().iterator(chunk_size=2000):
    ...

No-Celery bulk helpers — count + streaming export

Every dynamic model endpoint exposes two synchronous helpers that reuse the same filter, search and permission backends as the list view — no Celery required:

count/ returns just the size of the filtered set — cheap paginator sizing without pulling rows. export/ streams the entire filtered queryset as newline-delimited JSON (application/x-ndjson), one serialized object per line, pulled lazily in chunks (SNAPADMIN_EXPORT_CHUNK_SIZE, default 1000) so huge tables never materialise in memory. Both require the model's view permission. This is the synchronous counterpart to the Celery-backed /api/exports/ jobs above.

fetch-by — an explicit key set, in one call

export streams a filtered result set; fetch-by answers a different question — "give me exactly these records", for a key set large enough that a query string can't hold it. It is a POST that reads, justified by that one constraint alone: there is no other way to express a large explicit value list. field must be unique=True or db_index=True on the target model — anything else answers 400 naming the constraint, closing the unindexed-full-table-scan foot-gun a free-form field name would open. A hard cap, SNAPADMIN_FETCH_BY_MAX_VALUES (default 10000), rejects an oversized values list with 400 rather than silently truncating it — an unbounded list is a denial-of-service vector, and the cap exists before this route does. Same NDJSON streaming, permissions and masking as export (a masked field also can't be used as the lookup key); not supported for ES_ONLY models, which have no DB column to index. Because it never writes, it remains reachable via POST even on an api_read_only model — the read/write policy that gates create on the same URL segment does not apply to it.

Hiding fields from the API — api_exclude_fields

Columns listed in api_exclude_fields are removed from the REST serializer (responses and writes), the GraphQL object type and /api/models/schema/ — while the admin keeps showing them. Use it for PII and internal columns:

class AuditLog(SnapModel):
    action     = snap_fields.SnapCharField(max_length=100, searchable=True)
    user_email = snap_fields.SnapEmailField()     # PII

    api_exclude_fields = ["user_email"]           # never leaves the server via API

Restricting writes — api_write_fields

Field exposure and field writability are separate controls. By default every field not listed in api_exclude_fields also accepts a client-supplied value on REST create/update — set api_write_fields to an explicit list to change that: any field not named there is forced read-only through the API (still returned in responses unless also excluded above). Use it for status flags, ownership FKs and other columns that must only ever change server-side:

class Account(SnapModel):
    owner     = snap_fields.SnapForeignKey(User, on_delete=models.CASCADE)
    is_locked = snap_fields.SnapBooleanField(default=False)   # server-only status flag
    balance   = snap_fields.SnapDecimalField(max_digits=12, decimal_places=2)  # computed

    api_write_fields = ["owner"]   # is_locked / balance never accept a client value

Leaving it unset (the default) keeps every non-excluded field writable, matching prior behaviour — the snapadmin.W004 system check warns on any model that hasn't made the choice explicitly, so the exposure is deliberate rather than an oversight. The warning is grouped: one message names every unguarded model rather than repeating an identical block per model, and a model served read-only (api_read_only, or an api_http_method_names allowlist with no write verb) is skipped entirely — it has no mass-assignment surface to guard.

Read-only models & verb allowlists — api_read_only / api_http_method_names

api_write_fields controls which fields a write may touch; api_read_only removes the write verbs entirely. Set it on an import-only or reference table — one fed by an ETL job or another service, never by API clients — and the dynamic REST API serves it read-only: list/retrieve/count/export work, while POST/PUT/PATCH/DELETE answer 405 Method Not Allowed (no blank-row insert, no silent no-op update):

class ExchangeRate(SnapModel):
    code = snap_fields.SnapCharField(max_length=3, unique=True)
    rate = snap_fields.SnapDecimalField(max_digits=18, decimal_places=6)

    api_read_only = True                       # rates come from the feed, not API clients

# or an explicit verb allowlist (HEAD/OPTIONS are always added):
class AuditEvent(SnapModel):
    api_http_method_names = ["get", "post"]    # append-only: read + create, no update/delete

The verb is rejected in dispatch before any handler runs, so a read-only model can never insert a blank row, and the disallowed verbs are dropped from the OPTIONS Allow header too. api_http_method_names takes precedence over api_read_only when both are set; both default to full CRUD. A model that is field-read-only (api_write_fields = []) yet still write-exposed is flagged by the snapadmin.W007 check, nudging it toward api_read_only.

🎬 User-defined REST actions — @snap_action

CRUD covers create/read/update/delete; a real model usually also needs a handful of operations — approve, refund, recalculate, archive. @snap_action turns a model method into a callable REST endpoint, without hand-wiring a view:

class Order(SnapModel):
    total = snap_fields.SnapDecimalField(max_digits=10, decimal_places=2)

    @snap_action()
    def recalculate_total(self, request):
        self.total = sum(item.quantity * item.price for item in self.items.all())
        self.save(update_fields=["total"])
        return {"total": str(self.total)}

reachable at POST /api/models/demo/Order/<pk>/recalculate_total/. Works identically on a SnapModel subclass or a @snap_model-decorated plain model — the decorator reads the method straight off the class, no field or registry machinery involved.

An action can never widen a model's own policy. Every action URL is wired to every HTTP verb, but Django REST Framework rejects a verb outside the view's http_method_names — the same descriptor api_read_only/ api_http_method_names already drive — with 405 before a handler is even selected. A POST-only action therefore structurally cannot reach a model configured api_read_only = True; there is nothing to bypass. New check snapadmin.E008 catches the same conflict at boot — an action whose declared methods the model's own policy would always reject — before it ships as dead configuration.

Return a plain dict (wrapped as a 200 response) or a rest_framework.response.Response you build yourself, for a custom status or headers. Raise snapadmin.api.views.SnapActionError("message", status=409) to answer with an error — turned into the same {"detail": "message"} envelope every other error path in the API already uses. Every model's registered actions (name, scope, methods, URL) are listed at GET /api/models/schema/ — the concrete, per-model action set drf-spectacular's static schema cannot enumerate for the one generic dispatcher operation it documents instead.

GraphQL has no mutation counterpart, and none is planned. The GraphQL schema is read-only by design (see GraphQL API) — @snap_action is a REST-only surface, stated here explicitly rather than left to be discovered.

class Product(SnapModel):
    sku  = snap_fields.SnapCharField(max_length=32, unique=True)  # exact only — no substring lookup at all
    name = snap_fields.SnapCharField(max_length=200)              # library default: exact + __icontains/__startswith/__in

    # narrow "sku" to exact-only; every other text field on this model still
    # gets the library default lookup set
    api_filter_lookups = {"sku": ["exact"]}

# Per model — every text field on this model, index-friendly by default
class Product(SnapModel):
    api_default_text_lookups = ["exact", "startswith", "in"]   # no __icontains
    api_filter_lookups = {"name": ["exact", "icontains"]}      # …except name, which keeps it

# Project-wide (settings.py) — the safe posture for every model at once
SNAPADMIN_API_TEXT_LOOKUPS = ["exact", "startswith", "in"]     # unset → library default

# find products that were never categorised, or priced in a specific set
GET /api/models/demo/Product/?category_id__isnull=true
GET /api/models/demo/Product/?price__in=9.99,19.99&price__isnull=false

# opt a text field into a null check
class Product(SnapModel):
    api_filter_lookups = {"sku": ["exact", "isnull"]}   # exposes ?sku__isnull=true

class Order(SnapModel):
    payload = snap_fields.SnapJSONField(default=dict)

    api_json_filters = {"payload": ["a.b", "a.c"]}
    # exposes ?payload__a__b=value and ?payload__a__c=value

# settings.py — replaces the whole chain, exactly like DRF's DEFAULT_FILTER_BACKENDS,
# so list every backend you still want alongside your custom one:
SNAPADMIN_API_FILTER_BACKEND = [
    "myapp.filters.MyFilterBackend",
    "rest_framework.filters.OrderingFilter",
]

# a single dotted path (or the class object) is accepted too:
SNAPADMIN_API_FILTER_BACKEND = "myapp.filters.MyFilterBackend"

Vetoing deletes — api_can_delete + SNAPADMIN_API_DELETE_GUARD

Forbid deleting specific objects through the dynamic model API without re-mounting routes. Two extension points are consulted before every DELETE and both must allow it — returning False responds 403:

# 1) Per-model hook (default allows):
class Account(SnapModel):
    is_system = snap_fields.SnapBooleanField(default=False)

    def api_can_delete(self, request) -> bool:
        return not self.is_system          # system rows are undeletable

# 2) Project-wide guard — dotted path to Callable[[request, obj], bool]:
SNAPADMIN_API_DELETE_GUARD = "myproject.guards.protect_superusers"

⚛️ GraphQL API

SnapAdmin provides a dynamic GraphQL interface powered by Graphene-Django.

• Auto-Schema: All SnapModel subclasses are automatically added to the schema.
• Secured by default: every resolver requires authentication (admin session or API token) and the model's Django view permission — the same contract as REST — enforced on every relation the query traverses, not just top-level fields. Reading A { relatedB { … } } needs view on both models; a related object you may not view resolves as a Permission denied. error rather than leaking its data. Token allowed_models scopes apply on top.
• PII masking: fields in SNAPADMIN_MASKED_FIELDS are masked in GraphQL output exactly as in the REST API — raw only for superusers, snapadmin.view_raw_pii holders, and (per field) holders of a permission named in SNAPADMIN_MASKING_RULES, whose rules apply here too.
• Unified Fetching: the search argument routes to Elasticsearch for DUAL/ES_ONLY models; first/offset paginate.
• Endpoint: /api/graphql/; GraphiQL follows DEBUG (override with SNAPADMIN_GRAPHIQL_ENABLED).

Field naming

The schema is generated, so field names follow a fixed scheme. For a model Product in an app labelled demo, graphene lower-camel-cases the generated names into demoProduct(id: ID!) (one object by primary key) and allDemoProducts(search, first, offset) (a list). The general form is <applabel><Model> and all<Applabel><Model>s; pluralisation is naïve (a trailing s), so Category → allDemoCategorys. The object type is <Applabel><Model>Type. List results are a plain list, not a Relay connection — select fields directly, with no edges/node wrapper. Fields in a model's api_exclude_fields are dropped from its GraphQL type as well.

Request Examples

# Same API tokens as REST — anonymous callers get "Authentication required."
curl -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
     -d '{"query": "{ allDemoProducts(search: \"laptop\", first: 10) { id name price } }"}' \
     "http://localhost:8000/api/graphql/"

# Single object by id
curl -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
     -d '{"query": "{ demoProduct(id: 42) { name price available } }"}' \
     "http://localhost:8000/api/graphql/"

# settings.py
SNAPADMIN_GRAPHQL_REQUIRE_AUTH = True   # default — never disable in production
SNAPADMIN_GRAPHIQL_ENABLED     = DEBUG  # playground only during development

🔑 Token Management

SnapAdmin uses named API tokens for REST API authentication. Tokens are created and managed in the Django admin under API Tokens, or programmatically:

from snapadmin.models import APIToken

# Create a token for a user, valid for 30 days
token = APIToken.create_for_user(
    user=user,
    token_name="CI Pipeline",
    allowed_models=["myapp.Product", "myapp.Order"],
    expires_in_days=30,
)

Include the token in every API request as an HTTP header:

Authorization: Token <token_key>

Token REST Endpoints

A regular user manages their own tokens — list, create, retrieve, rotate, deactivate, delete — without needing to be a superuser; each lookup is scoped to token.user == request.user (a superuser sees and manages every token).

Token Fields

Rotating a leaked key from Python:

token = APIToken.objects.get(token_prefix="ab12cd34")
new_raw_key = token.rotate()   # old key stops authenticating immediately
# new_raw_key is shown once — store it now, it is not recoverable afterwards

🧮 Quotas & Rate Limits

SnapAnonRateThrottle / SnapUserRateThrottle (SNAPADMIN_THROTTLE_ANON / SNAPADMIN_THROTTLE_USER, above) give one global rate for every anonymous or authenticated caller. snapadmin.limits.reserve() is the narrower primitive projects keep rebuilding on top of that: a per-tenant or per-token quota across several time windows at once, a concurrency cap, and a cooldown after an upstream service answers 429 — including for calls your project makes outbound to a third party, which a request-scoped DRF throttle has no way to express at all. It has no opinion about what the key means, so it serves inbound and outbound alike:

from snapadmin.limits import reserve

with reserve(f"tenant:{tenant_id}", windows={60: 100, 3600: 1000}, concurrency=5) as slot:
    if not slot.allowed:
        return too_many_requests(retry_after=slot.retry_after)  # slot.reason: "rate_limited" | "concurrency" | "cooldown"
    call_the_upstream_api()

windows is {period_seconds: max_count} — every window must clear for the reservation to succeed. concurrency, if given, additionally caps how many reservations for the same key may be held at once; releasing the returned object (or using it as a context manager, as above) frees the slot, and an unreleased slot expires on its own after concurrency_timeout seconds (default 300) so a crashed holder can never leak it forever. snapadmin.limits.cooldown(key, seconds) is a separate, explicit signal for the one thing reserve() cannot see on its own: call it after an upstream actually answers 429, and every reserve() for that key fails fast (before touching a window or the concurrency counter) until the cooldown expires.

Two honest limitations, worth reading before trusting this in production:

• Counters are per-process unless CACHES points at a shared backend. The default LocMemCache is private to one process — four Gunicorn workers each enforce the configured limit independently, so the effective ceiling is four times what windows says. Point SNAPADMIN_LIMITS_CACHE_ALIAS at a shared cache (Redis, Memcached, a database cache) before relying on this across more than one worker.
• A cache that evicts a counter under memory pressure fails open, not closed. An evicted counter looks identical to one that never existed, so the next call sees a fresh window and is allowed — the same trade-off any cache-backed rate limiter makes, including DRF's own throttles.

See it wired into an actual outbound call in the demo project's sync_exchange_rates --rate-limit N management command (caps the "call to the external feed" to N runs per minute, plus a concurrency=1 guard against two syncs racing the same feed).

🔍 Elasticsearch Integration

SnapAdmin supports three Elasticsearch storage modes via EsStorageMode. Choose the mode per model based on your use case.

Enable Elasticsearch

Add to your settings.py (or set via env vars):

ELASTICSEARCH_ENABLED = True   # False by default — ES is completely skipped when False
ELASTICSEARCH_URL = "http://localhost:9200"  # local dev or external cluster

Running with Docker

The default docker compose -f demo/docker-compose.yml up does not start Elasticsearch (saves ~512 MB RAM). To enable it:

# Enable ES in your demo/.env
ELASTICSEARCH_ENABLED=True

# Then start the full stack including ES
docker compose -f demo/docker-compose.yml --profile es up --build

# Add Kibana for visualisation (dev only)
docker compose -f demo/docker-compose.yml --profile es --profile dev up --build

External Elasticsearch (production / staging)

Point to any external ES cluster via env vars — no code change needed:

# demo/.env (production)
ELASTICSEARCH_ENABLED=True
ELASTICSEARCH_URL=https://my-cluster.example.com:9200

Storage Modes

Setting the Mode on a Model

The fields you want searchable in Elasticsearch are declared in es_mapping — a dict of {field_name: ES mapping}. (There is no es_index_fields attribute.) For DUAL you may also set es_index_enabled = True.

from snapadmin.models import SnapModel, EsStorageMode
from snapadmin import fields as snap_fields

# DB_ONLY (default — no extra config needed)
class Article(SnapModel):
    title = snap_fields.SnapCharField(max_length=200, searchable=True)
    body  = snap_fields.SnapTextField()

# DUAL — save to PostgreSQL AND Elasticsearch, search via ES
class Product(SnapModel):
    name        = snap_fields.SnapCharField(max_length=200, searchable=True)
    description = snap_fields.SnapTextField()
    price       = snap_fields.SnapDecimalField(max_digits=10, decimal_places=2)

    es_index_enabled = True
    es_storage_mode  = EsStorageMode.DUAL
    es_mapping = {
        "name":        {"type": "text", "analyzer": "standard"},
        "description": {"type": "text"},
        "price":       {"type": "float"},
    }

# ES_ONLY — no DB table (managed=False), data lives only in Elasticsearch
class SearchLog(SnapModel):
    query         = snap_fields.SnapCharField(max_length=255, searchable=True)
    results_count = snap_fields.SnapIntegerField()
    timestamp     = models.DateTimeField(auto_now_add=True)

    es_storage_mode = EsStorageMode.ES_ONLY
    es_mapping = {
        "query":         {"type": "text"},
        "results_count": {"type": "integer"},
        "timestamp":     {"type": "date"},
    }

    class Meta:
        managed = False  # required for ES_ONLY — no DB table is created

Custom analyzers & index settings — es_index_settings

Index-level settings (custom analyzers under analysis, number_of_shards, number_of_replicas, …) are declared in es_index_settings and applied when the index is first created. Existing indexes are never altered — to apply a change, delete the index and run es_reindex_all():

class Product(SnapModel):
    es_storage_mode = EsStorageMode.DUAL
    es_mapping = {
        "name":  {"type": "text", "analyzer": "de_analyzer"},
        "price": {"type": "float"},
    }
    es_index_settings = {
        "analysis": {"analyzer": {"de_analyzer": {"type": "german"}}},
        "number_of_shards": 1,
    }

Automatic mapping — es_auto_mapping

Don't want to write mappings by hand? Set es_auto_mapping = True and the mapping is derived from the model's fields: CharField/TextField → text with a .raw keyword subfield (exact match + aggregations), Email/Slug/URL/UUID/IP/File → keyword, integers & FK → long, Float → double, Decimal → scaled_float, dates → date, JSONField → object. Entries in es_mapping override the derived ones per field:

class SearchLog(SnapModel):
    query         = snap_fields.SnapCharField(max_length=255, searchable=True)
    results_count = snap_fields.SnapIntegerField()

    es_storage_mode = EsStorageMode.ES_ONLY
    es_auto_mapping = True   # derived: query → text + .raw, results_count → long
    # es_mapping = {"query": {"type": "search_as_you_type"}}   # optional override

Querying with es_search()

es_search(query_string=None, limit=20) is the single entry point for search. It runs a fuzzy multi_match over the index when ES is enabled, and gracefully falls back to an ORM query (using the model's searchable fields) when ES is off or unreachable — so the same call works in every environment. snap_search() is a public alias with identical behavior.

# Full-text search (fuzzy, typo-tolerant) — returns a queryset-like result
results = Product.es_search("wireles headphones")     # note the typo — still matches
for product in results:
    print(product.name, product.price)

# Cap the number of hits (default 20)
top5 = Product.es_search("laptop", limit=5)

# No query string → match-all (most-recent first), handy for "browse" views
everything = Product.es_search(limit=100)

# Public alias — identical behavior, nicer name for app code
hits = Product.snap_search("4k monitor")

# ES_ONLY models: es_search() is the ONLY way to read them (no DB table)
logs = SearchLog.es_search("error 404")
recent_logs = SearchLog.es_search(limit=50)

# DB_ONLY models still answer es_search() — it falls back to an ORM
# icontains query across the model's searchable fields:
articles = Article.es_search("django")   # works even with ELASTICSEARCH_ENABLED=False

Re-indexing (DUAL mode)

# Manually trigger a full re-index of every row into ES.
# Streams the table through the bulk API — one round-trip per 500 docs
# (tune with chunk_size=). DB-backed models page a pk__gt keyset cursor
# (not QuerySet.iterator, which buffers the whole result on mysqlclient),
# so memory stays flat even on million-row tables — on every backend:
Product.es_reindex_all()      # {"indexed": N} — or {"skipped": True} if ES is off

# Per-instance indexing happens automatically on save() in DUAL/ES_ONLY mode.
# To force a single object back into the index:
product.index_in_es()
product.delete_from_es()      # remove just this object's ES document

# Via Celery task (recommended for large datasets) — needs a running worker:
from demo.apps.shop.tasks import reindex_products_to_elasticsearch
reindex_products_to_elasticsearch.delay()

📴 Offline Mode

Flip one class attribute to make a model's admin list view survive a dropped connection. SnapAdmin injects snapadmin/js/offline.js into that model's admin pages only — models without the flag ship no extra JavaScript.

class Customer(SnapModel):
    first_name = SnapCharField(max_length=100, show_in_form=True)
    last_name  = SnapCharField(max_length=100, show_in_form=True)

    # Cache this model's list view client-side and enable offline support
    offline_mode = True
    # Prefetch only the 50 most-recent rows for offline view (default: 100)
    offline_cache_limit = 50

⚡ Large-Dataset Performance

SnapAdmin keeps the admin and API responsive as tables grow. Most tuning is automatic; the rest is a few per-model knobs.

Automatic — no admin N+1

When a model is registered, SnapAdmin inspects the columns shown in the list view and auto-derives list_select_related from the ForeignKey columns among them. A list view that renders a related column — or a __str__ that walks a relation — issues one joined query instead of one query per row. Only the FKs you actually display are joined; relations you don't show are never fetched.

The auto-generated REST API applies the same treatment to its querysets — select_related() for ForeignKeys and prefetch_related() for many-to-many fields — with the field lists cached per model to keep introspection out of the request hot path.

class AuditLog(snap_models.SnapModel):
    action = snap.SnapCharField(max_length=100, searchable=True)

    list_per_page = 50              # rows per page (default 100)
    list_max_show_all = 200         # cap on the "Show all" link
    show_full_result_count = False  # skip the unfiltered COUNT(*) on huge tables

# Bulk-seed 100k customers + orders (batched bulk_create, flat memory)
python manage.py seed_large --count 100000

# Time the Order changelist queryset with vs without list_select_related
python manage.py benchmark_list_view --model order

📊  Result
   WITHOUT :    5,001 queries       584.5 ms
   WITH    :        1 queries        37.8 ms

   Query reduction : 5,001 → 1  (5001× fewer)
   Speedup         : 15.5× faster wall time

🚀 Optimizations Guide

The Large-Dataset Performance section above is the reference for SnapAdmin's specific knobs. This guide is the broader picture: the data-access patterns every developer working with large tables should understand, whether or not they use SnapAdmin. Most of it is plain Django/SQL; the SnapAdmin-specific automation is called out where it applies.

# N+1: one query for orders, then one per order for the customer
for order in Order.objects.all():        # 1 query
    print(order.customer.first_name)     # +1 query EACH iteration

# Fixed: a single JOIN pulls customers alongside orders
for order in Order.objects.select_related("customer"):   # 1 query, total
    print(order.customer.first_name)

⚙️ Celery & Periodic Tasks

SnapAdmin ships built-in Celery tasks for background export, indexing, token cleanup, error digests, backups and GDPR retention.

Nothing here runs on its own. SnapAdmin has no daemon and installs no schedule. Each task stays idle until you either point a scheduler at it (Celery Beat or system cron) or — for the event-triggered ones — keep a Celery worker running to pick the job up. Where this site calls a feature "automatic", it means automatic once wired; the table below is what wiring it means.

Task outcomes & monitoring

Every scheduled task below except run_export (which tracks its own status on the SnapExportJob row) returns a summary dict carrying a status key with one of exactly four values, plus a failed list ([] when nothing failed) — every existing key on every task's summary keeps its name and shape, this is purely additive:

A total failure raises (BackupError / SnapPurgeError / AlertDeliveryError / ReindexError) instead of returning — a raised exception is the only thing Celery itself records as a task failure, which is what a task-status monitor watches. Retrying a partial failure would redo the units that already succeeded (e.g. re-uploading a backup that already shipped to two of three destinations), so partial never raises — it is loud instead: status="partial", a populated failed list, and one error-level log line with a stable marker.

This closes a reported incident: a disabled backup schedule ran "successfully" for weeks with no backup ever taken (the task returned {"ran": False, "reason": "disabled"} and Celery recorded a clean success every time), and a silently-failing offsite destination never surfaced anywhere but a log line while the task still reported overall success.

# myproject/celery.py
from celery import Celery

app = Celery("myproject")
app.config_from_object("django.conf:settings", namespace="CELERY")
app.autodiscover_tasks()

from celery.schedules import crontab

CELERY_BROKER_URL = "redis://localhost:6379/0"
CELERY_RESULT_BACKEND = "redis://localhost:6379/0"

CELERY_BEAT_SCHEDULE = {
    "purge-expired-data": {
        "task": "snapadmin.purge_expired_data",
        "schedule": crontab(hour=1, minute=0),   # daily 1am
        "description": "GDPR — data_retention_days, the audit log, and job/file cleanup",
    },
    "purge-expired-tokens": {
        "task": "snapadmin.purge_expired_tokens",
        "schedule": crontab(hour=3, minute=0),   # daily 3am
        "description": "Remove expired API tokens",
    },
    "send-error-digest": {
        "task": "snapadmin.send_error_digest",
        "schedule": crontab(hour=8, minute=0),   # daily 8am
        "description": "Grouped digest of captured error events",
    },
    "send-health-alert": {
        "task": "snapadmin.send_health_alert",
        "schedule": crontab(minute="*/5"),       # every 5 minutes
        "description": "Email an alert when a subsystem (DB/ES) is down",
    },
    "run-db-backups": {
        "task": "snapadmin.run_db_backups",
        "schedule": crontab(minute=30),          # hourly due-check
        "description": "3-2-1 database backups (each destination when due)",
    },
}

No Celery? Every scheduled task above can be driven from system cron instead — see the per-feature sections (GDPR retention, error monitoring, backups) for the equivalent cron lines.

Running Celery in Docker

# demo/docker-compose.yml services:
worker:
  command: celery -A demo.core worker -l INFO
beat:
  command: celery -A demo.core beat -l INFO --scheduler django_celery_beat.schedulers:DatabaseScheduler

💾 3-2-1 Database Backups

Built-in database backups following the classic 3-2-1 rule — 3 copies of your data, on 2 different machines, 1 of them offsite. Dumps are gzip-compressed (file copy for SQLite, pg_dump for PostgreSQL, mysqldump for MySQL) and shipped to up to five destinations, each on its own interval:

Backups are the integration checklist's "Data safety" group in full: two destinations, retention, and — strongly recommended — encryption, covered next.

Configuration

SNAPADMIN_BACKUP_ENABLED = True               # strictly opt-in (default: False)
SNAPADMIN_BACKUP_KEEP = 7                     # dumps kept per destination (oldest pruned)

# Copy 1 — same server
SNAPADMIN_BACKUP_LOCAL_DIR = "/var/backups/snapadmin"
SNAPADMIN_BACKUP_LOCAL_EVERY_HOURS = 24       # daily

# Copy 2 — server on the same network (mounted share)
SNAPADMIN_BACKUP_NETWORK_DIR = "/mnt/backup-server/snapadmin"
SNAPADMIN_BACKUP_NETWORK_EVERY_HOURS = 24     # daily

# Copy 3 — offsite FTP/FTPS
SNAPADMIN_BACKUP_FTP_HOST = "backup.example.com"
SNAPADMIN_BACKUP_FTP_PORT = 21
SNAPADMIN_BACKUP_FTP_USER = "backup"
SNAPADMIN_BACKUP_FTP_PASSWORD = "secret"
SNAPADMIN_BACKUP_FTP_DIR = "/snapadmin"
SNAPADMIN_BACKUP_FTP_TLS = True               # FTPS — recommended offsite
SNAPADMIN_BACKUP_REMOTE_EVERY_HOURS = 168     # weekly

# Copy 3 (alternative) — offsite over SSH/SFTP; pip install django-snapadmin[backup]
SNAPADMIN_BACKUP_SFTP_HOST = "offsite.example.com"
SNAPADMIN_BACKUP_SFTP_PORT = 22
SNAPADMIN_BACKUP_SFTP_USER = "backup"
SNAPADMIN_BACKUP_SFTP_KEY_FILE = "/etc/snapadmin/id_ed25519"  # key auth; or set _PASSWORD
SNAPADMIN_BACKUP_SFTP_DIR = "/snapadmin"
SNAPADMIN_BACKUP_SFTP_EVERY_HOURS = 168       # weekly

# Copy 3 (alternative) — any S3-compatible object store; pip install django-snapadmin[s3]
SNAPADMIN_BACKUP_S3_BUCKET = "my-backups-bucket"
SNAPADMIN_BACKUP_S3_PREFIX = "snapadmin/"           # optional key prefix inside the bucket
SNAPADMIN_BACKUP_S3_REGION = "eu-central-1"
# ENDPOINT_URL is the one setting that turns this into a transport for five
# providers — leave it unset for AWS, or point it at MinIO / Backblaze B2 /
# Hetzner Object Storage / Wasabi:
SNAPADMIN_BACKUP_S3_ENDPOINT_URL = "https://s3.eu-central-1.wasabisys.com"
# Leave both unset to use the ambient credential chain instead (env vars, a
# shared config file, or an IAM role / instance profile) — the right choice
# on AWS; a static key there would be a downgrade.
SNAPADMIN_BACKUP_S3_ACCESS_KEY_ID = "AKIA..."
SNAPADMIN_BACKUP_S3_SECRET_ACCESS_KEY = "..."
SNAPADMIN_BACKUP_S3_EVERY_HOURS = 168               # weekly

A configured-but-incomplete S3 destination is snapadmin.W011 at manage.py check — advisory, like the AGE recipient check above: an unparseable SNAPADMIN_BACKUP_S3_ENDPOINT_URL, or a bucket set with neither an explicit access key pair nor a detected ambient AWS credential source (env vars, a shared credentials file, an ECS/IRSA role — an EC2 instance profile can't be detected without a network call, so that case is silently accepted).

Hetzner Storage Box — a worked SFTP recipe

A Storage Box account works with the existing SFTP destination once four things are right:

SNAPADMIN_BACKUP_SFTP_HOST = "u123456.your-storagebox.de"
SNAPADMIN_BACKUP_SFTP_PORT = 23                              # not 22 — Storage Box's external SSH port
SNAPADMIN_BACKUP_SFTP_USER = "u123456-sub1"                  # a sub-account, not the main account
SNAPADMIN_BACKUP_SFTP_KEY_FILE = "/etc/snapadmin/id_ed25519"  # key-based auth

1. Port 23, not the SSH default 22 — Storage Box's external SFTP/SCP endpoint.
2. A sub-account (Hetzner Robot → Storage Box → Sub-accounts) scoped to its own subdirectory, so a leaked key can't reach the whole box.
3. Key-based auth — upload the sub-account's public key in the Robot panel; set SNAPADMIN_BACKUP_SFTP_KEY_FILE to the matching private key's path.
4. Pre-populate known_hosts — SnapAdmin's SFTP transport rejects an unknown host key on purpose (no trust-on-first-use), so the host key has to already be there before the first backup runs:

   ssh-keyscan -p 23 -H u123456.your-storagebox.de >> ~/.ssh/known_hosts

   Run this once as the same user the backup process runs as (e.g. during deployment), or make one manual sftp -P 23 u123456-sub1@u123456.your-storagebox.de connection and accept the prompt.

Running the backups

Backups run as a separate process from your web workers — via Celery Beat or cron. The hourly Beat task is only a due-check: each destination actually fires when its own *_EVERY_HOURS interval has elapsed (last-run times persist in a state file, surviving restarts):

# Celery Beat:
"run-db-backups": {
    "task": "snapadmin.run_db_backups",
    "schedule": crontab(minute=30),   # hourly due-check
}

# ...or plain cron, without Celery:
30 * * * *  python manage.py snapadmin_db_backup            # ships only what is due
python manage.py snapadmin_db_backup --force                # all configured destinations, now
python manage.py snapadmin_db_backup --destination remote   # one destination, now

Encrypting backups (AGE)

Set SNAPADMIN_BACKUP_AGE_RECIPIENTS and every dump is encrypted with age in-stream, before a single byte reaches disk — pg_dump/mysqldump/SQLite → gzip → age → the .age-suffixed file. No plaintext or plain-gzip artefact is ever written, not even transiently, and a mid-pipeline failure leaves nothing behind rather than a partial or corrupt one. With the setting empty (the default), nothing changes — this is exactly today's behaviour.

age's headline property is what makes this useful for a team rather than one person: encrypt once to any number of recipients, and any one of their private keys decrypts the file independently — no shared secret, no re-encryption to add a reader.

# One setting turns it on — a list, because multi-recipient is the default shape:
SNAPADMIN_BACKUP_AGE_RECIPIENTS = [
    "age1scr8rpq5lxtaqqskkawrft82at865e4j3gvs30cjv79q5qq3gc7qwj8um3",  # ops laptop
    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBaU... deploy@ci",           # an SSH public key works too
]

# Restore-only — a *path* to a private-key file, never the key material itself.
SNAPADMIN_BACKUP_AGE_IDENTITY_FILE = "/etc/snapadmin/age-identity.txt"

# "auto" (default) prefers the in-process pyrage library, falls back to the `age`
# CLI if pyrage isn't installed. Pin explicitly with "pyrage" or "binary".
SNAPADMIN_BACKUP_AGE_BACKEND = "auto"

An entry that doesn't look like a valid age (age1…) or SSH (ssh-ed25519 … / ssh-rsa …) public key is snapadmin.W008 at manage.py check — advisory, since the other recipients still work; the malformed one only fails when a backup actually runs.

Both backends produce and consume the identical, standardised age file format — a bundle encrypted with one restores fine with the other, or with the plain age command run by hand on a jump host with no Django involved at all.

Don't have a keypair yet? Generate one from the library, through either backend:

python manage.py snapadmin_age_keygen

The private key is written once, to a new .age/ directory at the project root, and is never printed or logged — only the public recipient is, ready to paste into SNAPADMIN_BACKUP_AGE_RECIPIENTS above. Before writing anything, the command checks the project's .gitignore for a rule that would already exclude .age/ — recognising more than a literal .age/.age/ line (a leading-slash anchor, a **/ prefix or /** suffix, and a blanket dotfile rule like .*) — and appends one, with a visible message, if none is found. Every run closes with a reminder: move the private key to a secure location (a password manager, a secrets vault, an encrypted volume) and delete the local .age/ directory — it is a convenience for generation, never long-term storage for a private key.

Key rotation, stated plainly because it surprises people: adding a recipient only affects backups made after the change — it does not retroactively unlock older bundles. Removing one is the same in reverse: an already-encrypted bundle stays decryptable by every key it was originally encrypted to. A private key never appears in a setting, in snapadmin_info output, or in a log line — only the recipient (public key) list and the identity file path are ever recorded; the identity is supplied only at restore time, from that file.

Media and .env in the bundle

SNAPADMIN_BACKUP_INCLUDE extends a run beyond the database — a subset of db, media, env. The default is ["db"], so this is entirely opt-in and today's behaviour is unchanged unless you add to it. Each part ships as its own file sharing one run's timestamp, alongside one always-unencrypted manifest.json sidecar — never a single combined archive, so --only db at restore time can fetch and decrypt just the part you actually need.

SNAPADMIN_BACKUP_INCLUDE = ["db", "media", "env"]   # default: ["db"]

# media: MEDIA_ROOT, tarred and streamed — never built in memory.
SNAPADMIN_BACKUP_MEDIA_EXCLUDE = ["cache/**", "*.tmp"]        # glob patterns, relative to MEDIA_ROOT
SNAPADMIN_BACKUP_MEDIA_SIZE_WARNING_BYTES = 10 * 1024 ** 3     # log a warning past this size (10 GiB) — never aborts

# env: your project's .env file (or any file holding secrets).
SNAPADMIN_BACKUP_ENV_FILE = "/etc/snapadmin/project.env"

An unreadable media file (permission error, a broken symlink, one that vanished mid-run) is skipped with a warning, not an aborted backup — a broken thumbnail must not cost you the database. The manifest lists snapadmin/Django versions, the DB engine, every part actually produced with its ciphertext checksum (so a truncated upload is caught before any decrypt attempt is made), the full recipient list, and a ready-to-paste snapadmin_restore command — see Restoring a backup.

Retention (SNAPADMIN_BACKUP_KEEP) applies per part: a run that includes media keeps its own newest N media bundles independently of the database dump's own N, so opting into media never starves the database backup's retention headroom.

↩️ Restoring a Backup

manage.py snapadmin_restore restores a bundle snapadmin_db_backup produced. Dry-run is the default — without --confirm it prints exactly what would happen (which parts, which database, whether the .env file would be overwritten) and changes nothing:

# See what backups are available (a local path, or from a configured destination):
python manage.py snapadmin_restore --list
python manage.py snapadmin_restore --list --destination sftp

# Plan only — prints what would happen, touches nothing:
python manage.py snapadmin_restore snapadmin-manifest-20260826-020000.json

# Pull straight from a destination and restore only the database:
python manage.py snapadmin_restore sftp:snapadmin-manifest-20260826-020000.json \
    --only db --identity /etc/snapadmin/age-identity.txt --confirm

Before touching anything, the manifest's per-part checksum is verified against the fetched ciphertext — a truncated or corrupted upload is refused rather than half-restored. An encrypted bundle restored with no --identity prints exactly how many recipients it needs and their fingerprints, instead of failing on an opaque parse error.

Restoring db is not live-safe: existing connections are terminated and, for PostgreSQL, the database is dropped and recreated before the dump loads. Run it in a maintenance window. SQLite is a straight file replace after closing the connection.

The pre-restore safety net: snapadmin_rollback

Before a --confirmed restore touches anything, it automatically snapshots the current live state of every part it is about to overwrite — the same parts, encrypted the same way a real backup would be — into SNAPADMIN_RESTORE_SNAPSHOT_DIR (default: a rollback/ subdirectory of the local backup directory), and prints the snapshot id prominently before proceeding. If the snapshot itself fails, the restore is aborted — never on a best-effort basis.

# List available snapshots:
python manage.py snapadmin_rollback --list

# Roll back to the most recent one (dry-run by default, same --confirm):
python manage.py snapadmin_rollback --confirm

# Roll back to a specific one:
python manage.py snapadmin_rollback 20260826-020000 --identity /etc/snapadmin/age-identity.txt --confirm

Snapshots have their own retention, SNAPADMIN_RESTORE_SNAPSHOT_KEEP (default 3) — separate from SNAPADMIN_BACKUP_KEEP, since these are short-lived safety nets, not backups, and must not compete with the real retention policy for disk. --no-snapshot exists for the operator who knows better and prints a loud warning when used.

🚨 Error Monitoring & Alerts

Optional notifications about server errors, built on one middleware. Every unhandled exception and 5xx response is stored as an ErrorEvent — browsable in the admin under Error Events — and two alerts keep the team informed (by email, by chat webhook, or both — see Alert channels):

• Spike alert — when SNAPADMIN_ERROR_ALERT_THRESHOLD errors occur within SNAPADMIN_ERROR_ALERT_WINDOW_MINUTES (default 20 errors / 15 min), one email is sent immediately. A cooldown guarantees at most one alert per window.
• Daily digest — a grouped 24-hour report: identical errors are merged by exception class + endpoint, ordered by frequency, and capped at SNAPADMIN_ERROR_DIGEST_MAX_GROUPS groups so the email stays readable.

Setup

# settings.py
MIDDLEWARE = [
    # ... Django middleware ...
    "snapadmin.middleware.SnapErrorMonitorMiddleware",
]

# Spike alert (defaults shown)
SNAPADMIN_ERROR_ALERT_THRESHOLD = 20          # errors ...
SNAPADMIN_ERROR_ALERT_WINDOW_MINUTES = 15     # ... within this window → email
SNAPADMIN_ERROR_ALERT_EMAILS = ["ops@example.com"]

# Daily digest
SNAPADMIN_ERROR_DIGEST_EMAILS = ["team@example.com"]  # falls back to ALERT_EMAILS
SNAPADMIN_ERROR_DIGEST_MAX_GROUPS = 20
SNAPADMIN_ERROR_RETENTION_DAYS = 30           # ErrorEvents older than this are purged

Scheduling the digest

# Celery Beat — the send time is entirely yours:
"send-error-digest": {
    "task": "snapadmin.send_error_digest",
    "schedule": crontab(hour=8, minute=0),
}

# ...or plain cron, without Celery:
0 8 * * *  python manage.py snapadmin_send_error_digest
python manage.py snapadmin_send_error_digest --hours 12   # custom window

Settings reference

Health alerts — email when a subsystem is down

A third, independent channel watches infrastructure rather than application errors. It runs the same probes as snapadmin_info --health-check — database, Elasticsearch, the REST API and GraphQL — and emails when one reports a failure, so an outage reaches an operator instead of only the logs. Each probe honours its feature toggle (ELASTICSEARCH_ENABLED, SNAPADMIN_REST_API_ENABLED, SNAPADMIN_GRAPHQL_ENABLED), so a subsystem you turned off is never a false alarm. Run it on a schedule — the snapadmin.send_health_alert Celery task, or the snapadmin_health_alert management command from cron (it also exits non-zero while a probe is failing, so it doubles as a monitoring gate). A cache-based cooldown limits a persistent outage to one email; a recovery re-arms it so the next outage alerts immediately.

# settings.py — recipients fall back to SNAPADMIN_ERROR_ALERT_EMAILS
SNAPADMIN_HEALTH_ALERT_ENABLED = True
SNAPADMIN_HEALTH_ALERT_EMAILS = ["ops@example.com"]
SNAPADMIN_HEALTH_ALERT_COOLDOWN_MINUTES = 60

# Celery Beat — probe every few minutes:
"send-health-alert": {
    "task": "snapadmin.send_health_alert",
    "schedule": crontab(minute="*/5"),
}

# ...or plain cron, without Celery:
*/5 * * * *  python manage.py snapadmin_health_alert
python manage.py snapadmin_health_alert --force   # re-send within the cooldown

Alert channels — Slack, Discord, Teams, Telegram

Every alert above (spike, digest, health) is delivered by the same set of channels. Email is one of them; the others are chat webhooks, posted with the standard library — SnapAdmin adds no dependency for alerting. Thresholds, grouping and the cooldown are shared by all channels, so adding a webhook changes where an alert goes, never how often it fires.

# settings.py — read the URLs from the environment, never hard-code them
SNAPADMIN_ALERT_WEBHOOKS = [
    {"type": "slack",    "url": os.environ["SLACK_ALERT_WEBHOOK"]},
    {"type": "discord",  "url": os.environ["DISCORD_ALERT_WEBHOOK"]},
    {"type": "teams",    "url": os.environ["TEAMS_ALERT_WEBHOOK"]},
    {"type": "telegram", "token": os.environ["TELEGRAM_BOT_TOKEN"],
                         "chat_id": os.environ["TELEGRAM_CHAT_ID"]},
    # Only page the on-call channel for outages, not for the daily digest:
    {"type": "json", "url": "https://ops.example.com/hooks/snapadmin",
     "events": ["health", "error_spike"], "timeout": 3},
]

SNAPADMIN_ALERT_EMAIL_ENABLED = True   # False → chat-only, no mail server needed
SNAPADMIN_ALERT_WEBHOOK_TIMEOUT = 5    # seconds per POST

🪵 Structured Logging

SnapAdmin provides a structlog-based logging setup with colourised output for development and JSON output for production.

from snapadmin.logging_config import configure_logging

# Human-readable coloured output (development)
configure_logging(log_level="INFO", json_logs=False)

# JSON lines (production / Docker)
configure_logging(log_level="WARNING", json_logs=True)

from snapadmin.logging_config import get_logger

logger = get_logger(__name__)

logger.info("order_created", order_id=42, total=199.90)
logger.warning("es_unavailable", model="Product")
logger.error("payment_failed", reason="card_declined")

🔒 GDPR Data Retention

SnapAdmin gives you a one-line retention window on any SnapModel to help comply with EU data retention laws (GDPR). The two attributes below declare what counts as expired; a scheduled task you wire up is what actually deletes it. The same snapadmin.purge_expired_data task also covers two things that are not SnapModels at all — the audit log and, if you opt in, finished export/reindex job rows and their files — see the full purge table below for everything the package can auto-delete.

class AuditLog(SnapModel):
    action     = SnapCharField(max_length=100)
    created_at = SnapDateTimeField(auto_now_add=True)
    attachment = SnapFileField(upload_to="audit/", blank=True, null=True)

    # Rows older than 90 days count as expired (deleted when the purge runs)
    data_retention_days  = 90
    data_retention_field = "created_at"    # default — any DateTimeField works
    data_retention_files = ["attachment"]  # delete the file with the row (#RET2c)

How it works

Running the cleanup

# Via Celery Beat (recommended — add to CELERY_BEAT_SCHEDULE):
"purge-expired-data": {
    "task": "snapadmin.purge_expired_data",
    "schedule": crontab(hour=1, minute=0),
}

# Manually via management command:
python manage.py snapadmin_purge_expired_data           # live run — deletes records
python manage.py snapadmin_purge_expired_data --dry-run  # preview only — no deletes

# Programmatically, per model (returns the number purged):
AuditLog.purge_expired()              # delete now
AuditLog.purge_expired(dry_run=True)  # count what *would* be deleted, delete nothing

Purging across every storage layer

The purge is storage-aware — it removes expired records from wherever the model actually keeps them, so personal data never lingers in a secondary store:

File payloads: files before rows

Deleting the row but not the file it references is the wrong outcome for a GDPR retention feature — the row is what remembers the file's name, so an orphaned file becomes unreachable and undeletable without a separate storage sweep. data_retention_files closes that gap, with two rules that make it safe to run unattended:

• Files are deleted before their row. If a file cannot be removed (a storage error), the row — and therefore the file's name — is left intact and purge_expired() raises SnapPurgeError instead of silently continuing, so the purge is retryable on the next run rather than orphaning the file permanently. A missing file (already gone) is treated as already-done, not an error.
• A path another live row still references is never deleted. Two rows can legitimately point at the same storage path; before removing a file, SnapAdmin checks whether any other row outside this purge still needs it and skips the delete if so (one extra query per distinct path) — "we deleted a file another row still points at" is unrecoverable, "we left a file behind" is a storage sweep.

dry_run=True touches nothing — no file is deleted and no row is counted as skipped, exactly as before data_retention_files existed.

The audit log, and export/reindex job cleanup

Two more tables grow forever unless something purges them, and neither is a SnapModel — so snapadmin.purge_expired_data covers each explicitly, alongside the per-model sweep above, every time it runs:

• The audit log (SnapadminAuditLog) — governed by SNAPADMIN_AUDIT_RETENTION_DAYS (default 365, i.e. on by default). Rows are append-only (save/delete raise once persisted); the purge uses QuerySet.delete(), the one sanctioned bypass of that guard, so the trail itself stays tamper-evident right up until the retention window closes. This does not change what manage.py snapadmin_audit_export --purge does — that command keeps working exactly as before, reading the same setting independently.
• Export/reindex jobs (SnapExportJob/SnapReindexJob) — governed by SNAPADMIN_EXPORT_RETENTION_DAYS, unset (off) by default — unlike the two sweeps above, this one deletes files a project may deliberately want to keep (a downloaded report, an archival export), so it needs an explicit opt-in. Once set, finished job rows past the window are deleted along with their published files (files before rows, same ordering rule as data_retention_files), and a second pass sweeps any export file left behind with no job row at all — the state a worker that died mid-export leaves. This assumes the export storage location (see Async Export) is used exclusively for SnapAdmin exports; do not point it at a bucket with unrelated files.

Every purge the package performs, in one place

Retention is real but was historically scattered across four unrelated tables — this table is the single answer to "what gets cleaned up, by what, and how often should I schedule it":

All five rows above run from the beat schedule in Celery & Periodic Tasks — the demo project's own CELERY_BEAT_SCHEDULE schedules every one of them.

🧾 GDPR Subject-Access Requests

data_retention_days answers "how old is too old"; a subject-access request answers a different question — "show (or delete) everything about this one person, right now". manage.py snapadmin_subject_request answers it by walking every registered model's own subject_path declaration, the same one snapadmin.E011/E012 require every registered model to state explicitly (declared, not guessed).

Declaring who a subject is

class Customer(SnapModel):
    email = SnapEmailField(...)
    is_data_subject   = True     # a valid --model entry point
    subject_identifier = "email"  # the field holding the raw identifier
    subject_path        = "email"  # a subject's own path always equals its identifier

class Order(SnapModel):
    customer = SnapForeignKey(Customer, on_delete=PROTECT)
    subject_path = "customer__email"   # one relation hop to the subject

class SomeOtherModel(SnapModel):
    subject_path = None   # explicit — this model carries nothing subject-scoped

subject_path is required on every registered model — None is a valid, explicit answer, but silence is not: snapadmin.E011 fails manage.py check for any registered model that never declares it at all, and snapadmin.E012 catches a declared-but-malformed one (a subject model whose own path doesn't match its identifier, a path over 3 relation hops, one that doesn't resolve via this model's own forward relations, or a multi-hop path on an ES_ONLY model — see the reference table below). The decorator route accepts the same three keywords: @snap_model(subject_path=..., is_data_subject=..., subject_identifier=...).

Running a request

# Export everything reachable from this subject, unmasked, as one bundle:
python manage.py snapadmin_subject_request export \
    --model demo.Customer --identifier alice@example.com --user dpo_operator

# ...optionally AGE-encrypted to a recipient (repeatable) — the plaintext is removed once encrypted:
python manage.py snapadmin_subject_request export \
    --model demo.Customer --identifier alice@example.com --user dpo_operator \
    --recipient age1qy...

# Preview a deletion — dry-run by default, deletes nothing:
python manage.py snapadmin_subject_request delete \
    --model demo.Customer --identifier alice@example.com --user dpo_operator

# Actually delete, once the preview looks right:
python manage.py snapadmin_subject_request delete \
    --model demo.Customer --identifier alice@example.com --user dpo_operator --confirm

Export: reuses the existing export machinery, unmasked

One SnapExportJob per matched model, run synchronously with filters={subject_path: identifier} and requested_by set to the resolved operator — the same masking bypass that already applies to a PII-privileged requester elsewhere produces the unmasked export, so there is no second "skip masking" code path to get wrong. A manifest.json lists every file, the row count per model, and who requested it. Pass one or more --recipient age/SSH public keys to encrypt the whole bundle in place afterward (the same AGE machinery backups use) — recommended, since an unmasked SAR bundle is exactly the kind of thing that should not sit in plaintext once written.

Deletion: dry-run by default, refuses rather than routes around a block

Both dry-run and --confirm run the identical pre-flight — a Django deletion Collector walk over every matched row, which discovers cascade spillover on its own (a more complete picture than the subject_path declarations alone: deleting a Customer also takes its CustomerProfile, since that relation is on_delete=CASCADE) — so the dry run is a genuine preview of what --confirm would do, not a separate, weaker check. If any matched row is protected (on_delete=PROTECT — the demo's Order.customer uses it), the whole run refuses up front and deletes nothing, rather than deleting in dependency order to route around it:

$ python manage.py snapadmin_subject_request delete --model demo.Customer \
      --identifier alice@example.com --user dpo_operator --confirm
REFUSED — deleting these rows is blocked by a protected relation: demo.Order
Nothing was deleted. Resolve the blocking rows manually (delete or reassign them) before retrying.

A deletion audit entry is written after a successful run — action delete, model subject_access_deletion, the per-model row counts, and the operator. This entry cannot itself be swept away by a later deletion for the same subject: SnapadminAuditLog is deliberately outside the general SnapAdmin registry (see Unalterable Audit Trail), so it carries no subject_path at all and is structurally invisible to this command's own matching sweep.

Reference

🔐 Field Encryption — Keys

Encrypted model fields keep ciphertext in the database and hand your code the ordinary Python value. All of that rests on one thing being configured correctly: the keyset. This section is the keyset — where the key comes from, how it rotates, and the startup checks that stop a column from quietly staying plaintext.

Generating a key

python manage.py snapadmin_encryption_key            # the first key
python manage.py snapadmin_encryption_key --rotate   # a key to prepend

The key is printed once, as the environment line to paste into your secret store — the command writes it nowhere. --rotate prints the new key plus the ids already in the keyset, never their material: rotating is prepending one line.

Where the key comes from

Four sources, most secure first. The first one configured wins — sources are never merged, so a stray environment variable can never silently half-override a secret store.

SNAPADMIN_ENCRYPTION = {
    # Ordered: the FIRST key encrypts, EVERY key decrypts.
    "KEYS": [{"id": "2026-09", "key": "<32 bytes, base64url>"}],

    # Better — keep the material out of settings entirely:
    "KEY_PROVIDER": "myapp.secrets.load_snapadmin_keys",
    "KEY_FILE": "/run/secrets/snapadmin_encryption",

    "STRICT": True,   # default
}

Rotation

The keyset is ordered: the first key encrypts everything written from now on, and every key in the list can decrypt. Rotating is therefore prepending, with no downtime and no migration:

1. manage.py snapadmin_encryption_key --rotate and prepend the printed line.
2. Deploy. New writes use the new key; existing rows keep opening with the old one, because every ciphertext records the id of the key it was written with.
3. Re-encrypt the stored rows, then drop the old key from the list — not before. Dropping a key while rows still name it makes those rows permanently unreadable.

Two rules the package enforces for you

Never SECRET_KEY. Reusing Django's SECRET_KEY as encryption key material is the classic mistake here: SECRET_KEY is rotated for session and CSRF reasons, and the damage only becomes visible after a rotation, when every encrypted column has already become unreadable. snapadmin.E017 fails manage.py check if the two are the same value.

Key material is never rendered. No repr, no str, no log line, no exception message and no snapadmin_info section emits key bytes — only a key's id and its fingerprint, a short digest safe to print and to compare between environments. A restore into an environment whose keyset fingerprint differs is the one failure that looks like data corruption but is not, which is why the fingerprint is displayable at all.

Startup checks

🏘️ Multi-Tenancy

Row-level tenant isolation, opt-in per model. A model declares itself tenant-scoped and adds a tenant column; every generated surface then requires a bound tenant to see or write any row of it — default-deny, not opt-out. Nothing about a model that never opts in changes.

from snapadmin import models as snap_models
from snapadmin.tenancy import tenant_field

class Order(snap_models.SnapModel):
    customer = snap_models.SnapForeignKey(Customer, on_delete=models.PROTECT)
    tenant_id = tenant_field()      # a plain, nullable, indexed CharField
    tenant_scoped = True            # opts this model into isolation

tenant_field() returns a pre-configured CharField — nullable so the migration it adds never breaks an existing row, indexed for the filter every scoped query runs. Override any keyword (max_length=, …) to fit a project's own tenant-identifier shape; declare a real ForeignKey by hand instead if the tenant is itself a project model. tenant_field (the model attribute, distinct from the factory function above) renames the column when set — otherwise it is "tenant_id".

Resolving the current tenant

Add the middleware, then point it at a resolver:

# settings.py
MIDDLEWARE = [
    # ... after AuthenticationMiddleware, so the resolver can read request.user
    "snapadmin.tenancy.SnapTenantMiddleware",
]
SNAPADMIN_TENANT_RESOLVER = "myproject.tenancy.resolve_tenant"       # request -> tenant value | None
SNAPADMIN_TENANT_USER_RESOLVER = "myproject.tenancy.resolve_for_user" # user -> tenant value | None

SNAPADMIN_TENANT_RESOLVER runs once per request, resolving the caller's tenant from whatever a project's own auth carries — a claim on the session/JWT, a subdomain, an SSO group. Unset, every request resolves to no tenant — the correct fail-closed default until a project configures one. SNAPADMIN_TENANT_USER_RESOLVER is the second half: an async export or import job has no request when a Celery worker actually runs it, so the tenant is resolved from the submitter once, at job-creation time, and stamped onto the job row for the worker to replay. See demo/core/tenancy.py for a complete (illustrative, email-domain-based) pair of resolvers wired into the demo project.

What "default-deny" means concretely

The one escape hatch: use_all_tenants()

Reserved for background code whose job is inherently cross-tenant — the retention purge (a row's age decides whether it is purged, not its tenant) and the Elasticsearch reindex (the index must stay complete across every tenant, or a verify pass would mismatch by construction against the whole index). Application code must never reach for it to work around a scoping failure:

from snapadmin.tenancy import use_all_tenants

with use_all_tenants():
    Order.objects.all()   # every tenant's rows, deliberately and audibly

A NULL tenant is unassigned data, not shared data

The column is nullable so the migration it adds never breaks an existing row — but a row with no tenant value matches no tenant's filter, by ordinary SQL equality semantics. It is simply invisible to every tenant until something assigns it, never a fallback any caller can reach.

Reference

🏢 Enterprise Config v0.1.0a8

Four settings-driven features that fit SnapAdmin's zero-boilerplate philosophy. Every one is inert on a stock single-database install — it does nothing until you configure it.

# settings.py
DATABASES = {"default": {...}, "read_replica": {...}}
SNAPADMIN_ANALYTICS_DB_ALIAS = "read_replica"

PII data masking

Declare sensitive fields once. They are obfuscated in the admin changelist, dropped from the admin change form, and masked in both REST API and GraphQL responses for anyone who is not a superuser or a holder of the snapadmin.view_raw_pii permission. Emails become a***@domain.com, other values +3********78. Masking is enforced on every path that could otherwise leak the raw value: a masked field can't be targeted by ?field=, ?ordering=field or ?search= for an unprivileged caller (silently ignored, not a 400), the async export (POST /api/exports/) masks rows unless the requester holds PII access, and the audit trail's changes diff is masked in the admin and in snapadmin_audit_export (pass --reveal-pii for the raw diff).

# settings.py
SNAPADMIN_MASKED_FIELDS = {
    "users.UserModel": ["email", "phone_number"],
    "customers.Profile": ["passport_number", "billing_address"],
}
# Grant trusted staff raw access:
#   assign the "snapadmin | api token | Can view unmasked PII data" permission.

A key that doesn't resolve to an installed model (snapadmin.E001) or a field name that doesn't exist on it (snapadmin.E002) is a startup error, not a silent no-op — masking a typo'd field would otherwise fail open.

Per-field rules — SNAPADMIN_MASKING_RULES

The setting above says which fields are sensitive; this one says how each is obfuscated, and who may see it raw. A rule takes a pattern (a regex applied with re.sub), a replacement (on its own, a flat redaction of the whole value), and/or a permission that unlocks that one field for whoever holds it — without granting the blanket snapadmin.view_raw_pii, which reveals every masked field of every model.

# settings.py
SNAPADMIN_MASKING_RULES = {
    "customers.Profile": {
        # keep the last four digits, star the rest → ************1111
        "card_number": {"pattern": r"\d(?=\d{4})", "replacement": "*"},
        # first two and last two characters only → SE…03
        "iban": {"pattern": r"^(\w{2}).*(\w{2})$", "replacement": r"\1…\2"},
        # never shown below the field permission
        "billing_address": {"replacement": "[redacted]",
                            "permission": "customers.view_profile_address"},
    },
}

Naming a field here also declares it sensitive, so this setting works on its own — SNAPADMIN_MASKED_FIELDS stays optional and unchanged, and a field listed only there keeps the built-in masker. Rules apply on every surface that masks: the admin changelist, the REST serializer, GraphQL, background exports and the audit-log diff. The matching check is masking.user_can_view_pii(user, "app.Model.field") — the field argument is additive, so existing calls are unaffected.

Patterns are compiled once and cached. One that fails to compile, one whose replacement references a group it does not have, one shaped like a catastrophic-backtracking bomb (a quantified group containing a quantifier, (a+)+), and any value longer than 4096 characters all fall back to the built-in masker and log the reason — every failure path degrades to more masking, never to raw data. A rule naming a model or field that does not exist would instead fail open, so it is a startup error (snapadmin.E003–E005) rather than a silent no-op.

🔐 Field-level permission guards — api_field_permissions

Masking says how an already-visible field is displayed; api_field_permissions says whether it is visible or writable at all — a different, orthogonal question. Declare a Django permission per field, per side:

class Employee(SnapModel):
    salary = snap_fields.SnapDecimalField(max_digits=10, decimal_places=2)

    api_field_permissions = {
        "salary": {"read": "hr.view_salary", "write": "hr.change_salary"},
    }

A caller lacking the named permission never sees the field's existence: absent from a REST response (not null, not an error — the key itself is gone) or nulled in GraphQL (the schema is built once at import time, so a per-request field cannot be removed from the response shape the way REST's serializer can — a documented, deliberate asymmetry, not an inconsistency). A denied write answers an explicit 400 naming the field, because a silently dropped write is a data-loss bug the caller cannot detect — a required field a role can't write simply cannot be created by that role, which is the correct, if blunt, outcome.

Rows 2 and 4, precisely: the permission gate decides whether the field appears at all; masking decides whether what appears is raw or starred. Gate first, mask second — a field can carry both a permission rule and a masking rule at once, and the two compose in that fixed order rather than racing.

Works on both doors: a SnapModel subclass sets it as a plain class attribute; a @snap_model-decorated plain model sets it via registry.register(Model, api_field_permissions={...}) (the decorator's own api_field_permissions= keyword is a follow-up). Applied so far to the two surfaces an external API consumer actually reaches — REST (the serializer, plus the ?field=/?ordering=/?search= oracle-prevention filters, same precedent as PII masking above) and GraphQL; the admin form and background export are a follow-up.

SSO / OAuth2 login buttons

SnapAdmin only renders the providers you already wired into AUTHENTICATION_BACKENDS / URLconf (django-allauth, social-auth, mozilla-django-oidc) — it adds no auth dependency. Configure once and get login-page buttons plus a public GET /api/sso-providers/ endpoint for headless frontends.

# settings.py
SNAPADMIN_SSO_PROVIDERS = {
    "azure":    {"label": "Login with Microsoft Enterprise", "url": "/accounts/azure/login/"},
    "keycloak": {"label": "Corporate Keycloak SSO", "url": "/api/v1/auth/keycloak/"},
}
# TEMPLATES → OPTIONS → context_processors: add "snapadmin.sso.sso_providers"
# In your admin/login.html override: {% include "snapadmin/sso_buttons.html" %}

A provider entry with no url, a protocol-relative url, or an absolute url outside SNAPADMIN_SSO_ALLOWED_HOSTS (when that list is non-empty) is dropped from the rendered buttons rather than shown broken — unset (the default) applies no host restriction, since most deployments legitimately point providers at an external identity provider. manage.py check catches all three at startup: a missing url is snapadmin.W003; a protocol-relative or off-allowlist url is snapadmin.W005.

# settings.py
SNAPADMIN_NESTED_APPS = {"snapadmin": "auth"}   # move snapadmin models under "auth"
SNAPADMIN_HIDDEN_APPS = ["silk"]                # hide these groups from the index
SNAPADMIN_APP_LABELS  = {"auth": "Administration"}  # rename a group heading

Unalterable audit trail DORA / ISO 27001

Django's built-in LogEntry is minimal and editable straight from the DB. SnapAdmin records a richer, append-only SnapadminAuditLog for every admin create/update/delete — who (actor + IP + User-Agent), what (target object + before/after field diff) and when (tz-aware timestamp). Rows are immutable at the ORM level (save/delete raise once persisted) and the admin is fully read-only.

# settings.py — on by default
SNAPADMIN_AUDIT_LOG_ENABLED = True
SNAPADMIN_AUDIT_RETENTION_DAYS = 365

# Export for a SIEM (newline-delimited JSON or CSV):
python manage.py snapadmin_audit_export --format json > audit.jsonl
python manage.py snapadmin_audit_export --since 2026-01-01 --action delete
python manage.py snapadmin_audit_export --purge   # also prune rows past retention

For defence against direct database tampering, layer a DB trigger / append-only role on top — the ORM guard protects the admin and application paths.

Reading the trail — diffs and the per-object timeline

The diff is stored as {"field": {"old": …, "new": …}} and rendered in the admin as a field-level table: one row per field, the value before, the value after. Values keep their JSON-native type, so 42 stays distinguishable from "42"; anything without a JSON representation (Decimal, dates, UUIDs, related objects) is stored as text. The old/new key names are part of the on-disk format and will not change.

Each entry's Object column links to that object's timeline — every change ever recorded for it, newest first, each as the same diff table:

/admin/snapadmin/snapadminauditlog/timeline/<app_label>/<model>/<object_id>/

Both views mask through SNAPADMIN_MASKED_FIELDS and SNAPADMIN_MASKING_RULES, and both are gated on the audit log's own view permission — the same one that already lists these rows — so reading the trail is never a way around masking. A long history is capped at the 100 most recent entries per page (override timeline_max_entries on the model admin); snapadmin_audit_export remains the way to read all of it.

Large-dataset performance

Every SnapAdmin admin auto-derives list_select_related from the FK columns it shows, and the REST API auto-select_relateds FKs and prefetch_relateds M2M — no N+1, zero config. On multi-million-row tables the changelist's SELECT COUNT(*) is the costliest query; EstimatedCountPaginator swaps it for PostgreSQL's instant reltuples estimate on unfiltered listings, staying exact for small or filtered views and non-PostgreSQL databases.

# settings.py — on by default
SNAPADMIN_ESTIMATED_COUNT = True
SNAPADMIN_ESTIMATED_COUNT_THRESHOLD = 100000   # estimate only above this row count

# Per model: also skip the second, unfiltered COUNT(*) the admin runs for "X total"
class BigModel(snap_models.SnapModel):
    show_full_result_count = False

Async background export Celery

Large synchronous exports time out. SnapAdmin offloads them to a Celery worker that streams a model's rows to CSV, JSON or XLSX. The line-based formats (csv, json) are written in resumable chunks, paged by a primary-key cursor rather than OFFSET so a concurrent insert/delete elsewhere in the table can't shift the window and skip or duplicate a row. Each chunk is written and fsync-ed to disk before its checkpoint is persisted, so a worker crash between the two can only leave an unconfirmed tail to discard on resume — never a duplicate. Jobs are also single-flight (an atomic pending/failed → processing claim stops a redelivered task or a manual re-trigger from running the same job on two workers at once) and cancellable mid-run. A worker that crashes mid-processing leaves the job stuck there until an operator resets it to pending to retry — there is no heartbeat/TTL auto-recovery. Jobs are private to their requester; the caller needs the target model's view permission. Finished files are published through Django's storage API (SNAPADMIN_EXPORT_STORAGE, a dotted Storage class) rather than read off the worker's local disk, so download/ works even when the web process and the worker don't share a filesystem; left unset it defaults to local FileSystemStorage, unchanged from before.

curl -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
     -d '{"app_label": "demo", "model": "Product", "export_format": "csv"}' \
     http://localhost:8000/api/exports/
# → {"id": "…", "status": "pending", "progress_percent": 0, "eta_seconds": null, …}

# Same job as a spreadsheet — needs pip install django-snapadmin[xlsx]
curl -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
     -d '{"app_label": "demo", "model": "Product", "export_format": "xlsx"}' \
     http://localhost:8000/api/exports/

XLSX — the container format extra

export_format="xlsx" writes a real workbook via openpyxl, installed with the [xlsx] extra. Values keep their types, so price arrives as a number Excel can sum and a DateTimeField as a date — converted to the project's current timezone and stripped of its tzinfo, which Excel has no concept of. Text that begins with = is stored as text, never as a formula: exported row data must not become something a spreadsheet executes when the file is opened.

A workbook is a zip archive that only becomes readable once it is closed, so it cannot be appended to chunk by chunk the way a CSV can. Rows are streamed into a temporary spool (memory stays at one chunk, whatever the export's size) and the finished workbook is moved into place in one step. Two consequences worth knowing before you pick the format:

• No resume. A re-dispatched XLSX job re-exports from the first row instead of continuing from its checkpoint — progress and cancellation work as usual, resume does not.
• No partial download. A cancelled or failed XLSX job leaves no file at all, where a cancelled CSV leaves the rows it managed to write.

Requesting xlsx without the extra is rejected by POST /api/exports/ with a 400 naming it, rather than accepted as a job that could only fail in the worker.

Custom row sources — SNAPADMIN_EXPORT_SOURCES

By default an export streams model.objects.filter(**filters) as raw column rows. Three shapes don't fit that: a result set defined by a structured Elasticsearch query (routing it through filters would force the DB-fallback scan the ES query exists to avoid); an explicit key list ("export exactly these records" — encoding it as a __in filter re-evaluates a giant clause on every cursor page); or a custom document shape (not raw values() rows). Register a source and the writer keeps everything else — the resumable pk-cursor chunking, progress, cancellation and storage — while your source owns only what rows to emit and how each looks:

# settings.py — {name: "dotted.path.to.factory"}, factory(job) -> source
SNAPADMIN_EXPORT_SOURCES = {
    "product_catalog": "myapp.exports.product_catalog_source",
}

# myapp/exports.py
class ProductCatalogSource:
    def __init__(self, job):
        qs = Product.objects.all()
        if job.filters:
            qs = qs.filter(**job.filters)
        self._qs = qs.order_by("pk")
    def field_names(self):                 # CSV header / row-dict keys
        return ["id", "catalog_line"]
    def count(self):                       # drives progress / ETA
        return self._qs.count()
    def iter_batches(self, *, cursor, chunk_size):
        # yield (rows, next_cursor); next_cursor is checkpointed and passed
        # back on resume, so continue deterministically from it. Mask here.
        while True:
            page = self._qs.filter(pk__gt=cursor) if cursor is not None else self._qs
            rows = list(page[:chunk_size].values("id", "name", "price"))
            if not rows:
                return
            batch = [{"id": r["id"], "catalog_line": f'{r["name"]} (${r["price"]})'} for r in rows]
            cursor = str(rows[-1]["id"])
            yield batch, cursor

def product_catalog_source(job):
    return ProductCatalogSource(job)

Create the job with source="product_catalog" (a field on SnapExportJob) and it runs through your source instead of the ORM default; a blank source is byte-for-byte the built-in export. The demo registers exactly this product_catalog source (demo/apps/shop/export_sources.py). An unknown source name fails the job cleanly (never the worker). Because your source owns PII masking on the rows it emits, apply masking there if the document exposes protected fields — use snapadmin.masking.mask_field(app_label, model, field, value, user), the same choke point the built-in source goes through, so configured rules apply to your rows too.

🗄️ Database Sharding & Replica Routing

A separate, more general mechanism from the single-alias read-replica routing above — for a project partitioning data across multiple physical databases, not just steering reads to one replica. Inert unless configured: with SNAPADMIN_SHARDING unset or ENABLED: False, nothing changes — no new DATABASES entry, no extra router, no query overhead.

Two configuration shapes resolve to the same thing. The simple path — a flat list of DSNs the module slices into shards/replicas automatically:

# settings.py
SNAPADMIN_SHARDING = {
    "ENABLED": True,
    "SHARDING_ENABLED": True,    # partition data across shards
    "MIRRORING_ENABLED": True,   # give each shard read replicas
    "REPLICAS_PER_SHARD": 1,     # 1 primary + 1 replica per shard, sliced in order
    "DATABASES": [
        "postgres://user:pass@s1-primary:5432/db",
        "postgres://user:pass@s1-replica:5432/db",
        "postgres://user:pass@s2-primary:5432/db",
        "postgres://user:pass@s2-replica:5432/db",
    ],
}

Or full manual control — an explicit mapping naming exactly which DSN is which shard's primary/replica:

SNAPADMIN_SHARDING = {
    "ENABLED": True,
    "STRATEGY": "range",             # modulo | hash | range | custom
    "SHARDS": {
        "shard_1": {
            "PRIMARY": "postgres://user:pass@s1-primary:5432/db",
            "REPLICAS": ["postgres://user:pass@s1-replica:5432/db"],
            "RANGE": (0, 1000000),   # only read for STRATEGY == "range"
        },
        "shard_2": {
            "PRIMARY": "postgres://user:pass@s2-primary:5432/db",
            "RANGE": (1000001, 2000000),
        },
    },
}

A model opts in with shard_key — the field to shard by, or True for the project-wide default (SNAPADMIN_SHARDING['SHARD_KEY'], default "id") — mirroring how tenant_scoped opts a model into multi-tenancy. No model, including Django's own auth/sessions/ admin tables, is ever routed across shards without explicitly asking:

class Order(SnapModel):
    shard_key = "customer_id"
    ...

from snapadmin.sharding.decorators import snap_master_only, snap_target

with snap_master_only():
    Order.objects.filter(id=order_id).update(status="paid")
    assert Order.objects.get(id=order_id).status == "paid"  # no replication lag

@snap_target(shard="shard_2")
def read_from_shard_2():
    return list(Order.objects.all())

manage.py snap_migrate runs migrations against every shard's primary only — sequentially, or all at once with --parallel — and never touches a replica, since replication already propagates schema at the database layer. manage.py snapadmin_db_backup does the same for backups: with sharding enabled, the "db" bundle part becomes one independently-checksummed "db.<shard_name>" part per shard's primary.

📥 Bulk Import

The write-side counterpart to async export, mirroring its architecture (chunking, progress, resumability) for the opposite direction: reading rows from a CSV or NDJSON file into a model, via manage.py snapadmin_import and a SnapImportJob (see snapadmin.importing for the full contract).

python manage.py snapadmin_import --model demo.Product --file products.csv
python manage.py snapadmin_import --model demo.Product --file p.json --format json
python manage.py snapadmin_import --model demo.Product --file p.csv \
    --map '{"Product Name": "name"}' --natural-key name --on-conflict update
python manage.py snapadmin_import --model demo.Product --file products.csv --resume

• Column mapping is header-name matching by default (case/whitespace/underscore- insensitive, against both the field name and its verbose_name), plus an optional explicit --map that wins wherever a header is named in it. An unmapped column is reported in the run's summary and skipped — never guessed at, never a hard failure.
• The duplicate key (--natural-key) is a field name or a comma-separated list. Left unset it defaults to the model's first unique=True field, or the primary key if the file actually carries a mapped column for it; with neither, every row is a create (there is nothing to detect a duplicate with).
• --on-conflict is fail (the default), skip or update. The default is fail — an import that silently overwrites production rows because nobody passed a flag is the same class of bug this project's write-surface hardening exists to close. A "fail" duplicate is reported as a failed row, never a failed run — one bad or duplicate row must never abort a run processing a million others.
• Validation runs through the model's own field validators — full_clean() on the constructed (or updated) instance, so every Snap*Field's extension/size/format rule applies for free. No parallel validation layer.
• The report is one NDJSON line per row — {"row": N, "action": "created"|"updated"|"skipped"|"failed", "pk": …, "errors": {...}} — plus one {"summary": {...}} line at the end, written through the same storage seam the export API downloads from. Its path is printed when the command finishes.
• Crash-safe, chunk-checkpointed resume (--resume): every row's write, the job's own progress counters and the report's confirmed byte length commit together as one transaction per chunk — a crash loses at most one chunk's progress, and a resumed run can never re-create a row an earlier attempt already committed.
• A write surface from the first line, not a follow-up. A column targeting a field outside api_write_fields, inside api_exclude_fields, or a masked/PII field with no --requested-by user holding PII access, fails the whole run up front, naming the field — never a silent write. A model that is api_read_only (or whose api_http_method_names excludes every write verb) refuses the import entirely.

🧩 Integrating with Your Project

SnapAdmin drops into a real project without bridge code — authentication, the user model and the Elasticsearch client are all pluggable, and imports have a first-class helper.

Pluggable API authentication (JWT / session / custom)

By default the API accepts SnapAdmin's own token auth. Point SNAPADMIN_API_AUTHENTICATION_CLASSES at any DRF authenticators — model CRUD, schema and token endpoints all honour it. With non-token auth, model permissions fall back to plain Django model permissions (a token additionally applies its allowed_models scope):

SNAPADMIN_API_AUTHENTICATION_CLASSES = [
    "rest_framework_simplejwt.authentication.JWTAuthentication",
    "rest_framework.authentication.SessionAuthentication",
    "snapadmin.api.authentication.APITokenAuthentication",   # keep tokens working too
]

JWT in three steps (djangorestframework-simplejwt):

# 1. settings.py — add the authenticator above + the app
INSTALLED_APPS += ["rest_framework_simplejwt"]

# 2. urls.py — obtain / refresh endpoints
from rest_framework_simplejwt.views import TokenObtainPairView, TokenRefreshView
urlpatterns += [
    path("api/token/",         TokenObtainPairView.as_view()),
    path("api/token/refresh/", TokenRefreshView.as_view()),
]

# 3. authenticate, then call any SnapAdmin endpoint with the Bearer token
#   curl -H "Authorization: Bearer $ACCESS" .../api/models/demo/Product/

ELASTICSEARCH_KWARGS = {                 # merged into Elasticsearch(...)
    "api_key": "…", "ca_certs": "/etc/ssl/es.pem",
    "request_timeout": 30, "max_retries": 3, "retry_on_timeout": True,
}
# …or full control (cloud_id, sniffing, custom transport):
SNAPADMIN_ES_CLIENT_FACTORY = "myproject.es.make_client"   # zero-arg callable → client

python manage.py snapadmin_reindex                       # all ES-enabled SnapModels
python manage.py snapadmin_reindex --model demo.Product  # one model
python manage.py snapadmin_reindex --chunk-size 1000     # tune bulk batch size
python manage.py snapadmin_reindex --limit 1000          # probe run — first 1000 rows only
python manage.py snapadmin_reindex --tune                # relax refresh/replicas for the load
python manage.py snapadmin_reindex --no-tune             # force tuning off (overrides the setting)
python manage.py snapadmin_reindex --parallel 4          # fan out with helpers.parallel_bulk
python manage.py snapadmin_reindex --resume              # continue a crashed run from its checkpoint
python manage.py snapadmin_reindex --verify               # count the index against the source afterwards
python manage.py snapadmin_reindex --progress-interval 30 # at most one progress line per 30s

SNAPADMIN_REINDEX_API_ENABLED = True    # the endpoint 404s until you set this
SNAPADMIN_REINDEX_API_ASYNC = False     # True → snapadmin.run_es_reindex Celery task (202 + task_id)

from snapadmin.etl import upsert_from_source

def rows_from_remote():          # any iterable of dicts (e.g. a streamed cursor)
    for r in remote_cursor:
        yield {"code": r.code, "base": "EUR", "rate": r.rate}

summary = upsert_from_source(
    ExchangeRate, rows_from_remote(),
    unique_fields=["code"],      # conflict target (needs a unique constraint)
    batch_size=1000,
)
# {"processed": 5231, "batches": 6, "reindex": {"indexed": 5231}}

from snapadmin.etl import upsert_from_source, stale_sync

seen = {r.code for r in remote_cursor}      # natural keys present in THIS sync
upsert_from_source(ExchangeRate, rows_from_remote(), unique_fields=["code"])
stale_sync(
    ExchangeRate, seen,
    key_field="code",                       # the same unique natural key
    max_fraction=0.1,                       # refuse if >10% would be deleted
)
# {"total": 5231, "stale": 4, "deleted": 4, "fraction": 0.0008, "dry_run": False}

result = stale_sync(ExchangeRate, seen, key_field="code", on_exceed="skip")
if result["aborted"]:
    logger.warning("rates prune skipped: %.0f%% stale", result["fraction"] * 100)

run_started = timezone.now()
# the upsert stamps last_seen = run_started on every reported row …
upsert_from_source(ExchangeRate, rows_with_last_seen(run_started), unique_fields=["code"])
# … then prune everything the sync left behind, entirely DB-side:
stale_sync(
    ExchangeRate,
    strategy="last_seen",
    last_seen_field="last_seen",
    run_started=run_started,
    max_fraction=0.1,
)

🎛️ SNAPADMIN_PROFILE Presets

A new project has roughly 90 SNAPADMIN_* settings to decide before it has a sensible install. SNAPADMIN_PROFILE collapses that to one line by picking sane defaults for the handful of settings that actually differ depending on how you use the package — everything else keeps its built-in default regardless of profile.

# settings.py
SNAPADMIN_PROFILE = "admin"  # "admin" | "api" | "full" (default: unset — no profile applied)

• admin — admin UI only. Turns REST, GraphQL, Swagger and GraphiQL off, for a project that only wants the generated Django admin and nothing else exposed over HTTP.
• api — REST + GraphQL on, admin used minimally. Turns REST, GraphQL and Swagger on explicitly; GraphiQL follows DEBUG. Settings-identical to full today — the two differ as declarations of intent, and as the places future api- or admin-specific settings will attach to.
• full — every generated surface on: REST, GraphQL and Swagger, with GraphiQL following DEBUG.

Precedence: an explicit setting always wins. A profile only fills in a setting nothing else configured — get_setting(name, default) checks, in order: an explicit Django setting, then the active profile's preset, then the built-in default. Leaving SNAPADMIN_PROFILE unset skips the profile step entirely, so every existing install resolves exactly as it did before this feature existed — that is the upgrade guarantee, and it is pinned by a test that walks every setting the package reads.

Since 0.1.0b8, full and "no profile" are no longer the same thing. They used to be: every preset value equalled the built-in default, so full was a documented no-op. Then SNAPADMIN_REST_API_ENABLED and SNAPADMIN_GRAPHQL_ENABLED flipped to False (see the 1.0 migration guide), and a profile that merely mirrored the defaults would have inverted with them — api, whose whole purpose is "REST + GraphQL on", would have turned them off. Each profile now states its values outright, so a profile means what its name says no matter what the defaults do. Leaving SNAPADMIN_PROFILE unset is still exactly the pre-profile behaviour.

A misconfigured profile is caught at manage.py check time rather than failing silently: an unrecognised SNAPADMIN_PROFILE value is snapadmin.E006, and an explicit setting that quietly overrides what the active profile would otherwise set is snapadmin.W009 — both advisory-friendly, since overriding a profile on purpose is a normal, supported thing to do. See Environment Variables Reference for every check id.

🔧 Environment Variables Reference

Every SNAPADMIN_* knob is a plain Django setting — you can set it directly in settings.py. The demo project additionally reads them from an env file: copy demo/dist.env to demo/.env and edit it there.

🧩 Ecosystem Compatibility

How SnapAdmin coexists with popular third-party Django packages.

The two rules that make SnapAdmin safe by default

1. SnapAdmin only auto-registers SnapModel subclasses. Every other model in your project — including third-party ones (taggit.Tag, guardian's permission models, reversion.Version, django_celery_beat, …) — is left entirely alone. There is no global admin takeover.
2. Auto-registration never clobbers an existing admin. If a model is already registered (by you or a package) when SnapAdmin runs, it skips it (AlreadyRegistered). Your custom admin wins.

Two escape hatches let a package take over a SnapModel's admin when you want it to:

admin_mixins classes are placed first in the MRO, so their get_queryset / changelist_view / actions wrap SnapAdmin's, which in turn wraps Django/Unfold's ModelAdmin.

Beyond mixins, three more SnapModel attributes tune the generated ModelAdmin without an admin.py: admin_overrides — a dict of attributes/methods merged on last so they win over the defaults (e.g. {"list_per_page": 25}); and css_admin_files / js_admin_files (a static path or list) appended to the generated Media.css / Media.js. These are the supported alternative to hand-writing class Media or your own admin.site.register — SnapAdmin owns registration via register_admin() (one model) and register_all_admins() (a whole app label). The zero-padded id helper snapadmin.models.formatted_id is public for use in overrides. SnapAdmin serves its own admin assets under the snapadmin/ static namespace (snapadmin/js/admin.js, snapadmin/css/admin.css, …); when migrating from the predecessor package, update any hardcoded drofji_autoadmin/… (or bare admin.js) static path to it.

select2 is opt-in, not automatic, on a plain <select>. The shipped admin.js only initialises select2 on an element carrying a snapadmin-select2 class (or a data-snapadmin-select2 attribute) — add that class to a form field's widget attrs to opt it in. This is deliberately narrow: an earlier, broader selector reached the changelist's own action dropdown, and select2 taking over an Alpine-bound <select> (as the Unfold theme renders it) silently broke bulk actions.

Package matrix

Legend: ✅ compatible — no SnapAdmin change needed beyond the documented hook.

Worked example — import/export + versioning on one model

from import_export.admin import ImportExportModelAdmin
from reversion.admin import VersionAdmin
from snapadmin import models as snap_models, fields as snap_fields

class Invoice(snap_models.SnapModel):
    number = snap_fields.SnapCharField(max_length=32, searchable=True, show_in_list=True, show_in_form=True)

    # Compose ecosystem admin behaviour with SnapAdmin's auto-config:
    admin_mixins = [ImportExportModelAdmin, VersionAdmin]

The generated admin is Invoice → ImportExportModelAdmin → VersionAdmin → (SnapAdmin mixins) → ModelAdmin: import/export buttons, version history, and SnapAdmin's field-driven list_display / search / filters / PII masking / audit logging, all at once.

🩺 Diagnostics — snapadmin_info

One command reports SnapAdmin's whole configuration and the health of everything it connects to — useful when deploying, debugging a staging box, or feeding a monitoring dashboard. It reads configuration and probes services only; it changes nothing, and secrets (database passwords, broker credentials, token values) are never printed.

snapadmin-info                   # full text report
snapadmin-info --json            # machine-readable (monitoring / CI)
snapadmin-info --section version # one section (repeatable)
snapadmin-info --brief           # top-level values only
snapadmin-info --health-check    # probes only; non-zero exit on failure

Flags

Sections

• System checks — a per-severity count of Django's system checks, not their text. Django normally prints every message in full before any management command runs, which buried this report behind a screen of advisory text, so snapadmin_info opts out of that pass and summarises here instead: --verbose prints the messages, and errors are always listed because they block a working deployment (they also make --health-check fail). Run manage.py check for the full text with hints.
• Version & Status — SnapAdmin version, the Django/Python runtime, and every SNAPADMIN_* feature toggle at its effective value. Run from inside a tree extracted by snapadmin-demo, it also reports which release that tree came from, and says so plainly when the tree is older (or newer) than the installed package — a mismatch that otherwise shows up only as behaviour you thought was already fixed.
• Feature adoption — a commerce-readiness ✓/✗ checklist of which business-important capabilities are actually on or in use in this project: backups, retention-based deletion, audit trail, PII masking, the REST/GraphQL APIs, API tokens, Elasticsearch, background tasks, health/error alerting, rate limiting, the read-only / write-allowlist / delete guards, plain models opted in with @snap_model (these are the ones the reindex and the retention purge skip) and SSO. Where a capability is adopted per-model or per-field (retention, masking, read-only models, …), --verbose adds a one-line count. Unlike the toggle list above, the signal here is adoption — a model actually declaring retention, a masked field actually configured — so you can see at a glance what is protected and what is left open.
• Database — engine, name, host, port and user (never the password), reachability, table count and — where the backend exposes it — on-disk size.
• Elasticsearch — collapses to disabled when off; otherwise cluster reachability, status and index count, plus the DB_ONLY / DUAL / ES_ONLY tally of your models.
• Celery & Broker — broker and result-backend URLs with the password redacted, the number of online workers, and the configured Beat schedule (collapses to disabled when Celery isn't installed).
• Models & Security — every registered SnapModel with its storage mode, retention window, API write-allowlist and PII-masking flags, plus API-token counts (total / active / expired — counts only, never the token value).

Sample output

The report is written to be read at a glance: a run of booleans collapses into one on line and one off line, and a uniform list of records — the model inventory — becomes an aligned table instead of repeating every key name once per row.

🩺 System checks
  Warnings: 2
  Ok: ✓
  Detail: run `manage.py check` for the full text
📦 Version & Status
  Version: 0.1.0b8
  Status: pre-release
  Django: 6.0.6
  Python: 3.12.4
🧩 Feature adoption
  ✓ on   Rest api · Graphql · Audit trail · Retention purge · Pii masking · Api tokens ·
         Read only models · Write allowlist
  ✗ off  Backups · Elasticsearch · Health alerts · Delete guard · Sso
🗄 Database
  Engine: postgresql
  Name: snapadmin_db
  Host: localhost
  Ok: ✓
  Tables: 24
🔍 Elasticsearch
  Enabled: ✓
  Ok: ✓
  Cluster status: green
  Indices: 3
⚙ Celery & Broker
  Enabled: ✓
  Broker: redis://***@localhost:6379/0
  Workers online: 1
📊 Models & Security
  Models:
    Total: 3
    Items:
      Model            Es mode  Retention days  Write restricted  Masked
      ───────────────  ───────  ──────────────  ────────────────  ──────
      shop.AuditLog    DB_ONLY  90              ✓                 ✗
      shop.Customer    DB_ONLY  —               ✓                 ✓
      shop.Product     DUAL     —               ✓                 ✗
  Masked fields: 2

⚖️ Licence Audit — snapadmin_license_check

The runtime counterpart of THIRD_PARTY_NOTICES.md: it audits the licences of the SnapAdmin dependencies actually installed in your environment and tells you whether your install is safe for commercial/proprietary use. A curated map of every declared dependency (SPDX licence, tier, core-vs-extra, bundled-licence caveats) is overlaid on what pip resolved.

snapadmin-license-check                   # full report
snapadmin-license-check --json            # machine-readable (CI)
snapadmin-license-check --critical-only   # only 🟡/🔴 licences
snapadmin-license-check --compatible-with MIT   # per-package compatibility
snapadmin-license-check --verbose         # + uncurated deps + notes

As with snapadmin-info, the dashed shim, the underscored snapadmin_license_check and python manage.py snapadmin_license_check are the same command.

Tiers

Flags

Sample output

📋 SnapAdmin licence audit
Core dependencies
  🟢 Django                 BSD-3-Clause        installed 6.0
  🟢 djangorestframework    BSD-3-Clause        installed 3.16
  …
Optional extras
  🟢 [elasticsearch] elasticsearch   Apache-2.0   installed 8.19
  🟡 [backup] paramiko               LGPL-2.1     installed 3.5
       Weak copyleft — fine for proprietary use as an unmodified, dynamically-imported dependency.
  🔴 [wysiwyg] django-ckeditor-5     GPL-2.0-or-later OR Commercial   not installed
       bundles: The BSD Python wrapper ships CKEditor 5, which is GPL/commercial.

Commercial compatibility: ✓ OK — installed licences are proprietary-safe

Vulnerability scan: no vulnerability scanner installed — `pip install pip-audit` then run `pip-audit`.
Curated data last reviewed: 2026-09-03 (0 days ago)

🌍 Internationalization (i18n)

SnapAdmin's UI strings are wrapped in gettext and ship compiled translation catalogs for 10 locales — English, Russian, German, Swiss German (de_CH, ß→ss), French, Swiss French (fr_CH), Spanish, Italian, Polish, Dutch. A missing string falls back to English automatically.

Wire up Django's locale machinery in your project (the demo project already does this):

# settings.py
MIDDLEWARE = [..., "django.middleware.locale.LocaleMiddleware", ...]  # after SessionMiddleware
LANGUAGES = [("en", "English"), ("ru", "Russian"), ("de", "German"), ("de-ch", "Swiss German"), ...]

# urls.py — backs the language switcher
path("i18n/", include("django.conf.urls.i18n")),

Drop the accessible language selector into any page (for example an admin login or base template override):

{% include "snapadmin/language_switcher.html" %}

It posts to Django's set_language view and renders nothing when only one language is configured. The switcher builds its option list from Django's own get_available_languages, so it follows your LANGUAGES setting rather than a catalog shipped by SnapAdmin.

The theme's strings are translated too

django-unfold ships no translation catalogs at all, so on a themed admin its own chrome — “All applications”, “Apply Filters”, “No results found”, “Select action”, the command-palette hints — used to stay English around a page whose labels were translated. That is the mixed-language admin people report.

Django resolves a string against the catalogs of every installed app, so SnapAdmin simply answers for them: snapadmin/theme_i18n.py declares those msgids and the ten shipped catalogs translate them. Nothing to enable, and Unfold is not patched — remove the theme and the extra entries are just unused.

🎨 Theming & Styles

SnapAdmin ships its admin styling as three layers: one shared sheet plus exactly one theme layer, so an install that doesn't use Unfold gets a modern form layout, and an install that does is never fought by one.

The two theme layers are mutually exclusive, and that is the scoping mechanism — neither carries a theme prefix, so exactly one of them ever reaches the page. Shared design tokens (--primary-color, --radius, …) are defined once in the core sheet and referenced by both.

Django's built-in auth admin under the theme

Unfold ships template overrides for django.contrib.auth but leaves the matching admin classes and forms to the project. Left unwired, the built-in User screen renders Unfold's templates against Django's forms — and the mismatch is not cosmetic: the password row comes out empty with no way to change the password, because Unfold's default password-hash template is written for Django < 5.1 and the "Reset password" button lives in a newer variant that only Unfold's own UserChangeForm selects.

SnapAdmin wires it for you from SnapAdminConfig.ready(): User and Group are re-registered as (DjangoAdmin, unfold.admin.ModelAdmin) with Unfold's UserChangeForm, UserCreationForm and AdminPasswordChangeForm. It is deliberately conservative — only a registration whose admin class is exactly Django's stock one is replaced, so if you have subclassed UserAdmin yourself, your class is left completely alone (wire Unfold in yourself in that case). Without the theme installed the step is a no-op.

# settings.py — opt out and keep Django's stock auth admin as-is
SNAPADMIN_THEME_AUTH_ADMIN = False

🧬 Extending & Overriding

SnapAdmin is built to extend without forking. When a generated surface isn't enough, reach for the closest hook below — each snippet drops into your project.

1. Add your own field type

Mix SnapField into any Django field, then run incoming kwargs through _initializeSnapLogic() (consumes the Snap-only options like searchable, filterable, show_in_list) and handleDjangoKwargs() (returns the Django-safe kwargs):

# yourapp/fields.py
from django.db import models
from snapadmin.fields import SnapField

class SnapMoneyField(models.DecimalField, SnapField):
    def __init__(self, **kwargs):
        kwargs.setdefault("max_digits", 12)
        kwargs.setdefault("decimal_places", 2)
        kwargs.setdefault("filterable", True)          # Snap option
        kwargs = self._initializeSnapLogic(**kwargs)   # consume Snap options
        cleaned = self.handleDjangoKwargs(**kwargs)    # Django-only kwargs
        super().__init__(**cleaned)

2. Reuse the built-in validators

The validators behind SnapPhoneField / SnapColorField / SnapFileField are public and work on any plain Django field:

from snapadmin.validators import SnapPhoneValidator, SnapFileValidator

phone    = models.CharField(max_length=20, validators=[SnapPhoneValidator()])
contract = models.FileField(validators=[
    SnapFileValidator(allowed_extensions=["pdf"], max_size_bytes=10 * 1024 * 1024),
])

3. Extend a SnapModel

SnapModel is a normal abstract model — add methods, a custom manager, override save(), or tune the ES hooks. The admin/API surfaces are driven off your declared fields, so extra methods never break them:

class Product(snap_models.SnapModel):
    name  = snap.SnapCharField(max_length=200, searchable=True)
    price = SnapMoneyField()

    es_storage_mode   = snap_models.EsStorageMode.DUAL
    es_index_settings = {"number_of_shards": 2}   # override index creation

    def save(self, *args, **kwargs):
        self.name = self.name.strip()
        super().save(*args, **kwargs)             # keeps ES mirroring intact

4. Add custom REST endpoints (or override CRUD for one model)

The REST layer is one generic DynamicModelViewSet routed by app_label/model_name. To customise a single model, register your own DRF viewset in your urls.py, before SnapAdmin's routes so it wins for that path — reuse Snap's serializer via get_serializer_for_model():

from rest_framework import viewsets, decorators
from rest_framework.routers import DefaultRouter
from snapadmin.api.serializers import get_serializer_for_model
from yourapp.models import Product

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = get_serializer_for_model("yourapp", "product")

    @decorators.action(detail=False)
    def on_sale(self, request):
        page = self.paginate_queryset(Product.objects.filter(price__lt=100))
        return self.get_paginated_response(self.get_serializer(page, many=True).data)

router = DefaultRouter()
router.register(r"api/product", ProductViewSet, basename="product")
urlpatterns = [*router.urls, path("", include("snapadmin.urls"))]

Prefer to keep the generic viewset but change how it behaves globally? Subclass DynamicModelViewSet and point your own route at it.

5. Swap auth, permissions & the ES client (config, no code)

6. Override admin templates & the dashboard

SnapAdmin's templates live under the snapadmin/ template namespace, so Django's normal template resolution lets you shadow any of them. Put your project's templates/ dir ahead of the app in TEMPLATES['DIRS'], then drop in a same-named file:

yourproject/templates/snapadmin/dashboard.html            # replace the system dashboard
yourproject/templates/snapadmin/email/error_alert.html    # rebrand the spike-alert email
yourproject/templates/snapadmin/email/error_digest.html   # rebrand the daily digest

7. Package layout — the module map

Everything is importable from its own module (from snapadmin.backup import run_backup); the most common names are also re-exported from the top level (from snapadmin import SnapModel, SnapCharField). The re-exports are lazy, so importing snapadmin — or a console script that runs before Django is configured — never eagerly loads the Django-backed modules.

No module ever moves or is renamed — a deep import path is a permanent contract. Structure improves additively only: new modules, blessed top-level re-exports, docstrings.

🔄 Migration Guides

Hard migrations — upgrades that need manual steps beyond reading the release notes — get a dedicated guide in docs/migrations/. Most releases don't need one; SnapAdmin aims for backward compatibility on every change.

🧭 AI Assistants — llms.txt & the module map

If you build with an AI coding assistant, SnapAdmin ships two entry points written for machines rather than browsers. Both are kept in sync with the code by the test suite, so an assistant reading them will not be taught something that has since been renamed or removed.

llms.txt — a map of this documentation

llms.txt follows the llmstxt.org convention: plain Markdown, no navigation chrome, no JavaScript. It states what SnapAdmin is, carries the three-step quickstart, lists the facts an assistant should not have to infer — snap-only field kwargs add no migration, import paths are the public contract, the Unfold theme is optional, misconfiguration surfaces as snapadmin.W001–W018 and snapadmin.E001–E019 — and then links every section of this page with a line describing what it covers.

Point your assistant at the URL, or paste the file into its context. A byte-identical copy sits at the repository root and travels inside the source distribution, so it is available offline too.

The module map — available from any install

The snapadmin package docstring is a quickstart plus a map of the package: what each module and management command is for, the SNAPADMIN_* setting families, and the optional extras. Unlike llms.txt this needs no network and no repository access — it is what an assistant finds when it reads the installed package, and what you get from:

python -c "import snapadmin; help(snapadmin)"

🚀 Quick Start — snapadmin-demo

The fastest way to see SnapAdmin running, with no clone and no existing project. pip install django-snapadmin puts a snapadmin-demo command on your PATH (also python -m snapadmin.quickstart):

pip install django-snapadmin
snapadmin-demo

It downloads the demo/ directory from the GitHub source tarball of the matching release tag (the wheel doesn't ship it), caches and checksums it under ~/.cache/snapadmin-demo/ so re-runs are instant and work offline, extracts only demo/ into the current directory, then installs its requirements, applies migrations, seeds example data and starts the server at http://localhost:8000.

Refreshing an existing demo tree

pip install -U django-snapadmin upgrades the package. The demo/ directory it extracted earlier is an ordinary directory and is not upgraded with it — it keeps serving the models, templates and settings of the release it came from, which is a reliable way to chase problems the installed release already fixed. Re-run snapadmin-demo to bring the tree up to date:

pip install -U django-snapadmin
snapadmin-demo --skip-install --no-serve   # refresh the tree in place

Each extraction leaves a small .snapadmin-demo.json stamp at the root of the tree — the release it came from and the list of files that extraction wrote. On the next run that stamp gives you:

• a line naming both versions before anything is touched (“Refreshing the existing demo tree at … : v0.1.0b5 → v0.1.0b6”);
• deletion of files the new release dropped. Extraction overlays a tree, so without this a template removed upstream would linger and keep rendering. Only files listed in the previous stamp are candidates — anything you added yourself (a .env, your own app, an edited settings file that still exists upstream) is never in that list and is never deleted;
• a drift line in manage.py snapadmin_info when the tree and the installed package disagree, so the report says so instead of leaving you to guess.

Flags

Configuration

--interactive runs a short wizard — run mode (runserver / Docker), database (SQLite / PostgreSQL, with connection details), Elasticsearch on/off, admin password, secret-key generation and debug — and writes a .env the demo reads. Capture and share a setup so a whole team gets the same environment:

snapadmin-demo --interactive --save-config team.ini   # answer once, save it
snapadmin-demo --load-config team.ini                 # a colleague replays it

The same choices are available as non-interactive flags for CI — --mode, --database, --db-host, --db-password, --elasticsearch / --no-elasticsearch, --admin-password, --debug. (The demo runs on SQLite or PostgreSQL; MySQL is not one of its backends.)

🌟 Running the Demo

The repository includes a complete demo project to explore all features.

Via Docker (Recommended)

git clone https://github.com/drofji/django-snapadmin.git
cd django-snapadmin
cp demo/dist.env demo/.env
docker compose -f demo/docker-compose.yml up --build

With Traefik — Local Development (HTTP)

Access the app at http://snapadmin.localhost/ with a BasicAuth-protected dashboard:

docker compose -f demo/docker-compose.yml -f demo/docker-compose.traefik.local.yml up --build

# App:              http://snapadmin.localhost/admin/
# Traefik dashboard: http://traefik.localhost/  (admin / changeme)

On Windows, add to C:\Windows\System32\drivers\etc\hosts:

127.0.0.1 snapadmin.localhost traefik.localhost

With Traefik — Production (HTTPS + Let's Encrypt)

Automatic TLS certificates for your custom domain. Set in demo/.env:

TRAEFIK_DOMAIN=admin.mycompany.com
TRAEFIK_ACME_EMAIL=your@email.com
TRAEFIK_DASHBOARD_CREDENTIALS=admin:$$apr1$$...   # see demo/dist.env for generation
ALLOWED_HOSTS=admin.mycompany.com
DEBUG=False

Then start:

docker compose -f demo/docker-compose.yml -f demo/docker-compose.traefik.prod.yml up -d

# App:               https://admin.mycompany.com/admin/
# Traefik dashboard:  https://traefik.admin.mycompany.com/  (BasicAuth)
# HTTP → HTTPS redirect is automatic for all routes

Generating Dashboard Credentials

# Requires apache2-utils (apt) or httpd-tools (yum)
echo $(htpasswd -nb admin yourpassword) | sed -e 's/\$/\$\$/g'
# Paste result into TRAEFIK_DASHBOARD_CREDENTIALS in demo/.env

Manual / Local Setup

git clone https://github.com/drofji/django-snapadmin.git
cd django-snapadmin
python -m venv .venv && source .venv/bin/activate
pip install -r demo/requirements.txt
pip install -e .

python demo/manage.py migrate
python demo/manage.py seed_demo
python demo/manage.py runserver

Building images with automatic retention

For the test/demo image, demo/scripts/docker_build.sh builds, tags by build-day, and self-prunes so old images never pile up:

demo/scripts/docker_build.sh                              # image=snapadmin-test, keep 3 build-days
IMAGE=myimg demo/scripts/docker_build.sh                  # custom image name
SNAPADMIN_IMAGE_KEEP_DAYS=5 demo/scripts/docker_build.sh  # widen the window

Retention policy — one build per day, keep the last N build-days (N defaults to 3, override via SNAPADMIN_IMAGE_KEEP_DAYS):

• Collapse within a day — images are tagged snapadmin-test:YYYY-MM-DD plus a moving :latest. Rebuilding the same calendar day re-points that day's tag at the new image; the superseded build becomes a dangling layer and is reclaimed.
• Rolling N-day window — the last build of each of the N most-recent build-days is kept; when an (N+1)-th distinct build-day appears, the oldest day's image is pruned.
• History gaps are irrelevant — "N days" means the last N build-days, not calendar days. Idle days never consume a slot.

The pruner can also run standalone (e.g. in CI), with a dry-run mode:

python -m demo.scripts.docker_retention prune --image snapadmin-test --dry-run

Container health check — Docker, Coolify, Dokploy, Kubernetes

SnapAdmin serves an unauthenticated probe at GET /api/health/. Point your platform's health check at it — it is the one endpoint that actually reports whether this instance can serve:

An anonymous caller receives only {"status": "healthy"} — the per-service breakdown is reserved for an authenticated session or token — so the endpoint is safe to expose to a load balancer or an external uptime monitor.

Dockerfile (the demo image ships exactly this, and bundles curl for it):

HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
    CMD curl -fsS http://localhost:8000/api/health/ || exit 1

Docker Compose — use this when the image has no HEALTHCHECK of its own, or to override it per environment:

services:
  app:
    healthcheck:
      test: [ "CMD", "curl", "-fsS", "http://localhost:8000/api/health/" ]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s     # covers migrate + collectstatic on first boot

Coolify / Dokploy / Caprover — these expose the same Docker fields in their UI. The values to enter:

Kubernetes — the same endpoint works for both probes; give the liveness probe a longer failure threshold so a brief database blip restarts nothing:

readinessProbe:
  httpGet: { path: /api/health/, port: 8000 }
  initialDelaySeconds: 15
  periodSeconds: 10
  failureThreshold: 3
livenessProbe:
  httpGet: { path: /api/health/, port: 8000 }
  initialDelaySeconds: 60
  periodSeconds: 30
  failureThreshold: 6

Static, media and backups on remote storage

Local disk is fine for one container. The moment there are two, media must move off the local filesystem: a file uploaded through instance A is a 404 on instance B, and a container restart loses it. The demo settings switch Django 5+ STORAGES from a single environment variable, and the same block is what you would copy into your own project.

# .env — any S3-compatible provider, same variables
SNAPADMIN_STORAGE_BACKEND=s3
AWS_ACCESS_KEY_ID=…
AWS_SECRET_ACCESS_KEY=…
AWS_STORAGE_BUCKET_NAME=my-bucket
AWS_S3_ENDPOINT_URL=https://fsn1.your-objectstorage.com   # empty for real AWS
AWS_S3_REGION_NAME=fsn1
AWS_QUERYSTRING_AUTH=True        # signed, time-limited URLs — correct for a private bucket
AWS_S3_FILE_OVERWRITE=False      # never let one upload silently replace another
AWS_DEFAULT_ACL=                 # modern buckets disable ACLs; sending one fails the PUT
SNAPADMIN_STATIC_ON_S3=False     # static is public+immutable; WhiteNoise is usually enough

It needs pip install "django-storages[s3]" (BSD-3-Clause). Nothing is imported while STORAGE_BACKEND=local — STORAGES holds a dotted path Django resolves lazily — so the dependency stays optional.

Database backups are a separate mechanism — SnapAdmin writes dumps to its own destinations rather than through Django's storage layer, so a Storage Box works directly:

# Mount a Storage Box over CIFS, then point the network destination at it
//u123456.your-storagebox.de/backup  /mnt/box  cifs  credentials=/etc/box.cred,uid=1000  0 0
SNAPADMIN_BACKUP_NETWORK_DIR=/mnt/box/snapadmin

📦 Demo App — Model Overview

The demo/ app contains pre-built models that showcase every SnapAdmin feature. Most differ by Elasticsearch storage mode; the last differs by how it was declared at all.

🌱 Seed Command

The seed_demo management command populates the database with realistic demo data in seconds.

python manage.py seed_demo          # default: 20 products, 10 customers, 5 orders
python manage.py seed_demo --no-index  # skip ES indexing (no ES cluster needed)

The command is idempotent — running it multiple times adds more data without duplicating existing records.