Hasura v3 (DDN) – Getting Started, and Upgrading from v2

Hasura v3 is called DDN — Data Delivery Network — and the most useful thing to understand before touching it is that it is not v2 with new commands. It is a different product that happens to share a name and a query language. This lesson covers what it is, how to get one running, and exactly what changes coming from v2.

How this lesson was written. Everything below is taken from the official Hasura DDN documentation as read on 2026-08-21 — the feature availability matrix, the glossary and the quickstart. Unlike the v2 lessons in this track, it was not run locally, so it shows configuration and commands but never claims output.

The v3 mental model

Three words carry most of it.

A connector is what talks to a data source. In v2 the engine had built-in support for a fixed list of databases; in v3 every source — Postgres, a REST service, another GraphQL API, your own TypeScript functions — is reached through a native data connector implementing a common specification. Adding a new kind of source means writing or installing a connector rather than waiting for a Hasura release.

A subgraph is a self-contained slice of the API: its metadata, its connectors, its permissions, its own repository and release cycle. It is the unit of team ownership.

A supergraph is the composition of those subgraphs into one API. This is the architectural point of v3 — several teams shipping independently into a single graph, without the central bottleneck a single v2 engine becomes.

The other shift is builds. A v2 change is applied to a running engine and takes effect. A v3 change is compiled into an immutable build with its own unique endpoint, which you can test before promoting. Metadata stops being a live thing you mutate and becomes source you compile.

Getting a v3 project running

Install the CLI. Docker Compose v2.20 or later is required.

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

Scaffold a supergraph, attach a connector, and let it introspect the database:

ddn supergraph init mysupergraph
ddn connector init my_connector -i
ddn connector introspect my_connector

Introspection writes what it found into the connector’s configuration; nothing is exposed in the API yet. In v2 you would now “track” tables in the console. In v3 you add models, and the equivalent of tracking everything is a wildcard:

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

Then build and run it locally:

ddn supergraph build local
ddn run docker-start
ddn console --local

What you get is a project directory, not a running engine holding state:

supergraph.yaml
globals/                       # AuthConfig, CompatibilityConfig, GraphqlConfig
app/
  metadata/*.hml               # your models, types, relationships, permissions
  connector/my_connector/configuration.json
engine/build/                  # immutable build output

Those .hml files are the product. HML is Hasura Metadata Language, an extension of YAML, and it is what you edit and commit. A model looks like this:

kind: Model
version: v1
definition:
  name: Properties
  objectType: Properties
  source:
    dataConnectorName: my_connector
    collection: properties
  graphql:
    selectUniques: []
    selectMany:
      queryRootField: properties

The console still exists but its job has changed: in v3 it is for testing queries, reading traces and analytics, and managing collaboration — not for authoring. Authoring is the CLI, the files, and a VS Code extension that validates them as you type.

v2 to v3, item by item

This is the table to keep open while you are working. Every row is from Hasura’s own documentation on 2026-08-21. Rows marked with a stripe are ones where v3 currently does less than v2.

Legend. (C) connector-dependent · WIP work in progress · * supported but implemented differently · EE Enterprise or Cloud only.

What an existing v2 project has to become

Read down that table and the migration sorts into three piles.

Things that carry over as ideas but not as syntax. Roles, session variables, row-level filters and column allowlists all still exist — they are just declared differently. A v2 select permission becomes ModelPermissions for the rows plus TypePermissions for the fields, split by what is being protected rather than by which operation you were doing. Relationships become a Relationship object and gain the ability to cross connectors, which v2 relationships could not do.

Things that change shape entirely. Actions become Commands backed by a lambda connector, so instead of hosting a webhook and describing its types to Hasura, you write a function in TypeScript, Python or Go inside the project. Remote schemas become the GraphQL connector. And filtering stops being generated for every column: you declare a BooleanExpressionType saying what is filterable.

Things that simply do not come with you. These are the ones worth deciding on before you start, not after.

The admin secret is gone

There is no HASURA_GRAPHQL_ADMIN_SECRET in DDN and no built-in unrestricted role behind it. Every v2 habit built on that secret — seeding scripts, console access, migration tooling, the “just use admin for now” shortcut in a test suite — needs another answer. API access uses a Cloud PAT sent as a cloud_pat header.

This is the single most disruptive row in the table and it is easy to miss, because nothing about it is announced loudly. If your deployment scripts authenticate with an admin secret today, they do not have a direct translation.

Cron triggers do not exist

Scheduled and cron triggers have no v3 replacement. If you run reconciliation jobs, digest emails or nightly cleanups off Hasura’s scheduler, that work moves to your own scheduler before you migrate.

Event triggers are unfinished

Event triggers are marked work in progress. Plan for them to live outside Hasura — a listener on the database’s own change stream, or writes going through a service that emits its own events. Do not architect a v3 migration assuming they will land in time.

Database migrations are no longer Hasura’s job

hasura migrate has no successor. Schema migrations belong to your own tool — Alembic, Flyway, whatever you already use — and you tell Hasura about the result by re-introspecting the connector. For teams who leaned on the v2 CLI to version schema and metadata together, this is a real workflow change and not a small one.

So should you migrate?

If you are starting fresh, are federating across several data sources or teams, and none of the gaps above are load-bearing for you, v3 is the direction the product is going and the supergraph model is genuinely better at that job.

If you have a working v2 installation whose value is a well-tuned permission model over one Postgres database, and you use cron or event triggers, then the honest answer is that migrating buys you architecture you may not need and costs you features you currently have. v2 is not going anywhere yet. Read the table, find your own load-bearing rows, and decide from those rather than from the version number.