hasura/graphql-engine v2.0.0 on GitHub

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
HASURA_GRAPHQL_METADATA_DATABASE_URL

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

BigQuery

REST APIs

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.
HASURA_GRAPHQL_PG_CONNECTIONS
HASURA_GRAPHQL_PG_TIMEOUT
HASURA_GRAPHQL_NO_OF_RETRIES
HASURA_GRAPHQL_PG_CONN_LIFETIME
HASURA_GRAPHQL_PG_POOL_TIMEOUT
HASURA_GRAPHQL_USE_PREPARED_STATEMENTS
HASURA_GRAPHQL_TX_ISOLATION
HASURA_GRAPHQL_READ_REPLICA_URLS
HASURA_GRAPHQL_CONNECTIONS_PER_READ_REPLICA
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:

hasura/graphql-engine:v2.0.0