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 `__ 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.