From 6822547d2fcced03180a783708b97f9b09a1db31 Mon Sep 17 00:00:00 2001 From: onoy42 Date: Sat, 21 May 2022 18:29:40 +0200 Subject: [PATCH] Add warning on concurrent updates See: https://github.com/jazzband/django-payments/issues/309 --- docs/install.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/install.rst b/docs/install.rst index c54133b..1dda055 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -136,6 +136,25 @@ Prepare a template that displays the form using its ``action`` and ``method``:

+Mutating a `Payment` instance +----------------------------- + +When operating `BasePayment` instances, care should be take to only save +changes atomically. If you were to load an instance into memory, mutate, and +then save it, you might overwrite fields that have been updated due to handling +a notification from the processor. Keep in mind that some processors implement +"at least once" notification delivery. + +In general, you should either: + +- Use atomic updates only specifying the relevant fields. For example, if the + application-local ``Payment`` class has a custom field named + ``discount_card_code``, use + ``BasePayment.objects.filter(pk=payment_id).update(discount_card_code="123XYZ")``. + This is the recommended approach. +- Lock the database row while mutating a python instance of ``BasePayment`` (may + negatively affect performance at scale). + .. _settings: Additional Django settings