graphene-django/docs/mutations.rst

Mutations
=========

Introduction
------------

Graphene-Django makes it easy to perform mutations.

With Graphene-Django we can take advantage of pre-existing Django features to
quickly build CRUD functionality, while still using the core `graphene mutation <https://docs.graphene-python.org/en/latest/types/mutations/>`__
features to add custom mutations to a Django project.

Simple example
--------------

.. code:: python

    import graphene

    from graphene_django import DjangoObjectType

    from .models import Question


    class QuestionType(DjangoObjectType):
        class Meta:
            model = Question


    class QuestionMutation(graphene.Mutation):
        class Arguments:
            # The input arguments for this mutation
            text = graphene.String(required=True)
            id = graphene.ID()

        # The class attributes define the response of the mutation
        question = graphene.Field(QuestionType)

        @classmethod
        def mutate(cls, root, info, text, id):
            question = Question.objects.get(pk=id)
            question.text = text
            question.save()
            # Notice we return an instance of this mutation
            return QuestionMutation(question=question)


    class Mutation(graphene.ObjectType):
        update_question = QuestionMutation.Field()


Django Forms
------------

Graphene-Django comes with mutation classes that will convert the fields on Django forms into inputs on a mutation.

DjangoFormMutation
~~~~~~~~~~~~~~~~~~

.. code:: python

    from graphene_django.forms.mutation import DjangoFormMutation

    class MyForm(forms.Form):
        name = forms.CharField()

    class MyMutation(DjangoFormMutation):
        class Meta:
            form_class = MyForm

``MyMutation`` will automatically receive an ``input`` argument. This argument should be a ``dict`` where the key is ``name`` and the value is a string.

DjangoModelFormMutation
~~~~~~~~~~~~~~~~~~~~~~~

``DjangoModelFormMutation`` will pull the fields from a ``ModelForm``.

.. code:: python

    from graphene_django.forms.mutation import DjangoModelFormMutation

    class Pet(models.Model):
        name = models.CharField()

    class PetForm(forms.ModelForm):
        class Meta:
            model = Pet
            fields = ('name',)

    # This will get returned when the mutation completes successfully
    class PetType(DjangoObjectType):
        class Meta:
            model = Pet

    class PetMutation(DjangoModelFormMutation):
        pet = Field(PetType)

        class Meta:
            form_class = PetForm

``PetMutation`` will grab the fields from ``PetForm`` and turn them into inputs. If the form is valid then the mutation
will lookup the ``DjangoObjectType`` for the ``Pet`` model and return that under the key ``pet``. Otherwise it will
return a list of errors.

You can change the input name (default is ``input``) and the return field name (default is the model name lowercase).

.. code:: python

    class PetMutation(DjangoModelFormMutation):
        class Meta:
            form_class = PetForm
            input_field_name = 'data'
            return_field_name = 'my_pet'

Form validation
~~~~~~~~~~~~~~~

Form mutations will call ``is_valid()`` on your forms.

If the form is valid then the class method ``perform_mutate(form, info)`` is called on the mutation. Override this method
to change how the form is saved or to return a different Graphene object type.

If the form is *not* valid then a list of errors will be returned. These errors have two fields: ``field``, a string
containing the name of the invalid form field, and ``messages``, a list of strings with the validation messages.


Django REST Framework
---------------------

You can re-use your Django Rest Framework serializer with Graphene Django mutations.

You can create a Mutation based on a serializer by using the `SerializerMutation` base class:

.. code:: python

    from graphene_django.rest_framework.mutation import SerializerMutation

    class MyAwesomeMutation(SerializerMutation):
        class Meta:
            serializer_class = MySerializer


Create/Update Operations
~~~~~~~~~~~~~~~~~~~~~~~~

By default ModelSerializers accept create and update operations. To
customize this use the `model_operations` attribute on the ``SerializerMutation`` class.

The update operation looks up models by the primary key by default. You can
customize the look up with the ``lookup_field`` attribute on the ``SerializerMutation`` class.

.. code:: python

    from graphene_django.rest_framework.mutation import SerializerMutation
    from .serializers import MyModelSerializer


    class AwesomeModelMutation(SerializerMutation):
        class Meta:
            serializer_class = MyModelSerializer
            model_operations = ['create', 'update']
            lookup_field = 'id'

Overriding Update Queries
~~~~~~~~~~~~~~~~~~~~~~~~~

Use the method ``get_serializer_kwargs`` to override how updates are applied.

.. code:: python

    from graphene_django.rest_framework.mutation import SerializerMutation
    from .serializers import MyModelSerializer


    class AwesomeModelMutation(SerializerMutation):
        class Meta:
            serializer_class = MyModelSerializer

        @classmethod
        def get_serializer_kwargs(cls, root, info, **input):
            if 'id' in input:
                instance = Post.objects.filter(
                    id=input['id'], owner=info.context.user
                ).first()
                if instance:
                    return {'instance': instance, 'data': input, 'partial': True}

                else:
                    raise http.Http404

            return {'data': input, 'partial': True}



Relay
-----

You can use relay with mutations. A Relay mutation must inherit from
``ClientIDMutation`` and implement the ``mutate_and_get_payload`` method:

.. code:: python

    import graphene
    from graphene import relay
    from graphene_django import DjangoObjectType
    from graphql_relay import from_global_id

    from .queries import QuestionType


    class QuestionMutation(relay.ClientIDMutation):
        class Input:
            text = graphene.String(required=True)
            id = graphene.ID()

        question = graphene.Field(QuestionType)

        @classmethod
        def mutate_and_get_payload(cls, root, info, text, id):
            question = Question.objects.get(pk=from_global_id(id)[1])
            question.text = text
            question.save()
            return QuestionMutation(question=question)

Notice that the ``class Arguments`` is renamed to ``class Input`` with relay.
This is due to a deprecation of ``class Arguments`` in graphene 2.0.

Relay ClientIDMutation accept a ``clientIDMutation`` argument.
This argument is also sent back to the client with the mutation result
(you do not have to do anything). For services that manage
a pool of many GraphQL requests in bulk, the ``clientIDMutation``
allows you to match up a specific mutation with the response.



Django Database Transactions
----------------------------

Django gives you a few ways to control how database transactions are managed.

Tying transactions to HTTP requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A common way to handle transactions in Django is to wrap each request in a transaction.
Set ``ATOMIC_REQUESTS`` settings to ``True`` in the configuration of each database for
which you want to enable this behavior.

It works like this. Before calling ``GraphQLView`` Django starts a transaction. If the
response is produced without problems, Django commits the transaction. If the view, a
``DjangoFormMutation`` or a ``DjangoModelFormMutation`` produces an exception, Django
rolls back the transaction.

.. warning::

    While the simplicity of this transaction model is appealing, it also makes it
    inefficient when traffic increases. Opening a transaction for every request has some
    overhead. The impact on performance depends on the query patterns of your application
    and on how well your database handles locking.

Check the next section for a better solution.

Tying transactions to mutations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A mutation can contain multiple fields, just like a query. There's one important
distinction between queries and mutations, other than the name:

..

    `While query fields are executed in parallel, mutation fields run in series, one
    after the other.`

This means that if we send two ``incrementCredits`` mutations in one request, the first
is guaranteed to finish before the second begins, ensuring that we don't end up with a
race condition with ourselves.

On the other hand, if the first ``incrementCredits`` runs successfully but the second
one does not, the operation cannot be retried as it is. That's why is a good idea to
run all mutation fields in a transaction, to guarantee all occur or nothing occurs.

To enable this behavior for all databases set the graphene ``ATOMIC_MUTATIONS`` settings
to ``True`` in your settings file:

.. code:: python

    GRAPHENE = {
        # ...
        "ATOMIC_MUTATIONS": True,
    }

On the contrary, if you want to enable this behavior for a specific database, set
``ATOMIC_MUTATIONS`` to ``True`` in your database settings:

.. code:: python

    DATABASES = {
        "default": {
            # ...
            "ATOMIC_MUTATIONS": True,
        },
        # ...
    }

Now, given the following example mutation:

.. code::

    mutation IncreaseCreditsTwice {

        increaseCredits1: increaseCredits(input: { amount: 10 }) {
            balance
            errors {
                field
                messages
            }
        }

        increaseCredits2: increaseCredits(input: { amount: -1 }) {
            balance
            errors {
                field
                messages
            }
        }

    }

The server is going to return something like:

.. code:: json

    {
        "data": {
            "increaseCredits1": {
                "balance": 10.0,
                "errors": []
            },
            "increaseCredits2": {
                "balance": null,
                "errors": [
                    {
                        "field": "amount",
                        "message": "Amount should be a positive number"
                    }
                ]
            },
        }
    }

But the balance will remain the same.