Quickstart with Docker

Introduction

This guide will help you get up and running quickly with the Hasura GraphQL Engine and a Postgres database running as Docker containers using Docker Compose.

Prerequisites

• You have Docker and Docker Compose version 2.0 or higher working on your machine.

Step 1: Get the Compose file & start the containers

Get the Compose file from our repo. If you're using curl, run this command in a new directory:

curl https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/docker-compose/docker-compose.yaml -o docker-compose.yml

If you're using wget, run this command in a new directory:

wget https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/docker-compose/docker-compose.yaml

Then, run the following command to start both the Hasura GraphQL Engine and the Postgres database in Docker containers:

docker compose up -d

Step 2: Connect a database

Hasura ships with a Postgres database

The docker-compose file we used in the previous step starts a Postgres database in a Docker container. Hasura relies on this database to store its metadata, but this can also be used to store your application data.

If you'd like to connect another type of database for storing application data, check out our list of supported databases.

Open the Hasura Console by navigating to http://localhost:8080/console. From the Console, click the Data tab:

Select the Environment Variable option and enter PG_DATABASE_URL as the environment variable name:

Click Connect Database.

Step 3: Try out Hasura

Create a table and insert some demo data

On the Hasura Console, navigate to Data -> Create table and create a sample table called profiles with the following columns:

profiles (
  id SERIAL PRIMARY KEY, -- serial -> auto-incrementing integer
  name TEXT
)

Now, insert some sample data into the table using the Insert Row tab of the profiles table.

Try out a query

Head to the API tab in the Console and try running the following query:

query {
  profiles {
    id
    name
  }
}

You'll see that you get all the inserted data!

Note: The Hasura GraphQL Engine collects anonymous telemetry to understand usage and provide the best experience. Read more here on what data is collected and the procedure to opt out.

Recap

What did we just do? Well, you just created a powerful, full-featured GraphQL API in less than five minutes. 🎉

We started two Docker containers - one for the Hasura GraphQL Engine and one for the Postgres database. In this example, our Postgres database also contains the Hasura Metadata; which is how Hasura records its information about the GraphQL schema, the relationships between tables, and much more. Finally, we connected our Postgres database to the Hasura GraphQL Engine, which allowed Hasura Engine to automatically create a full CRUD GraphQL API for our Postgres database which we could then easily query, mutate and subscribe to.

Important: Set up the Hasura CLI

The Hasura CLI is a powerful tool that helps you manage your Hasura project and is recommended for the majority of development workflows. It helps track and manage your Hasura Metadata and Migrations and commit them to version control and allows you to quickly move between environments like development and production.

Database operations

We omitted the CLI steps in this guide for the sake of simplicity and brevity, but in a typical new project, you would always include the CLI setup steps.

Every developer working with Hasura should have the Hasura CLI installed. You can quickly get up and running with a new project using the CLI quickstart and learn more by checking out our Advanced Hasura course.

Next steps

• If you're interested in taking a deep dive into Hasura, check out our hands-on 30-Minute Hasura Basics Tutorial.

• There are several options for the implementation of business logic, depending on your use case.

  • Actions: Actions can be used if you'd like to extend your GraphQL schema by integrating with a REST endpoint.
  • Remote Schemas: If you have an existing GraphQL server or if you're comfortable with implementing one, you can use Remote Schemas.
  • Event Triggers: To trigger a serverless function based on a database event, use Event Triggers.
  • Scheduled Triggers: Scheduled Triggers are used to execute custom business logic at specific points in time.

• If you're new to database modeling, check out these guides:

  • Database modeling: Learn how to model your database schema, as well as how to extend it.
  • Querying data: Use GraphQL queries to query data from your GraphQL API.
  • Inserting data: Use GraphQL mutations to insert data into your GraphQL API.

• Security Announcements: Join the Hasura Security Announcements group for emails about security announcements.

• We release new features every month. Sign up for our newsletter by using the link below. We send newsletters only once a month. https://hasura.io/newsletter/.