Get Started with Hasura DDN and PostgreSQL

Prerequisites

Install the DDN CLI

macOS and Linux

Simply run the installer script in your terminal:

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

Windows

• Download the latest DDN CLI installer for Windows.
• Run the DDN_CLI_Setup.exe installer file and follow the instructions. This will only take a minute.
• By default, the DDN CLI is installed under C:\Users\{Username}\AppData\Local\Programs\DDN_CLI
• The DDN CLI is added to your %PATH% environment variable so that you can use the ddn command from your terminal.

Install Docker

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.

Validate the installation

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

ddn doctor

Guide

In this guide, you'll learn how to get started with Hasura DDN and a PostgreSQL database. You'll set up a new Hasura DDN project, connect it to a PostgreSQL database, and run your first query. This guide assumes you're starting from scratch, but you can easily follow the steps if you already have data seeded; Hasura will never modify your source schema.

Don't have your own PostgreSQL instance?

The hasura/postrgres data connector ships with a built-in PostgreSQL image for you to get up-and-running quickly. Skip ahead to Step 2 and — after initializing your connector in Step 4 — come back to create this table and seed data.

Step 1. Create a table in your PostgreSQL database

First, you'll create a new table in your PostgreSQL database:

--- Create the table
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  age INT NOT NULL
);

--- Insert some data
INSERT INTO users (name, age) VALUES ('Alice', 25);
INSERT INTO users (name, age) VALUES ('Bob', 30);
INSERT INTO users (name, age) VALUES ('Charlie', 35);

Connect to cloud local data sources

Hasura DDN can connect to hosted or local data sources. If you have a cloud-hosted PostgreSQL provider, you can connect to your database and seed the table with the above data. Alternatively, you can run PostgreSQL locally using Docker.

Step 2. Authenticate your CLI

Before you can create a new Hasura DDN project, you need to authenticate your CLI:

ddn auth login

Step 3. Scaffold out a new local project

Next, you'll create a new local project. Run the following command:

ddn supergraph init my-project && cd my-project

Step 4. Initialize your PostgreSQL connector

Initialize a new PostgreSQL connector. Run the following command:

ddn connector init my_pg -i

From the dropdown, start typing PostgreSQL and hit enter.

Set your environment variables:

Variable	Value	Required
CONNECTION_URI	The connection string to your source in this format: postgresql://username:password@hostname:port/dbname	Yes
CLIENT_CERT	Path to the client certificate file.	No
CLIENT_KEY	Path to the client key file.	No
ROOT_CERT	Path to the root certificate file.	No

Connecting a local database?

Hasura DDN uses a unique domain to resolve local services when using Docker. In the connection string above, you can replace hostname with local.hasura.dev if you're connecting to a local database running inside of a Docker container.

Step 5. Introspect your PostgreSQL database

Next, you'll introspect your PostgreSQL database:

ddn connector introspect my_pg

Step 6. Add your model

Now, you'll track the tables as models in your PostgreSQL database:

ddn models add my_pg users

Have multiple tables?

You can quickly grab them all using:

ddn models add my_pg "*"

Step 7. Create a new build

Next, you'll create a new build:

ddn supergraph build local

Step 8. Start your local services

Start your local Hasura DDN Engine and PostgreSQL connector:

ddn run docker-start

Step 9. Run your first query

Open your local console:

ddn console --local

And, if you write a query like this:

query {
  users {
    id
    name
    age
  }
}

You'll get a response like this:

{
  "data": {
    "users": [
      {
        "id": 1,
        "name": "Alice",
        "age": 25
      },
      {
        "id": 2,
        "name": "Bob",
        "age": 30
      },
      {
        "id": 3,
        "name": "Charlie",
        "age": 35
      }
    ]
  }
}

Next steps

Congratulations! You've successfully set up a Hasura DDN project and connected it to a PostgreSQL database. Next, you can explore more advanced features like relationships, permissions, and more.

Take a look at our PostgreSQL docs to learn more about how to use Hasura DDN with PostgreSQL.