{"canonical_url":"https://engineer.company/glossary/idempotent/","content_markdown":"# Idempotent\n\n## What it is\n\nAn operation is idempotent when performing it several times has the same effect\nas performing it once, and the property is called idempotence or idempotency.\nThe word comes from mathematics, where a function is idempotent when applying it\nto its own result changes nothing, so that f(f(x)) equals f(x): rounding down a\nnumber that has already been rounded down gives the same number.\n\nIn software the useful test is a second run. Setting a value is idempotent,\nbecause the second run writes the value that is already there. Adding to a value\nis not, because the second run adds again:\n\n```sql\n-- idempotent: a second run sets the same value\nUPDATE accounts SET plan = 'pro' WHERE id = 42;\n\n-- not idempotent: a second run adds ten more\nUPDATE accounts SET credits = credits + 10 WHERE id = 42;\n```\n\nHTTP gives the word its most precise definition. RFC 9110 calls a request method\nidempotent when several identical requests are intended to have the same effect\non the server as a single one, and it lists PUT, DELETE and the safe methods\nGET, HEAD, OPTIONS and TRACE. Two details in that definition matter. The\nproperty covers the effect the client asked for, so a server is free to log\nevery request separately. And the response may differ: a second DELETE of the\nsame resource can answer 404 where the first answered 200, and the method is\nstill idempotent, because the resource is gone either way. PATCH sits outside\nthe list. RFC 5789 says it is neither safe nor idempotent, although a client can\nsend a particular PATCH in an idempotent way by making it conditional, with a\nstrong ETag in an If-Match header, so that a repeated copy is refused once the\nfirst has changed the resource.\n\nSafe is the stricter of the two promises. A safe method in RFC 9110's sense is\nessentially read-only, so every safe method is idempotent, while DELETE is\nidempotent without being safe.\n\n## Why it matters\n\nNetworks lose answers. When a client sends a request and the connection drops\nbefore the response arrives, it cannot tell whether the server never saw the\nrequest, saw it and stopped, or carried it out and lost the reply. Repeating the\nrequest is the obvious recovery, and idempotence is what makes the repetition\nharmless. RFC 9110 builds its retry rules on exactly that. An idempotent request\ncan be repeated automatically after a communication failure. A client should not\nretry a non-idempotent request automatically unless it knows the request is\nidempotent in practice or can tell that the original was never applied, and a\nproxy must never retry one on its own.\n\nQueues raise the same question at scale. Many message systems promise delivery\nat least once: a consumer that crashes after doing its work and before\nacknowledging the message is handed the same message again. Delivery exactly\nonce across a network is a far harder promise, so the practical answer is a\nconsumer for which a second delivery changes nothing. Configuration management\ndepends on the property too. A tool that brings servers to a declared state runs\nagain and again, after every change and often on a schedule, and each run has to\nleave a correct server exactly as it found it.\n\nThe real decision is how to get idempotence where an operation lacks it by\nnature, and there are three common answers. The first is design: express the\nchange as a target state rather than a step, so \"make sure this line is in the\nfile\" instead of \"append this line\". The second is a key: the client attaches a\nunique identifier to the request, the server records it under a unique\nconstraint, and a repeat finds the record and gets the original result back\ninstead of a second action. The third is to check before acting, which is how\nmost Ansible modules work: they compare the current state with the desired one\nand exit without acting when the two already match. Each has a cost.\nTarget-state design needs a clear model of the end state, keys need storage and\na rule for how long they are kept, and checking first needs a reliable way to\nread the current state.\n\n## What it looks like in practice\n\nThe company's own servers are configured with Ansible, and on that project\n[idempotence is a contract: a converged host reports zero changes](/portfolio/servers-you-can-rebuild-from-scratch/).\nProvisioning with no arguments converges every host to its declared state, and a\nplay that cannot report zero changes on a host that is already correct counts as\nunfinished. That makes idempotence something every run measures rather than\nsomething one hopes for.\n\nThe same idea, applied to data, is behind\n[a test that runs the nineteen-step build pipeline twice](/portfolio/held-the-generator-to-981-tests-and-92-coverage/).\nThe page names the kind of bug it exists for: a generator that works the first\ntime and corrupts the second, through steps that insert without checking or\ndepend on the order of an earlier step's output. The test builds the database\nfrom an empty file, takes a snapshot, runs the whole pipeline again over the\nresult and requires the second pass to change nothing, down to row counts,\ncontents and identifiers. The test provides repeat-run evidence for the inputs and database state it exercises.\n\nFor selling limited stock, the note on\n[selling the last ticket exactly once](/notes/selling-limited-stock-without-overselling/)\ncombines a key with conditional writes. Every checkout carries an idempotency\nkey, and the holds table carries `UNIQUE (tenant_id, idempotency_key)`, so a\nretried click gets back the hold it already has instead of a second unit. A\nrelease that runs twice, from a timeout and a cancel button for instance, gives\nthe unit back once, because it credits the stock only when its own update\nchanged exactly one row. Further along, every message consumer is idempotent,\nkeyed by the order: messages arrive at least once, and idempotency makes that\neffectively once.\n\n## Where it goes wrong\n\n**A retried request charges twice.** A POST that creates a payment, an order or\nan email is not idempotent by default, and a client or proxy that retries it\nafter a timeout creates a second one. Give these requests an idempotency key\nthat the server stores under a unique constraint, and return the stored result\nwhen the same key comes back.\n\n**An empty result is read as an error.** In PostgreSQL,\n`INSERT ... ON CONFLICT DO NOTHING` skips a row that would violate a unique\nconstraint, and `RETURNING` gives back only rows that were actually inserted or\nupdated. A repeated insert of the same row therefore returns nothing, which is\nthe correct outcome of a second run. Code that treats the empty result as a\nfailure turns a harmless retry into an error page; it should look up the row\nthat is already there.\n\n**A command task changes the host on every run.** Ansible's documentation says\nmost modules check whether the desired state has already been reached, and also\nthat \"not all playbooks and not all modules behave this way\". A task that runs a\ncommand is the usual exception, because the command is arbitrary and Ansible\ncannot know what it does. The command module's `creates` option skips the step\nwhen a given file already exists, `removes` runs it only while the file is still\nthere, and `changed_when` defines which outcome counts as a change. A command\ntask with none of them runs again on every converge, whatever state the host is\nin.\n\n**A counter counts the retry.** Under delivery at least once, a consumer that\nincrements a counter or sends a notification for each message does it twice for\na message delivered twice. Store the message's business key alongside the\neffect, in the same transaction, and skip any key that is already stored.\n\n**The second run corrupts what the first one built.** A step can be correct on\nan empty database and wrong on a full one, inserting a duplicate, renumbering\nidentifiers or relying on an order the first run left behind. A test that starts\nfrom nothing and runs once will pass all the same. Run the whole job twice and\nrequire the second run to change nothing, as the pipeline test above does.\n\n## Further reading\n\n- [RFC 9110, section 9.2.2: Idempotent Methods](https://www.rfc-editor.org/rfc/rfc9110#name-idempotent-methods)\n  — HTTP's definition, the idempotent methods and the rules for automatic\n  retries.\n- [RFC 5789: PATCH Method for HTTP](https://www.rfc-editor.org/rfc/rfc5789) —\n  why PATCH is neither safe nor idempotent, and how a conditional request makes\n  one safe to repeat.\n- [Ansible: Introduction to playbooks](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html)\n  — desired state, idempotency and check mode in Ansible's own words.\n- [Ansible: command module](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/command_module.html)\n  — the `creates` and `removes` options that make a command safe to rerun.\n- [PostgreSQL: INSERT](https://www.postgresql.org/docs/current/sql-insert.html)\n  — `ON CONFLICT` and what `RETURNING` gives back when a row already exists.\n\n\u003chttps://engineer.company/glossary/idempotent/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"What makes an operation idempotent, when a retry, a rerun or a duplicate message needs it, and the counters, inserts and commands that break it.","formats":{"gemtext":"https://engineer.company/glossary/idempotent/index.gmi","gopher":"https://engineer.company/glossary/idempotent/gophermap","html":"https://engineer.company/glossary/idempotent/","json":"https://engineer.company/glossary/idempotent/index.json","markdown":"https://engineer.company/glossary/idempotent/index.md","pdf":"https://engineer.company/glossary/idempotent/index.pdf"},"kind":"page","language":"en","title":"What does idempotent mean?","url":"https://engineer.company/glossary/idempotent/","version":1}