Version: v3.x (DDN)

Get Started with Hasura DDN and Turso

Overview

This tutorial takes about twenty minutes to complete. You'll learn how to:

Set up a new Hasura DDN project
Connect it to a Turso-hosted database
Generate Hasura metadata
Create a build
Run your first query
Create relationships
Mutate data

Additionally, we'll familiarize you with the steps and workflows necessary to iterate on your API.

This tutorial assumes you're starting from scratch; you'll connect a hosted Turso instance to Hasura, but you can easily follow the steps if you already have data seeded. Hasura will never modify your source schema.

Prerequisites

Install the DDN CLI

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

ARM-based Linux Machines

Currently, the CLI does not support installation on ARM-based Linux systems.

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.20 or later.

Validate the installation

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

ddn doctor

Tutorial

Step 1. Authenticate your CLI

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

ddn auth login

This will launch a browser window prompting you to log in or sign up for Hasura DDN. After you log in, the CLI will acknowledge your login, giving you access to Hasura Cloud resources.

Step 2. Scaffold out a new local project

Next, create a new local project:
ddn supergraph init my-project && cd my-project

Once you move into this directory, you'll see your project scaffolded out for you. You can view the structure by either running ls in your terminal, or by opening the directory in your preferred editor.

Step 3. Create and seed a new Turso database

Step 3.1. Create a new database

Head to Turso and create an account if you don't already have one. Then, create a new group and database using their onboarding wizard.

After you finish creating the database, you'll be able to access it from your dashboard.

Step 3.2. Create an auth token

From the database, create an auth token and save it.

Step 3.3. Seed the database

Replacing the db-name, username, and auth token with your values, run the following command to create your first table and seed it with data:
curl -L -X POST 'https://<db-name>-<your-username>.turso.io/v2/pipeline' \
    -H 'Authorization: Bearer <auth-token>' \
    -H 'Content-Type: application/json' \
    -d '{
      "requests": [
        {
          "type": "execute",
          "stmt": {
            "sql": "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, age INTEGER NOT NULL)"
          }
        },
        {
          "type": "execute",
          "stmt": {
            "sql": "INSERT INTO users (name, age) VALUES (\"Alice\", 25)"
          }
        },
        {
          "type": "execute",
          "stmt": {
            "sql": "INSERT INTO users (name, age) VALUES (\"Bob\", 30)"
          }
        },
        {
          "type": "execute",
          "stmt": {
            "sql": "INSERT INTO users (name, age) VALUES (\"Charlie\", 35)"
          }
        },
        {
          "type": "close"
        }
      ]
    }'

You can then verify this by running the following:
curl -L -X POST 'https://<db-name>-<your-username>.turso.io/v2/pipeline' \
    -H 'Authorization: Bearer <auth-token>' \
    -H 'Content-Type: application/json' \
    -d '{
      "requests": [
        {
          "type": "execute",
          "stmt": {
            "sql": "SELECT * FROM users"
          }
        },
        {
          "type": "close"
        }
      ]
    }'

Step 4. Initialize your Turso connector

In your project directory, run:

ddn connector init my_turso -i

From the dropdown, select hasura/turso (you can type to filter the list), then hit enter to accept the default of all the options.

You'll be prompted for two environment variables:

Variable	Description	Example
`TURSO_URL`	The connection string for the Turso database, using `libsql` protocol. You can generate this from the database's overview in your Turso dashboard.	`libsql://dbname-username.turso.io`
`TURSO_AUTH_TOKEN`	The Turso auth token you genreated in the previous step.	`eyJ...`

Step 5. Introspect your Turso database

Next, use the CLI to introspect your Turso database:

ddn connector introspect my_turso

After running this, you should see a representation of your database's schema in the app/connector/my_turso/config.json file; you can view this using cat or open the file in your editor.

Additionally, you can check which resources are available — and their status — at any point using the CLI:

ddn connector show-resources my_turso

Step 6. Add your model

Now, track the table from your Turso database as a model in your DDN metadata:
ddn models add my_turso users

Open the app/metadata directory and you'll find a newly-generated file: Users.hml. The DDN CLI will use this Hasura Metadata Language file to represent the users table from Turso in your API as a model.

Step 7. Create a new build

To create a local build, run:

ddn supergraph build local

The build is stored as a set of JSON files in engine/build.

Step 8. Start your local services

Start your local Hasura DDN Engine and Turso connector:

ddn run docker-start

Your terminal will be taken over by logs for the different services.

Step 9. Run your first query

In a new terminal tab, open your local console:

ddn console --local

In the GraphiQL explorer of the console, write this query:
query {
  users {
    id
    name
    age
  }
}

You'll get the following response:
{
  "data": {
    "users": [
      {
        "id": 1,
        "name": "Alice",
        "age": 25
      },
      {
        "id": 2,
        "name": "Bob",
        "age": 30
      },
      {
        "id": 3,
        "name": "Charlie",
        "age": 35
      }
    ]
  }
}

Step 10. Iterate on your Turso schema

Add a new table and insert some data to your Turso database, taking care to update your values accordingly:
curl -L -X POST 'https://<db-name>-<your-username>.turso.io/v2/pipeline' \
    -H 'Authorization: Bearer <auth-token>' \
    -H 'Content-Type: application/json' \
    -d '{
      "requests": [
        {
          "type": "execute",
          "stmt": {
            "sql": "CREATE TABLE posts (id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER NOT NULL, title TEXT NOT NULL, content TEXT NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE)"
          }
        },
        {
          "type": "execute",
          "stmt": {
            "sql": "INSERT INTO posts (user_id, title, content) VALUES (1, \"My First Post\", \"This is Alice'\''s first post.\")"
          }
        },
        {
          "type": "execute",
          "stmt": {
            "sql": "INSERT INTO posts (user_id, title, content) VALUES (1, \"Another Post\", \"Alice writes again!\")"
          }
        },
        {
          "type": "execute",
          "stmt": {
            "sql": "INSERT INTO posts (user_id, title, content) VALUES (2, \"Bob'\''s Post\", \"Bob shares his thoughts.\")"
          }
        },
        {
          "type": "execute",
          "stmt": {
            "sql": "INSERT INTO posts (user_id, title, content) VALUES (3, \"Hello World\", \"Charlie joins the conversation.\")"
          }
        },
        {
          "type": "close"
        }
      ]
    }'

Verify this by running the following query:
curl -L -X POST 'https://<db-name>-<your-username>.turso.io/v2/pipeline' \
    -H 'Authorization: Bearer <auth-token>' \
    -H 'Content-Type: application/json' \
    -d '{
      "requests": [
        {
          "type": "execute",
          "stmt": {
            "sql": "SELECT posts.id AS post_id, posts.title, posts.content, posts.created_at, users.name AS author FROM posts JOIN users ON posts.user_id = users.id"
          }
        },
        {
          "type": "close"
        }
      ]
    }'

You should see a list of posts returned with the author's information joined from the users table

Step 11. Refresh your metadata and rebuild your project

tip

The following steps are necessary each time you make changes to your source schema. This includes, adding, modifying, or dropping tables.

Step 11.1. Re-introspect your data source

Run the introspection command again:

ddn connector introspect my_turso

In app/connector/my_turso/config.json, you'll see schema updated to include operations for the posts table. In app/metadata/my_turso.hml, you'll see posts present in the metadata as well.

Step 11.2. Update your metadata

Add the posts model:
ddn model add my_turso "posts"

Step 11.3. Create a new build

Next, create a new build:

ddn supergraph build local

Step 11.4. Restart your services

Bring down the services by pressing CTRL+C and start them back up:

ddn run docker-start

Step 12. Query your new build

Head back to your console and query the posts model:
query GetPosts {
  posts {
    id
    title
    content
  }
}

You'll get a response like this:
{
  "data": {
    "posts": [
      {
        "id": 1,
        "title": "My First Post",
        "content": "This is Alice's first post."
      },
      {
        "id": 2,
        "title": "Another Post",
        "content": "Alice writes again!"
      },
      {
        "id": 3,
        "title": "Bob's Post",
        "content": "Bob shares his thoughts."
      },
      {
        "id": 4,
        "title": "Hello World",
        "content": "Charlie joins the conversation."
      }
    ]
  }
}

Step 13. Create a relationship

Since there's already a foreign key on the posts table in Turso, we can easily add the relationship:
ddn relationship add my_turso "posts"

You'll see a new metadata object added to the app/metadata/posts.hml file of kind Relationship explaining the relationship between posts and users.

Step 14. Rebuild your project

As your metadata has changed, create a new build:

ddn supergraph build local

Bring down the services by pressing CTRL+C and start them back up:

ddn run docker-start

Step 15. Query using your relationship

Now, execute a nested query using your relationship:
query GetPosts {
  posts {
    id
    title
    content
    user {
      id
      name
      age
    }
  }
}

Which should return a result like this:
{
  "data": {
    "posts": [
      {
        "id": 1,
        "title": "My First Post",
        "content": "This is Alice's first post.",
        "user": {
          "id": 1,
          "name": "Alice",
          "age": 25
        }
      },
      {
        "id": 2,
        "title": "Another Post",
        "content": "Alice writes again!",
        "user": {
          "id": 1,
          "name": "Alice",
          "age": 25
        }
      },
      {
        "id": 3,
        "title": "Bob's Post",
        "content": "Bob shares his thoughts.",
        "user": {
          "id": 2,
          "name": "Bob",
          "age": 30
        }
      },
      {
        "id": 4,
        "title": "Hello World",
        "content": "Charlie joins the conversation.",
        "user": {
          "id": 3,
          "name": "Charlie",
          "age": 35
        }
      }
    ]
  }
}

Step 16. Add all commands

We'll track the available operations — for inserting, updating, and deleting — on our users and posts tables as commands.

Add all available commands:
ddn command add my_turso "*"

You'll see newly-generated metadata files in the metadata directory for your connector that represent insert, update, and delete operations.

As your metadata has changed, create a new build:

ddn supergraph build local

Bring down the services by pressing CTRL+C and start them back up:

ddn run docker-start

Step 17. Insert new data

Create a new post for Charlie:
mutation InsertSinglePost {
  insertPostsOne(
    object: {
      content: "I am an expert in Bird Law and I demand satisfaction."
      title: "Charlie has more to say"
      userId: 3
      id: 5
    }
  ) {
    id
    title
    content
  }
}

You should see a response that returns your inserted data.

Next steps

Congratulations on completing your first Hasura DDN project with Turso! 🎉

Here's what you just accomplished:

You started with a fresh project and connected it to a local Turso database.
You set up metadata to represent your tables and relationships, which acts as the blueprint for your API.
Then, you created a build — essentially compiling everything into a ready-to-use API — and successfully ran your first GraphQL queries to fetch data.
Along the way, you learned how to iterate on your schema and refresh your metadata to reflect changes.
Finally, we looked at how to enable mutations and insert data using your new API.

Now, you're equipped to connect and expose your data, empowering you to iterate and scale with confidence. Great work!

Take a look at our Turso docs to learn more about how to use Hasura DDN with Turso. Or, if you're ready, get started with adding permissions to control access to your API.

Get Started with Hasura DDN and Turso

Overview

Prerequisites

Tutorial

Step 1. Authenticate your CLI

Step 2. Scaffold out a new local project

Step 3. Create and seed a new Turso database

Step 3.1. Create a new database

Step 3.2. Create an auth token

Step 3.3. Seed the database

Step 4. Initialize your Turso connector

Step 5. Introspect your Turso database

Step 6. Add your model

Step 7. Create a new build

Step 8. Start your local services

Step 9. Run your first query

Step 10. Iterate on your Turso schema

Step 11. Refresh your metadata and rebuild your project

Step 11.1. Re-introspect your data source

Step 11.2. Update your metadata

Step 11.3. Create a new build

Step 11.4. Restart your services

Step 12. Query your new build

Step 13. Create a relationship

Step 14. Rebuild your project

Step 15. Query using your relationship

Step 16. Add all commands

Step 17. Insert new data

Next steps

Build an API in Less Than a Minute with Hasura DDN

Was this helpful?

Get Started with Hasura DDN and Turso

Overview​

Prerequisites​

Tutorial​

Step 1. Authenticate your CLI​

Step 2. Scaffold out a new local project​

Step 3. Create and seed a new Turso database​

Step 3.1. Create a new database​

Step 3.2. Create an auth token​

Step 3.3. Seed the database​

Step 4. Initialize your Turso connector​

Step 5. Introspect your Turso database​

Step 6. Add your model​

Step 7. Create a new build​

Step 8. Start your local services​

Step 9. Run your first query​

Step 10. Iterate on your Turso schema​

Step 11. Refresh your metadata and rebuild your project​

Step 11.1. Re-introspect your data source​

Step 11.2. Update your metadata​

Step 11.3. Create a new build​

Step 11.4. Restart your services​

Step 12. Query your new build​

Step 13. Create a relationship​

Step 14. Rebuild your project​

Step 15. Query using your relationship​

Step 16. Add all commands​

Step 17. Insert new data​

Next steps​

Build an API in Less Than a Minute with Hasura DDN

Was this helpful?

Overview

Prerequisites

Tutorial

Step 1. Authenticate your CLI

Step 2. Scaffold out a new local project

Step 3. Create and seed a new Turso database

Step 3.1. Create a new database

Step 3.2. Create an auth token

Step 3.3. Seed the database

Step 4. Initialize your Turso connector

Step 5. Introspect your Turso database

Step 6. Add your model

Step 7. Create a new build

Step 8. Start your local services

Step 9. Run your first query

Step 10. Iterate on your Turso schema

Step 11. Refresh your metadata and rebuild your project

Step 11.1. Re-introspect your data source

Step 11.2. Update your metadata

Step 11.3. Create a new build

Step 11.4. Restart your services

Step 12. Query your new build

Step 13. Create a relationship

Step 14. Rebuild your project

Step 15. Query using your relationship

Step 16. Add all commands

Step 17. Insert new data

Next steps