Build a GraphQL Application Using Hasura

On this page

This tutorial shows you how to create a GraphQL application using Hasura Cloud and CockroachDB Dedicated.

The Hasura GraphQL Engine creates GraphQL schemas and resolvers based on the tables and views in your CockroachDB cluster, allowing you to submit GraphQL queries to access and manipulate your data.

Hasura GraphQL Engine v2.16 and later supports CockroachDB v22.2 and later.

Overview

This tutorial will show you how to configure a Hasura project with a CockroachDB data source, allow connections to your CockroachDB cluster from Hasura Cloud, and create a table that is then used with Hasura GraphQL Engine to retrieve and modify data.

Before you begin

Before you start this tutorial, you need:

• An existing CockroachDB Cloud cluster, running CockroachDB v22.2 or later.
• A Hasura Cloud account.

Configure your cluster

Create a new project in Hasura Cloud

1. In the Hasura Cloud console, select Projects, then click New Project.

2. In the Create Project panel select the cloud infrastructure provider and region.

   The cloud infrastructure provider and region should match your cluster. For example, if you created a CockroachDB Dedicated cluster in GCP's us-east1 region, choose a GCP region closest to us-east1.

3. Click Create Free Project.

Add environment variables to your project

You will store your cluster root certificate and connection string in your Hasura project's environment variables. Storing this connection information in environment variables is considered a best practice.

Create a SSL_ROOT_CERT environment variable for your cluster's CA cert.

Create a CRDB_URL environment variable to store the connection string.

1. Click New Env Var.
2. Under Key type CRDB_URL, then press Enter.
3. Paste the connection string for your cluster you copied earlier. Add your SQL user password if necessary to the connection string.

4. Remove the sslmode and sslrootcert query parameters from the end of the connection string. You will add the SSL settings later.

   For example, if your connection string in the CockroachDB Cloud console is:

   postgresql://maxroach:NotAGoodPassword@fake-puppy-595.g95.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full
   

   You would modify the connection string to:

   postgresql://maxroach:NotAGoodPassword@fake-puppy-595.g95.cockroachlabs.cloud:26257/defaultdb
   

5. Click Add.

Create a Data Source in Hasura Cloud

1. In the overview page in Hasura Cloud, select Projects, find the project you created earlier, and click Launch Console.
2. Click Data in the console header to open the Data Manager.
3. Click Connect Database.
4. In the Connect Existing Database tab configure the connection to your cluster.
   1. Under Database Display Name type a name for your connection. Your cluster name is a good option. For example, fake-puppy.
   2. Set Data Source Driver to CockroachDB.
   3. Select Environment Variable, then enter CRDB_URL in the Environment Variable input box.
5. Expand Connection Settings, then expand SSL Certificates Settings and set SSL Mode to verify-full.
6. Enter SSL_ROOT_CERT under SSL Root Certificate, the environment variable you configured earlier.
7. Click Connect Database.

Create a table in your CockroachDB cluster

1. Connect to your cluster using the SQL client.

   cockroach sql --url "{connection string}"
   

   Where {connection string} is the connection string for your cluster you copied earlier.

2. In the SQL client, create an accounts table.

   CREATE TABLE IF NOT EXISTS accounts (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     balance INT8
   );
   

3. Insert some data into the accounts table.

   UPSERT INTO accounts (balance) VALUES (1000), (250);
   

This will create two accounts, one with $1000 and another with $250.

Track the accounts table in the Hasura Cloud Data Manager

1. In the Hasura Cloud Data Manager click public under your connection name.
2. Click the Track All button.
3. Click Yes when prompted to expose the table to the GraphQL API.

Create a GraphQL query in the Hasura Cloud API Explorer

In the Hasura Cloud Explorer, you will see the accounts table. You can expand accounts to construct a GraphQL query against the accounts table.

For example, to create a query that finds all accounts with balances greater than or equal to $500:

1. Enter GetLargeAccounts as the query name in the Explorer.
2. Expand accounts in the Explorer.
3. Check balance and id, then expand where, then balance.
4. Check _gte to create a "greater than or equal to" where clause for balance, then enter 500.

This creates the following GraphQL query:

query GetLargeAccounts {
  accounts(where: {balance: {_gte: "500"}}) {
    balance
    id
  }
}

Click the Execute Query button to run the GetLargeAccounts GraphQL query. The returned data should look like the following:

{
  "data": {
    "accounts": [
      {
        "balance": 1000,
        "id": "2ed41abf-e831-42df-aff4-f88a6f2b0afc"
      }
    ]
  }
}

Next steps

Now that you have connected your cluster to Hasura GraphQL Engine, you can use the Explorer to create GraphQL queries to access and modify data in your cluster's tables. You can then use these queries in your application. For example, you can create Hasura Actions that use these queries. See the Hasura documentation for detailed information on integrating and deploying Hasura in your applications.

Was this helpful?