Announcing Hasura GraphQL Engine v2.2.0

Let’s first take a moment to appreciate the numerology of today’s release. No matter how you slice it, releasing version 2.2.0 on 02.02.22 ticks all the boxes. But there’s a lot more in today’s release than serendipitous semvertology. Today we are releasing database updates, better interop with the REST ecosystem, and one of the biggest updates to actions since the first release of the feature – let’s go!

MSSQL upsert and “undo” (aka transactions ;))

We’ve released two new functionalities to MSSQL auto-generated GraphQL API: upserts and transactions.

Upserts

Upserts allow users to create or update depending on if an item exists or not present in the API, saving extra round-trips to the server. Under the hood, we watch for if_matched filter inputs and then wrap up each insert by setting the identity_insert for the table. Ultimately creating a temporary table state of the affected rows and a temporary table of the values, merging them both into a final upsert statement.

Consider the two following queries:

mutation simple_insert {
  insert_user(objects: {age: 20, id: 1, name: "george"}) {
    affected_rows
    returning {
      id
      age
      name
    }
  }
}

Here, we simply run the insert as usual. But if we pass an `if_matched` input, we now have a proper upsert behavior.

mutation upsert {
  insert_user(objects: {age: 21, id: 1, name: "lucas"}, if_matched: {match_columns: id, update_columns: age}) {
    affected_rows
    returning {
      id
      age
      name
    }
  }
}

You can read more about the design and implementation in the original RFC or check out the documentation here. Here's a video demo:

Transactional rollbacks based on state, AKA “undo”

Error handling in MSSQL can be tricky, and we were experiencing an issue where a cascading error would attempt to roll back the identical transaction, but the net effect was that the error of rolling back an already rolled-back transaction surfaced, not the actual cause of the original exception.

To solve this, we introduced the ability to query transaction state with the XACT_STATE() scalar function. This allows for monitoring transactional state without creating problematic duplication which increases error occurrences. More observability is always a good thing.

OpenAPI body specifications

A while back we introduced the ability to persist queries behind REST endpoints. This has allowed companies to improve reverse interoperability with existing infrastructure for cases where REST is required. To improve this interoperability, we’ve added OpenAPI documentation for body responses at the /api/swagger/json endpoint. Now, consuming restified GraphQL is even simpler than before.

Nested action types

Starting today, we’ve introduced nested types in action response handlers. Previously, an action could return deeply nested JSON structures, but the type definitions would need to be buried in either JSON, or JSONB. With this update, you can provide typings for actions and get instant GraphQL for your external rest endpoints as well. You can see just how impactful this is in the following video.