Postgraphile: document how to do a mutation

[barbalex]

I may have missed it. But is there an example of how to

• update a field value
• create a new dataset
• delete a dataset

when using postgraphql?

I am new to this. Examples on querying abound and that is very simple. But I have now spent a lot of time trying to mutate and have not succeeded.

[benjie]

Hi @barbalex, you're right - we should link to the GraphQL docs to help people get started with mutations and similar. This link should help quite a bit:

http://graphql.org/learn/queries/#mutations

Once you understand how mutations work in GraphQL the next step is to find out what mutations are available with your PostGraphQL schema; the easiest way to do this is to spin up PostGraphQL and then visit the /graphiql endpoint (note the i is important) and then click the Docs link top right, then browse through the generated mutation docs - you can then practice them by running them in the left pane - it auto-completes for you!

---

Hmmm... The /graphiql endpoint isn't working for me today, seems that unpkg.com do not appreciate us using them in this way? @calebmer do you have the same issue -> do we need to switch to bundling, using a CDN, or self-hosting the relevant files?

[benjie]

Have filed the unpkg.com issue as https://github.com/calebmer/postgraphql/issues/249; they claim to be a CDN so it totally should work...

[barbalex]

@benjie Thanks for the answer. I did do that.

For a newbie this is a little overwhelming though, as there are a lot of concepts to grasp at once: Not only how this works in graphql but also how postgraphql builds the schema.

And looking at a graphiql endpoint mutation docs for a database with (in my case) 40 tables is a little like searching for a needle in a haystack.

I just felt that a simple example for each type of mutation would have been an immense help for a newbie like me.

Thanks for contributing to this GREAT project!

[barbalex]

...and feel free to close this issue

[benjie]

@barbalex I see, so you want documentation on basic insert/update/delete for a "template" table - that does seem like an omission in the docs. We're planning on adding documentation around all of this as part of https://github.com/calebmer/postgraphql/issues/162 but no-one has got around to it yet. If you fancied having a shot at writing some documentation around mutations once you've grokked how it works that would be super valuable because you'll still remember what it was like to be a newbie and thus know which parts people are likely to trip over!

[barbalex]

I will watch https://github.com/calebmer/postgraphql/issues/162 and see if I can manage that

[fasiha]

I set up the superb forum_example tutorial and thanks to Graphiql autocomplete (which mostly worked), I was able to figure out the following queries and mutations—maybe they’ll be useful to others, or possibly added to the forum tutorial. Run these one at a time:

{query {allPeople}}

# If you try to run the above, Graphiql will expand it to:
{query {allPeople {edges {node {id}}}}}

# Navigating the help from: query → Person shows the full set of fields you can
# ask about each person. Tweak the above to:
{query {allPeople {edges {node {id firstName fullName}}}}}

# Navigating the help from root → query → allPeople → PeopleConnection shows
# that the autofilled value of `edges` is one of many, e.g., the following works too,
# and produces data in a slightly different shape:
{query {allPeople {nodes {id firstName fullName}}}}

# Nagivating the help from root → query → allPeople reveals you can parameterize the
# query itself by, e.g., first, last, offset, orderBy, etc:
{query {allPeople(first: 3, orderBy: LAST_NAME_DESC) {nodes {id firstName fullName}}}}

# Mutations: nagivating to root → mutation → registerPerson, I see (1) "Type" which
# turns out to be what the mutation returns, and (2) "Arguments" which is what the
# mutation needs.

# If you type in the following, mostly following autocomplete, a tooltip pops up
# saying the "input" needs firstName, lastName, etc.:
mutation {registerPerson(input: {})}

# So fill those in:
mutation {registerPerson(input:{firstName:"Mei", lastName:"Kusakabe", email:"[email protected]", password:"nekobasu"})}

# If you run the above, Graphiql appends `{clientMutationId}` as the response from
# `registerPerson`, which will be null. Navigating the help from mutation → registerPerson
# → RegisterPersonPayload, we see that `clientMutationId` is the first on the list and
# probably why Graphiql autocompleted this return data. Looks like we can get `person`
# back too:

# Try the following:
mutation {registerPerson(input:{firstName:"Neko", lastName:"Basu", email:"[email protected]", password:"mei"}) {person {id}}}

# With the above as exposition, I was able to cobble together the following mutation:
mutation {createPost(input:{post:{authorId:11, headline:"Totoro rocks!", body:"¡Sure does!"}}) {clientMutationId}}
# I got `11` from the `allPeople` query.

[ortonomy]

@fasiha -- this is sooo good

[hmaurer]

I think this is now properly documented on the website. Close @benjie ?

[benjie]

I don’t think it is well documented yet; this page could do with a list of examples/explanations:

https://www.graphile.org/postgraphile/crud-mutations/

[benjie]

There's examples in the docs now:

https://www.graphile.org/postgraphile/examples/