Get Started with Hasura (Docker) & CockroachDB

Introduction

Pre-requisites

• Docker
• Docker Compose
• Optionally, an existing CockroachDB database

Step 1: Get the docker-compose file

Get the Hasura docker-compose file:

# in a new directory run
wget https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/docker-compose-cockroach/docker-compose.yaml
# or run
curl https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/docker-compose-cockroach/docker-compose.yaml -o docker-compose.yaml

Step 2: Run Hasura GraphQL Engine and a CockroachDB instance

The following command will run Hasura along with a Postgres database required for its functioning.

$ docker compose up -d

Check that the containers are running:

$ docker ps

CONTAINER ID   IMAGE                 ... CREATED        STATUS          PORTS            ...
a6956d1492fd   hasura/graphql-engine ... 1 minute ago   Up 10 seconds   8080->8080/tcp   ...
f0931e41c608   cockroach             ... 1 minute ago   Up 10 seconds   26257->26257/tcp ...
42cd380d6ceb   postgres              ... 1 minute ago   Up 10 seconds   5432/tcp         ...

Please do note that you will see a Postgres database running, which is used by Hasura to store its configuration (Hasura Metadata).

Step 3: Open the Hasura Console

Head to http://localhost:8080/console to open the Hasura Console.

Step 4: Add your CockroachDB database as a source to Hasura

In the Data > Data Manager > Connect Existing Database section on the Console, select CockroachDB from the Data Source Driver dropdown and add the connection string directly or through an environment variable. As CockroachDB speaks the same protocol as Postgres, the connection string will start with postgres://, i.e, there is no difference between CockroachDB's connection strings and Postgres’s connection strings.

If you're testing Hasura with CockroachDB running locally, read this guide on Docker networking if you're not sure how to reach your CockroachDB database from the Hasura docker container on Linux, Mac or Windows.

This example uses the DB url postgresql://root@cockroach:26257/hasura, with the service name cockroach, as both Hasura and the CockroachDB services are configured in the above-mentioned docker-compose.yaml file.

Once you add the database, you'll see your database pop up on the sidebar.

Optional: Populate the CockroachDB database

The following examples use author and articles tables, which can be set up as follows.

1. Connect to the CockroachDB container and start the sql command line tool:

docker exec -it docker-compose-cockroach-cockroach-1 ./cockroach sql --insecure

2. Once the command line tool has started, execute the following to set up example tables:

CREATE TABLE author(
    id serial PRIMARY KEY,
    name text UNIQUE,
    "createdAt" timestamp
);

CREATE TABLE article (
    id SERIAL PRIMARY KEY,
    title TEXT,
    content TEXT,
    author_id INTEGER REFERENCES author(id),
    is_published BOOLEAN
);

-- Inserting sequential ids for demo purposes
-- See https://www.cockroachlabs.com/docs/v22.2/serial.html
INSERT INTO
    author (id, name, "createdAt")
VALUES
    (1, 'Author 3', '2017-09-21T09:39:44'),
    (2, 'Author 4', '2017-09-21T09:50:44');

INSERT INTO
    article (title, content, author_id, is_published)
VALUES
    (
        'Article 1',
        'Sample article content 1',
        1,
        false
    ),
    (
        'Article 2',
        'Sample article content 2',
        1,
        TRUE
    ),
    (
        'Article 3',
        'Sample article content 3',
        2,
        TRUE
    );

Step 5: Track existing tables or create new tables

If you have existing tables, head to the database page by clicking on the database name on the sidebar. You should see a list of tables.

Track tables selectively or all of them so that Hasura can introspect the tables and create the corresponding GraphQL schema.

If you have foreign keys, you'll also see suggested relationships. Again, you can choose to track them selectively or all at once.

If you don't have existing tables, go ahead and add new tables and data and try out some queries, just like with a regular Postgres database.

Step 6: Try out a GraphQL query

Head to the API tab in the Console and try running a GraphQL query! Use the explorer sidebar on GraphQL to get help in creating a GraphQL query.

Keep up to date

Hasura currently supports queries, relationships, and mutations on CockroachDB.

Please refer to the Postgres docs on how you can try these features out via the Console or by manipulating Metadata in JSON/YAML directly.

If you'd like to stay informed about the status of CockroachDB support, subscribe to our newsletter and join our discord!

• https://hasura.io/newsletter/
• https://discord.com/invite/hasura