Hasura - v2.0.0

We are glad to announce the stable release of Hasura GraphQL Engine v2.0.0.

Please check the upgrade guide before upgrading. There are few breaking changes in special scenarios which are described in Breaking changes section below.

IMPORTANT UPGRADE NOTE: Due to a startup issue observed on upgrading to v2.0.0 we've removed the v2.0.0 docker image. We have found the cause and the fix has been made in v2.0.1.

Hasura 2.0 highlights

Multiple databases support and metadata storage separation

Simultaneously add multiple Postgres databases:

You can also store Hasura metadata in a separate (Postgres) database given by the environment variable

Generalized backend: Support for MS SQL server and BigQuery

The server has been generalized to support different databases. We start off by providing read-only support for MS SQL server and BigQuery.

MS SQL server





Support for creating idiomatic REST API endpoints from GraphQL query templates so that users can support non-GraphQL clients easily and integrate with their existing REST tooling.

Remote Schema Permissions

The permission system has been extended for Remote Schemas. You can do type/field masking and preset arguments (with session variables) over remote schemas.

Volatile functions as mutations/queries

You can now track VOLATILE Postgres functions as mutations (or even queries).

Inherited Roles

You can now create an Inherited Role which allows you to combine multiple roles into one role (in an additive way). This solves fundamental problems with permission system (as described in #877 and #3442) and also helps you manage roles in a modular way.

To get started, head to Hasura Console, Settings -> Inherited Roles (read docs here)

In the first version, only Postgres queries and subscriptions are exposed for an inherited role.

PS: Inherited roles is currently an experimental feature. To enable inherited roles, start the Hasura server with environment variable HASURA_GRAPHQL_EXPERIMENTAL_FEATURES: "inherited_roles"

Support comparing columns across related tables in permission's boolean expressions

We now support comparing columns across related tables (fixing #3459) . For example:

Consider two tables, items(id, name, stock) and shopping_cart(id, item_id, quantity)
and these two tables are related via the item_id column. Now, while defining insert permission
on the shopping_cart table, there can be a check to insert an item into the shopping cart
only when there is enough stock present in the items table.

ltree comparison operators

Comparison operators on columns with ltree, lquery or ltxtquery types are now supported, for searching through data stored in a hierarchical tree-like structure.

See the documentation at graphql/core/queries/query-filters more details on the currently supported ltree operators.

Support geometry and geography spatial data comparison operators in MS SQL Server

Comparison operators on spatial data types, geometry and geography, are now supported in MS SQL Server. The following operators are supported:

  • STEquals
  • STIntersects
  • STTouches
  • STOverlaps
  • STCrosses
  • STWithin
  • STContains

Support for 3D PostGIS Operators

We now support the use of the functions ST_3DDWithin and ST_3DIntersects in boolean expressions.
Note that ST_3DIntersects requires PostGIS be built with SFCGAL support which may depend on the PostGIS distribution used.

Other fixes and improvements:

  • server: add allow_inconsistent_metadata option to replace_metadata API to allow adding objects which are inconsistent
  • server: add "resource_version" field to metadata for concurrency control - disable lookup during migrations
  • server: add request field to webhook POST body containing the GraphQL query/mutation, its name, and any variables passed (close #2666)
  • server: add --websocket-compression command-line flag for enabling websocket compression (fix #3292)
  • server: some mutations that cannot be performed will no longer be in the schema (for instance, delete_by_pk mutations won't be shown to users that do not have select permissions on all primary keys) (#4111)
  • server: treat the absence of backend_only configuration and backend_only: false equally (closing #5059) (#4111)
  • server: accept only non-negative integers for batch size and refetch interval (close #5653) (#5759)
  • server: Configurable websocket keep-alive interval. Add --websocket-keepalive command-line flag and HASURA_GRAPHQL_WEBSOCKET_KEEPALIVE env variable (fix #3539)
  • server: introduce optional custom table name in table configuration to track the table according to the custom name. The set_table_custom_fields API has been deprecated, A new API set_table_customization has been added to set the configuration. (#3811)
  • server: support joining Int or String scalar types to ID scalar type in remote relationship
  • server: add support for regex operators (close #4317) (#6172)
  • server: do not block catalog migration on inconsistent metadata
  • server: various changes to ensure timely cleanup of background threads and other resources in the event of a SIGTERM signal.
  • server: fix issue with event triggers defined on a table which is partitioned (fixes #6261)
  • server: action array relationships now support the same input arguments (such as where or distinct_on) as usual relationships
  • server: action array relationships now support aggregate relationships
  • server: fix issue with non-optional fields of the remote schema being added as optional in the graphql-engine (fix #6401)
  • server: accept new config allowed_skew in JWT config to provide leeway for JWT expiry (fixes #2109)
  • server: always log the request_id at the detail.request_id path for both query-log and http-log (#6244)
  • server: fix issue with --stringify-numeric-types not stringifying aggregate fields (fix #5704)
  • server: terminate a request if time to acquire connection from pool exceeds configurable timeout (#6326)
  • server: support tracking of functions that return a single row (fix #4299)
  • server/mssql: supports connection pooling to sql server
  • server: improve errors messages for inconsistent sources
  • server: better handling for one-to-one relationships via both manual_configuration and foreign_key_constraint_on (#2576)
  • server/mssql: support tracking and querying from views
  • server: fix issue when a remote relationship's joining field had a custom GraphQL name defined (fix #6626)
  • server: fix handling of nullable object relationships (fix #6633)
  • server/mssql: mssql_add_source can now take connection strings from environment variables
  • server: support IN, NIN, LIKE and NLIKE operators in MS SQL Server
  • server: remove the restriction of supporting only base type function arguments. The type of an argument with a table type is now <tablename>_scalar to avoid conflicts with the object type <tablename>.
  • server: add --async-actions-fetch-interval command-line flag and HASURA_GRAPHQL_ASYNC_ACTIONS_FETCH_INTERVAL environment variable for configuring async actions re-fetch interval from metadata storage (fix #6460)
  • server: add 'replace_configuration' option (default: false) in the add source API payload
  • server: add a comment field for actions
  • server: accept GeoJSON for MSSQL geometry and geography operators
  • server: update pg_dump clean output to disable function body validation in create function statements to avoid errors due to forward references
  • server: add a new /dev/rts_stats endpoint, enabled when hasura is started with '+RTS -T'
  • server: support for bigquery datasets
  • server: format the values of injectEventContext as hexadecimal string instead of integer (fix #6465)
  • server: add "kind" field to query-log items. Kind can be "database", "action", "remote-schema", "graphql", "cached", or "subscription"
  • server: support query multiplexing in MSSQL subscriptions
  • server: aggregation fields are now supported on mssql
  • server: accept a new env conf HASURA_GRAPHQL_EVENTS_FETCH_BATCH_SIZE to configure the number of rows being fetched from the events log table in a single batch
  • server: restore proper batching behavior in event trigger processing so that at most 2x batch events are checked out at a time
  • server: decrease polling interval for scheduled triggers from 60 to 10 seconds
  • server: Change HASURA_GRAPHQL_SCHEMA_POLL_INTERVAL env var to HASURA_GRAPHQL_SCHEMA_SYNC_POLL_INTERVAL and schema-poll-interval option to --schema-sync-poll-interval
  • server: log warning for deprecated environment variables.
  • server: initialise hdb_catalog tables only when required, and only run the event loop for sources where it is required
  • server: add rename_source metadata API (fix #6681)
  • server: MSSQL: Support ORDER BY for text/ntext types.
  • server: MSSQL: Support _lt, _eq, etc. for text/ntext types.
  • server: MSSQL: Fix offset when there's no order by.
  • server: MSSQL: Support booleans better.
  • server: Include permission filter in the exists clause (fix #6931)
  • server: add support for adding multi-column foreign key relationships
  • server: properly reject queries containing unknown or misplaced directives
  • server: fix bigint overflow, incorrect geojson format in event trigger payload (fix #3697) (fix #2368)
  • server: fix introspection output not being consistently ordered
  • server: forward the x-request-id header when generated by graphql-engine (instead of being user-provided) (fix #6654)
  • server: introduce --graceful-shutdown-timeout server config which will wait for the in-flight scheduled and event trigger events and async actions to complete before shutting down
  • server: sanitise event trigger and scheduled trigger logs to omit possibly sensitive request body and headers
  • server: fix parsing of values for Postgres char columns (fix #6814)
  • server: fix query execution of custom function containing a composite argument type
  • server: fix a bug in query validation that would cause some queries using default variable values to be rejected (fix #6867)
  • server: REST endpoint bugfix for UUID url params
  • server: custom URI schemes are now supported in CORS config (fix #5818) (#5940)
  • server: explaining/analyzing a query now works for mssql sources
  • server: fix bug preventing tables with the same name in different sources
  • server: include more detail in inconsistent metadata error messages (fix #6684)
  • server: fix asymptotic performance of fetching from the event_log table
  • server: remote relationships (database to remote schema joins) are now supported on SQL Server and BigQuery (console pending)
  • server: BigQuery: switches to a single query generation from a dataloader approach. This should result in
    faster query responses.
  • server: BigQuery: various bug fixes related to aggregations
  • server: fix add source API wiping out source's metadata when replace_configuration is true
  • console: allow user to cascade Postgres dependencies when dropping Postgres objects (close #5109) (#5248)
  • console: mark inconsistent remote schemas in the UI (close #5093) (#5181)
  • console: add onboarding helper for new users
  • console: add option to flag an insertion as a migration from Data section (close #1766) (#4933)
  • console: down migrations improvements (close #3503, #4988) (#4790)
  • console: show only compatible postgres functions in computed fields section (close #5155) (#5978)
  • console: add session argument field for computed fields (close #5154) (#5610)
  • console: add tree view for Data Tab UI
  • console: add inherited roles support
  • console: add relationship tab for mssql tables
  • console: add permissions support for mssql tables
  • console: add browse rows for mssql tables
  • console: allow editing rest endpoints queries and misc ui improvements
  • console: display collection names and queries from all collections in allowlist
  • console: add a comment field for actions
  • console: data sidebar bug fixes and improvements
  • console: add custom_column_names to track_table request with replaced invalid characters
  • console: add details button to the success notification to see inserted row
  • console: add request preview for REST endpoints
  • console: add bigquery support
  • console: fix Postgres table creation when table has a non-lowercase name and a comment (#6760)
  • console: add union types to remote schema permissions
  • console: read-only modify page for mssql
  • console: filter out partitions from track table list and display partition info
  • console: fixes an issue where no schemas are listed on an MSSQL source
  • console: allow editing sources configuration
  • console: show db version and source details in manage db page
  • console: add one-to-one relationships support
  • console: rearrange connect database form and add prepared statements
  • console: add pool_timeout, connection_lifetime and isolation_level connection params to connect database form
  • console: add check constraints and comments to MS SQL Server tables' read-only modify page
  • console: add create table functionality for MS SQL Server
  • console: add drop table functionality to MS SQL Server tables
  • console: allow renaming data sources
  • console: show error notification for table and cloumn names exceeding 63 characters and trim migration names exceeding 255 characters
  • console: add foreign key CRUD functionality to ms sql server tables
  • console: allow tracking of custom SQL functions having composite type (rowtype) input arguments
  • console: allow input object presets in remote schema permissions
  • console: add modify functionality on columns, primary keys & unique keys to MS SQL Server tables
  • cli: add missing global flags for seed command (#5565)
  • cli: allow seeds as alias for seed command (#5693)
  • cli: support rest endpoints
  • cli: support mssql sources
  • cli: use relative paths in metadata !include directives
  • cli: rename --database flag in migrate and seed command to --database-name
  • cli: support inherited roles
  • cli: cli-ext is now a native part of cli binary (no longer needed as a plugin)
  • cli: fix issue with adding operation to allow list in console mode (fix #6617)
  • cli: match ordering of keys in project metadata files with server metadata
  • cli: add --all-databases flag for migrate apply, this allows applying migrations on all connected databases in one go
  • cli: add support for bigquery in metadata operations
  • cli: fix regression - metadata apply โ€”dry-run was overwriting local metadata files with metadata on server when it should just display the differences
  • cli: add -o/--output flag for hasura metadata apply & export subcommands
  • cli: add support for graphql_schema_introspection metadata object
  • cli: fix applying migrations in a different environment after config v3 update (#6861)
  • cli: fix bug caused by usage of space character in database name (#6852)
  • cli: fix issues with generated filepaths in windows (#6813)
  • cli: add warning for incompatible pro plugin version
  • cli: add new sub command delete to hasura migrate
  • cli: fix bug in migrate squash due to empty down file (#3897)
  • cli: fix bug with metadata apply on some CI environments (#6987)
  • cli: add interactive prompt to get input when --database-name flag is missing
  • cli: fix metadata export to avoid unnecessary empty lines in actions.graphql (#5338)
  • cli: generate migrations for mssql databases in hasura console mode (#7011)
  • cli-migrations: add config v3 image
  • docs: add Hasura v2 upgrade guide
  • build: add test_server_pg_13 to the CI to run the server tests on Postgres v13 (#6070)

Breaking changes

  • Semantics of explicit "null" values in "where" filters have changed

According to the discussion in issue 704, an explicit null value in a comparison input object will be treated as an error rather than resulting in the expression being evaluated to True.

For example: The mutation delete_users(where: {id: {_eq: $userId}}) { name } will yield an error if $userId is null instead of deleting all users.

The old behaviour can be enabled by setting the environment variable: HASURA_GRAPHQL_V1_BOOLEAN_NULL_COLLAPSE: true.

  • Semantics of "null" join values in remote schema relationships have changed

In a remote schema relationship query, the remote schema will be queried when all of the joining arguments are not null values. When there are null value(s), the remote schema won't be queried and the response of the remote relationship field will be null. Earlier, the remote schema was queried with the null value arguments and the response depended upon how the remote schema handled the null arguments but as per user feedback, this behaviour was clearly not expected.

  • Order of keys in objects passed as "order_by" operator inputs is not preserved

The order_by operator accepts an array of objects as input to allow ordering by multiple fields in a given order, i.e. [{field1: sortOrder}, {field2: sortOrder}] but it is also accepts a single object with multiple keys as an input, i.e. {field1: sortOrder, field2: sortOrder}. In earlier versions, Hasura's query parsing logic used to maintain the order of keys in the input object and hence the appropriate order by clauses with the fields in the right order were generated .

As the GraphQL spec mentions that input object keys are unordered, Hasura v2.0's new and stricter query parsing logic doesn't maintain the order of keys in the input object taking away the guarantee of the generated order by clauses to have the fields in the given order.

For example: The query fetch_users(order_by: {age: desc, name: asc}) {id name age} which is intended to fetch users ordered by their age and then by their name is now not guaranteed to return results first ordered by age and then by their name as the order_by input is passed as an object. To achieve the expected behaviour, the following query fetch_users(order_by: [{age: desc}, {name: asc}]) {id name age} should be used which uses an array to define the order of fields to generate the appropriate order by clause.

  • Type name for computed fieldsโ€™ input argument has change

The name of the computed field argument has changed from <function_name>_args to
<computed_field_name>_<table_name>_args as the function name is internal detail for a computed field.
This change also enables adding a root-level tracked function as a computed field which previously would have thrown input type conflict error.

  • Hasura APIs generated by older Hasura versions cannot be added as Remote Schemas to Hasura v2

With v2.0, some of the auto-generated schema types have been extended. For example, String_comparison_exp has an additional regex input object field. This means if you have a Hasura API with an older Hasura version added as a remote schema then it will have a type conflict. You should upgrade all Hasura remote schemas to avoid such type conflicts.

  • Migrations are not executed under a single transaction

While applying multiple migrations, in earlier Hasura CLI versions all migration files were run under one transaction block. i.e. if any migration threw an error, all the previously successfully executed migrations would be rolled back. With Hasura CLI v2.0, each migration file is run in its own transaction block but all the migrations are not executed under one. i.e. if any migration throws an error, applying further migrations will be stopped but the other successfully executed migrations up till that point will not be rolled back.

  • Deprecation of database specific env vars

In v2.0, the values of the following env vars are used to define the connection parameters of the default database while updating an existing instance or while starting a fresh instance. During metadata initialization, their values are moved to the metadata of the default database as defined here.


Post the initial setup/update once the metadata is initialized, these env vars can be considered as deprecated. i.e. changing or setting values of these env vars will have no impact as the values in the Hasura metadata are now used to define the connection parameters.

Using this release

Use the following docker image:



June 23, 2021, 12:15 p.m.
Register or login to:
  • ๐Ÿ”View and search all Hasura releases.
  • ๐Ÿ› ๏ธCreate and share lists to track your tools.
  • ๐ŸšจSetup notifications for major, security, feature or patch updates.
  • ๐Ÿš€Much more coming soon!
Continue with GitHub
Continue with Google