Dispatch over backends.

Creating and consuming AnyBackend

Creating a new value of type AnyBackend is done via mkAnyBackend.

Consuming a value of type AnyBackend is done via either runAnyBackend or any of the dispatch functions (dispatchAnyBackend, dispatchAnyBackend', dispatchAnyBackend'').

For implementation details, or when trying to understand this module, start from AnyBackend.

Backend Architecture

Our multiple backend architecture uses type classes and associated types in order to share code, such as parsing graphql queries, building schemas and metadata, while still accounting for the differences between backends.

Each backend implements the Backend type class from Hasura.RQL.Types.Backend as well as instances for other classes such as BackendSchema from Hasura.GraphQL.Schema.Backend, and define the associated types and functions, such as ScalarType and parseScalarValue, which fit the backend.

Whenever one of these associated types (ScalarType, Column, etc.) are used, we need to either push the BackendType to our caller (and making our type BackendType -> Type), or use AnyBackend (and allow our type to be Type). This is particularly useful when we need to store a container of any backend.

In order to actually program abstractly using type classes, we need the type class instances to be available for us to use. This module is a trick to enumerate all supported backends and their respective instances to convince GHC that they can be used.

Example usage

As an example of using this module, consider wanting to write a function that calculates metrics for each source. For example, we want to count the number of tables each source has.

The SchemaCache (defined in Hasura.RQL.Types.SchemaCache) holds a hash map from each source to their information. The source information is parameterized by the BackendType and is hidden using an existential type inside AnyBackend. It essentially looks like this:

data SourceInfo b = ...

type SourceCache = HashMap SourceName (AnyBackend SourceInfo)

Our metrics calculation function cares which backend it receives, but only for its type class instances so it can call the relevant functions:

telemetryForSource :: forall (b :: BackendType). SourceInfo b -> TelemetryPayload

In order to apply this function to all backends and return the telemetry payload for each, we need to map over the hash map and dispatch the function over the relevant backend. we can do this with runBackend:

telemetries =
  map
    (`runBackend` telemetryForSource)
    (scSources schemaCache)

If we want to be able to extract some information about the backend type inside telemetryForSource, we can do this using backendTag:

let telemetryForSource :: forall (b :: BackendType). HasTag b => SourceInfo b -> TelemetryPayload
    telemetryForSource =
      let dbKind = reify (backendTag @b)

Note that we needed to add the HasTag constraint, which now means we can't use runBackend because our function has the wrong type (it has an extra constraint). Instead, we can use dispatchAnyBackend which allows us to have one constraint:

telemetries =
  fmap
    (\sourceinfo -> (Any.dispatchAnyBackend @HasTag) sourceinfo telemetryForSource)
    (scSources schemaCache)

Note that we had to add the constraint name as a type application, and we had to explicitly add a lambda instead of using flip.