Version: v3.x

Quickstart with DDN

This guide will help you create a new cloud-deployed Hasura DDN supergraph in only a couple of minutes.

Prerequisites

Install the DDN CLI

You can download the CLI binary below. Please follow the instructions for your system.
- macOS and Linux
- Windows
Simply run the installer script in your terminal:
curl -L https://graphql-engine-cdn.hasura.io/ddn/cli/v4/get.sh | bash
Download the latest cli-ddn-windows-amd64.exe binary and run it.
curl -L https://graphql-engine-cdn.hasura.io/ddn/cli/v4/latest/cli-ddn-windows-amd64.exe -o ddn.exe
In Windows, if you get an "Unrecognized application" warning, click "Run anyway".
Additionally, you'll need to add this executable to your system's PATH:
Step 1: Locate the and rename the executable: Find the full path to the directory containing the executable. For example, if the executable is located in C:\Program Files\cli-ddn-windows-amd64.exe, note this path. Also, rename it to ddn for ease when writing commands later on.
Step 2: Open System Properties:
- Press Win + X and select System.
- Click on Advanced system settings on the left side.
- In the System Properties window, click on the Environment Variables button.
Step 3: Edit the PATH Variable:
- In the Environment Variables window, find the System variables section.
- Scroll down and select the Path variable, then click Edit.
- In the Edit Environment Variable window, click New and paste the path to the directory containing your executable (e.g., C:\Program Files\ddn.exe).
Step 4: Save Your Changes:
- Click OK to close the Edit Environment Variable window.
- Click OK to close the Environment Variables window.
- Click OK to close the System Properties window.
Step 5: Verify the Changes: Open a new Command Prompt or PowerShell window and type the following.
```
ddn
```
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.

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 an empty directory

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

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.

mkdir hasura_project && cd hasura_project
ddn supergraph init .

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 also add a DataConnectorLink metadata object to link your connector to the supergraph.

Don't have a data source at hand?

You can choose our hasura/postgres connector which by default connects to our sample Postgres database for you to explore. Or check this guide to set up a local Postgres database using Docker.

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.

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 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

The ddn run docker-start 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. 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, check out these sections to see what your supergraph can do!

Integrate custom business logic

We've revolutionized how custom business logic is integrated into an API with our lambda connectors for TypeScript and Python. Gone are the days of writing separate microservices to handle business logic; with Hasura DDN, you can write your custom functions and expose them directly via your API! Plus, you get all the benefits of the supergraph, including the ability to add relationships and permissions for each function. Check it out here.

Add authorization

You can quickly and easily create access-control rules for any entity in your supergraph using permissions. Learn how to add ModelPermissions to control row-level access, and TypePermissions to control which columns are exposed to specific user roles. You can check both out in this guide.

Iterate on your API

In your day-to-day development cycle, you will be making changes to your data source's schema while developing new features. When this happens, you'll need to update your Hasura metadata to bring those changes into your API. Check out how to iterate on your API here.

Create relationships across sources

Arguably, the biggest benefit of a GraphQL API is your ability to create nested queries that allow you to return data from multiple tables and — with Hasura DDN — multiple sources. With Hasura DDN's metadata-driven approach, you can easily author relationships, using our VS Code extension, linking together disparate data sources for efficient, elegant queries to power your modern applications. Learn how here.

Add new subgraphs

Hasura DDN makes it easy to collaborate and iteratively build a federated API using individual subgraphs. Subgraphs can be owned by specific teams and their metadata can even live in separate repositories, ensuring discrete ownership rules are honored. Learn how to add new subgraphs to your supergraph here.