Skip to main content
Version: v3.x

Quickstart a Supergraph API

In less than a minute and without needing a data source connection string, you can have a supergraph API running locally and deployed on Hasura DDN. 🚀

Prerequisites

  1. Install the DDN CLI

    Simply run the installer script in your terminal:

    curl -L https://graphql-engine-cdn.hasura.io/ddn/cli/v4/get.sh | bash

  2. Install Docker (needed for local development)

    The Docker based workflow helps you iterate and develop locally without deploying any changes to Hasura DDN, making the development experience faster and your feedback loops shorter. You'll need Docker Compose v2.27.1 or later.

  3. Validate the installation

    You can verify that the DDN CLI is installed correctly by running:

    ddn doctor

Log in via the CLI

The ddn auth login command will authenticate your CLI session, giving you access to Hasura Cloud resources.

When you run this command, a browser window will open, allowing you to login to Hasura Cloud. After a successful login, you'll be redirected to your CLI session and can proceed with creating your supergraph.

ddn auth login

Initialize a new supergraph in a new directory

The ddn supergraph init command initializes a supergraph — which is a composite API — by setting up all necessary files and directories for development in the new mysupergraph directory.

When you execute this command, the CLI creates a Docker Compose file and a .env file to run the Hasura engine locally and other configuration files describing your supergraph. Additionally, the CLI creates two subgraphs, globals and app, to get you started with building your API. This setup allows you to start and manage your supergraph services locally with Docker.

ddn supergraph init mysupergraph
cd mysupergraph

Connect to data

The ddn connector init command adds a new native data connector to your supergraph project.

Data connectors allow you to connect to a specific type of data source (such as PostgreSQL, MongoDB, MySQL, ClickHouse, etc.).

Here we're naming our connector my_connector which is referenced in subsequent commands. As we are running this command with the interactive flag (-i), you'll be prompted to select a data connector type and enter any required environment variables, such as the connection details of your data source. The CLI will then generate the connector related files and also add a DataConnectorLink metadata object to link your connector to the supergraph.

Don't have a data source at hand?

If you choose our hasura/postgres connector, it ships with a docker compose that runs a local PostgreSQL database. You can check this guide for more details. Or you can connect to our sample PostgreSQL database using this URL: postgresql://read_only_user:[email protected]:5432/v3-docs-sample-app

ddn connector init my_connector -i

Introspect your data source

The ddn connector introspect command will introspect your data source.

This creates a set of configuration files describing your data source in a format which the connector specifies. It also updates the corresponding DataConnectorLink with the resources from the data source that can be exposed via the API. This will then be used in the next step to generate metadata for each resource found during introspection.

Is introspect not working? Confirm that the environment variables defined in the .env file are correct.

ddn connector introspect my_connector

Add your resources

This will create metadata for models, commands, and relationships in your supergraph. Metadata configures your GraphQL API and exposes entities in your data sources — such as tables.

ddn model add my_connector '*'
ddn command add my_connector '*'
ddn relationship add my_connector '*'

Build your supergraph for the local engine

The ddn supergraph build local command will build your supergraph and create local assets to run the engine.

This allows you to create an immutable build of your API which you can run locally and test before pushing your changes to version control or creating and deploying a cloud build, either on Hasura DDN or on your own self-hosted infrastructure.

ddn supergraph build local

Start your supergraph

Open a separate terminal, navigate to your project directory and run ddn run docker-start. This command will execute the script found in your .hasura/context.yaml file.

When you run this command, Docker will start services for your supergraph, each connector you've added, and observability tools.

You can explore, visualize, and test your supergraph using the Hasura DDN console. In the previous terminal, simply run ddn console --local or head to https://console.hasura.io/local/graphql and try it out!

Congratulations! At this point, you've created your very first, fully-functioning supergraph 🎉

Next, lets deploy your supergraph to Hasura DDN. Note that your data source will need to be accessible from the internet to be able to connect to it from Hasura DDN.

ddn run docker-start

Create a Hasura DDN project

The ddn project init command will provision a new project on Hasura DDN to deploy your supergraph.

The CLI will also create a .env.cloud file based on your .env file that contains any environment variables necessary to run your supergraph, such as the connection string to a data source. It will also set the project's name in your local context so you can run simplified commands. Finally, the CLI will generate your globals and app subgraphs on your Hasura DDN project.

ddn project init

Build and deploy your supergraph

Running ddn supergraph build create will build your data connector and the supergraph, making your API available on Hasura DDN.

This command builds each data connector associated with the project, updates any environment variables to match the connectors' URLs, and creates a new immutable build of your supergraph. You can explore this build on the DDN console. And, when ready, you can apply the build so it's served by your project's API endpoint.

That's it! you've created your very first, fully-functioning supergraph and deployed it to Hasura DDN 🎉

ddn supergraph build create

Next steps

What we've laid out above is the quickest way to get started with Hasura DDN. However, you have complete, granular control over each step in the process and can extend and customize your supergraph to fit your teams' needs. After deploying your first supergraph, take your next steps with Hasura DDN 👇

Connect your own data source

If you didn't connect your own data source in the guide above, give it a shot!

Hasura will never affect the schema, and you maintain full control over your data. Hasura maps your existing schema to a powerful, flexible API without altering any underlying structures.

Add a collaborator

Hasura DDN makes it easy to collaborate and iteratively build an API with other contributors. You can select from a variety of roles ensuring your teammates have the appropriate access level while maintaining control for those who need it. Add you first collaborator!