Management Commands

Think of it as

The value of a management command is not that it saves you writing a script. It is that it runs *inside* your project: settings loaded, apps populated, database connections configured, the ORM usable. A loose script has to reproduce all of that and will drift from it; a command cannot drift, because it is the same code your site runs. That is why the roadmap's list of uses — backfills, reconciliation, cleanup, imports, exports, maintenance — belongs here rather than in a `scripts/` directory. Think of the structure as a contract in two halves. `add_arguments` is the *interface*: everything the command accepts, with its type and its help text, declared in one place that `--help` reads. `handle` is the *implementation*, and it receives the parsed values as keyword arguments — a dashed flag arrives with underscores, so `--dry-run` is `options["dry_run"]`. Keeping the halves separate matters more than it looks, because argparse is doing real work for you: types are converted and validated before `handle` runs, so a non-integer id is rejected with a usage message rather than crashing halfway through a loop that has already written to the database. The design instinct worth forming early is to make the interface explicit rather than clever. Prefer a required positional over a magic default, because a backfill that silently defaults to "everything" is the command people run once by accident. Prefer an opt-in `--apply` over an opt-out `--no-dry-run`, so the dangerous direction is the one you have to type. And give every argument `help=` text: the person reading `--help` at 3 a.m. during an incident is usually not the person who wrote it.

Think of it as

A management command has two audiences and they want different things. A person wants progress, reassurance and a readable summary. A machine — cron, a CI step, a Kubernetes Job, the shell operator in `&&` — wants an exit code, and it is the only thing it can actually see. Almost every bad command experience comes from serving only the first. The exit code is the contract. Zero means success, non-zero means failure, and `CommandError` is the mechanism: Django catches it, formats it to stderr, and exits with `returncode`, which defaults to 1. A command that catches its own exceptions, prints "failed", and returns normally exits zero — so the cron job that wraps it reports success, the alert never fires, and the failure is discovered days later by a human noticing missing data. That is the single highest-cost mistake in this section, because it is invisible in every test that only reads output. The stream split is the same contract at a finer grain. Progress and diagnostics belong on stderr, results belong on stdout, and keeping them apart is what lets `command > data.csv` work while the operator still sees what is happening. Progress reporting itself has a rule worth stating: report against a denominator. "Processed 12,000 rows" tells a person nothing about whether to wait; "12,000 / 380,000, batch 24" tells them how long. And for long runs, log rather than only print — a progress line lost to a closed terminal cannot answer "where did it get to?" the next morning, whereas a structured log line with the same fields can.

Think of it as

Design the command around the assumption that it will be interrupted, because at production scale it will be — a deploy, an OOM kill, a network blip, someone pressing Ctrl-C. Once you accept that, the three properties stop looking like polish and start looking like the minimum. Idempotency is the one to design first, and the reliable way to get it is to select by *outcome* rather than by position. A query for "rows that still need the work" — `filter(currency="")` — naturally shrinks as the command progresses, so re-running it after a crash picks up exactly where it stopped, with no bookmark to store and nothing to skip. A command driven by an offset or a hard-coded id range has neither property: re-running repeats work, and resuming needs state you have to keep correct yourself. Transaction scope is the second decision, and it is a genuine trade. One transaction around everything gives you all-or-nothing, and on a large table it also gives you a hours-long write lock, a bloated undo log, and a rollback at the end that can take as long as the work did. One transaction per row gives you neither locking problems nor any grouping guarantee. A batch — a few hundred to a few thousand rows in one `atomic()` block — is the usual answer, and the batch size is exactly the knob controlling how much work an interruption costs you. The dry run is the third, and the important detail is *how* it is implemented. Printing what the command would do, computed by a separate code path, is a dry run that can lie: the reporting path and the writing path drift, and the one you tested is not the one that runs. The honest version executes the real path and refuses to persist — either by gating each write on the flag, or by running inside a transaction that is deliberately rolled back. And whichever you choose, the default should be the safe one. A command whose default is "write" is a command someone runs by accident.

Think of it as

Sort the six by what happens if the command is wrong, and the right amount of caution falls out. Reconciliation is the safe end: it reads two sources and reports the differences, so a bug produces a wrong report rather than wrong data. That makes it the natural *first* command to write for any integration, and the natural companion to the risky ones — a backfill you cannot verify afterwards is a backfill you should not run. Exports are nearly as safe, with one caveat that is easy to miss: they leave the system, so the risk is not corruption but disclosure, and the question is who can run them and what ends up in the file. Imports and backfills sit in the middle. Both write, both usually touch a lot of rows, and both need the full apparatus — a dry run that is the default, batched transactions, idempotent selection, and a report of what changed. The distinction between them is where the data comes from: a backfill derives new values from data you already have, so it is deterministic and re-runnable; an import brings in values from outside, so it has to answer what happens when row 4,000 of 10,000 is invalid, and it needs a stable key if re-running is not to duplicate everything. Cleanup is the dangerous end, because deletion is the one operation you cannot dry-run *after the fact*. Cascades are the specific trap: Django's default `on_delete=CASCADE` means deleting what looks like one row can remove a subtree, and the count you get back is the only warning you will get. Maintenance is the odd one out — refreshing a materialised view, rebuilding a search index, expiring sessions — because the work is usually cheap and repeatable, but it runs on a schedule, which means nobody is watching. That makes the exit code and the log line the whole of its interface, and it is why a maintenance command that fails silently can be broken for months.