Hasura GraphQL Connector

The Hasura GraphQL Connector allows for connecting to a GraphQL API and bringing it into Hasura DDN supergraph as a single unified API. It can also be used to bring in your current Hasura v2 graphQL API into Hasura DDN and our recommended approach is to create a new subgraph for the v2 API.

For Hasura v2 users, this functionality is the replacement of remote schemas functionality in v3 (DDN).

This connector is built using the Rust Native Data Connector SDK and implements the Native Data Connector Spec.

The connector translates the root-fields of a GraphQL schema to NDC functions and procedures. This results in your GraphQL root-fields being exposed as commands in the Hasura supergraph. This simplifies implementation and acts as a proxy more than a model.

The recent support for field arguments and header forwarding on Hasura v3 engine allow the connector to represent the majority of queries and mutations.

flowchart LR
    User ---|GraphQLRequest| Engine
    Engine ---|NDCRequest| Connector
    Connector ---|GrqphQLRequest| UpstreamGQL
    Admin --- CLI
    CLI --- Plugin
    Plugin ---|Introspection| UpstreamGQL
    CLI -->|Configuration| Connector

Loading

The connector is configured in plugin mode, then run in execution mode.

Header forwarding is implemented as additional command arguments and wired from headers to the argument by the engine via the new ArgumentPresets feature.

• Connector information in the Hasura Hub
• Hasura V3 Documentation

Features

Below, you'll find a matrix of all supported features for the GraphQL connector:

Feature	Supported	Notes
Queries	✅	All features that v3 engine currently supports
Mutations	✅
Header Passthrough	✅	Entire headers can be forwarded
Request-level Arguments	✅	Support dynamic headers from the from Pre-NDC Request Plugin
Subscriptions	❌
Unions	✅	Lowered to tagged-variant object types (__typename, on_<Type>)
Interfaces	✅	Lowered to tagged-variant object types (__typename, on_<Type>)
Relay API	❌
Directives	❌	@cached, Apollo directives

Other Considerations and limitations

• Error formatting
  • The format of errors from the connector does not currently match V2 error formatting
  • No "partial error" or "multiple errors" responses
• Polymorphic output lowering
  • GraphQL interface and union outputs are lowered into synthetic object types in NDC metadata.
  • Lowered object types expose __typename plus one nullable tagged field per concrete type: on_<ConcreteType>.
  • When lowering is not possible (for example no concrete object members), config/schema validation fails with a targeted error.
• Pattern matching in request header forwarding configuration
  • This uses simple glob patterns
  • More advanced matching and extraction is not currently supported
• Response headers only allow at most one header per name
  • For example you may only use one Set-Cookie response header

Using the GraphQL Connector

This connector should be used with Hasura DDN. Please see the relevant documentation.

Advanced Features

Forward Headers from Pre-NDC Request Plugin

You can use a Pre-NDC Request Plugin to modify the request, and add dynamic headers in runtime via request_arguments.headers field, which is a string map. Those headers will be merged into the HTTP request headers before being sent to external services.

See the full example at Pre-NDC Request Plugin Request

{
  // ...
  "ndcRequest": {
    // ...
    "request_arguments": {
        "headers": {
            "Authorization": "Bearer <token>",
            "X-Custom-Header": "foo"
        }
    }
  }
}

TLS/SSL Configuration

The connector uses rustls for TLS which does not automatically pick up system certificate stores. For self-hosted deployments using organization-signed certificates, you can configure custom CA certificates or disable TLS verification via environment variables.

Variable	Description
GRAPHQL_CA_CERT_FILE	Path to a single PEM-encoded CA certificate file
GRAPHQL_CA_CERT_DIR	Directory containing PEM-encoded CA certificates (.pem, .crt, .cer)
GRAPHQL_INSECURE_SKIP_TLS_VERIFY	Set to true or 1 to disable TLS verification

Notes:

• GRAPHQL_CA_CERT_FILE and GRAPHQL_CA_CERT_DIR can be used together (certificates are combined)
• GRAPHQL_INSECURE_SKIP_TLS_VERIFY takes precedence and skips all CA cert logic when enabled
• Warning: Disabling TLS verification is insecure and should only be used for development/testing