Skip to main content
Version: v2.x

Connecting Hasura to a Google AlloyDB Postgres Database

Introduction​

This guide explains how to connect a new or existing Google AlloyDB Postgres database to a Hasura instance, either on Hasura Cloud or via one of our self-hosted solutions. If you're exploring AlloyDB Postgres, check out their docs before continuing below.

Note

If you plan on using Hasura Cloud, which we recommend, follow steps 1 and 2 below. If you're self-hosting a Hasura instance and already have a project running, skip to step 3.

Step 1: Sign up or log in to Hasura Cloud​

Navigate to Hasura Cloud and sign up or log in.

Step 2: Create a Hasura Cloud project​

On the Hasura Cloud dashboard, create a new project:

Create Hasura Cloud project

After the project is initialized successfully, click on Launch Console to open the Hasura Console in your browser.

On the Hasura Console, navigate to the Data tab and choose Connect Existing Database. Select AlloyDB from the Data Source Driver dropdown. Hasura will prompt you for a Postgres Database URL. We'll create this in the next step and then come back here.

Hasura Cloud database setup

Step 3: Create an AlloyDB database​

Head here to learn more about and to try AlloyDB. If logged in, click Go to console:

AlloyDB splash page

You'll be redirected to GCP where you can get started with AlloyDB by clicking ENABLE:

AlloyDB enable page

To get started, create a cluster by clicking CREATE CLUSTER:

AlloyDB create cluster

If not already enabled, click, ENABLE APIS:

AlloyDB enable APIs

Choose your cluster type:

AlloyDB choose cluster
Note

As GCP states, your selection isn't permanent. At the time of writing this document, only two options are available as the others are currently in development: Highly available and Highly available with read pools.

Configure your cluster by providing the information required:

AlloyDB configure cluster

Under the Networking tab, you'll be prompted to set up a list of IP addresses for your services. Click SET UP CONNECTION:

AlloyDB set up connection
Note

If you work within a company project, you might need extra permissions to ensure that you can choose a specific network. Please contact your Google Cloud admin.

Either select an IP range or let GCP automatically allocate a range. After making your selection, click CONTINUE and then CREATE CONNECTION:

AlloyDB allocate IP

With your cluster configured, you now need to configure your primary instance. Fill in the required information before clicking CREATE CLUSTER:

AlloyDB cluster created

Step 4: Create an AlloyDB auth proxy​

AlloyDB requires an auth proxy to make authorized, encrypted connections to an instance. You can follow GCP's instructions, found here, to create your auth proxy and generate a connection string to use with Hasura. However, we'll also continue below with a Hasura-specific implementation.

Create a GCE instance​

Create a Compute Engine VM that can connect to AlloyDB instances using private services access.

Navigate to the VM Instances page and click CREATE INSTANCE:

AlloyDB VM create instance

Provide a name for this instance and set the following properties:

  • Access scopes

    Set to Allow full access to all Cloud APIs.

  • Network interfaces

    Set to the VPC network configured for private services access to your AlloyDB instance.

    Tip

    For the best performance, select the GCE region as the same or closest to whichever region hosts your Hasura instance.

Click CREATE.

Get the IP address of the AlloyDB instance​

From the cluster listing page for your AlloyDB instance, get the private IP address of the instance. You'll use this in the next step to run the auth proxy and connect it to the AlloyDB instance:

AlloyDB get IP of db

From your GCE-created VM instance, download the auth proxy and, per GCP's instructions, make the file executable.

You can start the auth proxy by running this command:

./alloydb-auth-proxy "projects/<project-id>/locations/<region>/clusters/<alloydb-cluster-id>/instances/<alloydb-instance-id>" --address "0.0.0.0"
Note

This starts the auth proxy client and exposes it to the public. Do note that this setup is an ephemeral one. You should run the auth proxy in a permanent mode (for example, via docker detached mode).

Additionally, you may have to specify a different version of the auth proxy, such as alloydb-auth-proxy.linux.amd64.

Step 5: Add a firewall rule​

With our auth proxy now running, you'll need to create a firewall rule that allows a connection from your Hasura instance. If using Hasura Cloud, from your project's dashboard, copy the Hasura Cloud IP address:

AlloyDB get IP of Hasura Cloud project
Note

If you're using a self-hosted solution, you'll need to determine the IP address manually depending on your hosting service.

Within the VPC Firewall settings, add a new rule by clicking, CREATE FIREWALL RULE:

AlloyDB create firewall rule

Permit connections to port 5432 and specify the IP address of your Hasura instance in the IPv4 range and click CREATE:

AlloyDB firewall rule settings

Step 6: Construct the database connection URL and connect the database​

The structure of the database connection URL looks as follows:

postgresql://<database-user>:<postgres-password>@<ip-address-of-gce-instance>:5432/<database-name>
  • The database-user and database-name are both postgres by default.
  • The postgres-password is the password you entered when creating the AlloyDB cluster in step 3.
  • The ip-address-of-gce-instance is from step 4 when you created a GCE VM instance.

Back on the Hasura Console, enter the database URL:

AlloyDB connect db

Then click Connect Database.

Note

For security reasons, it is recommended to set database URLs as env vars and using the env vars to connect to the databases in place of the raw database URLs.

Voilà. You are ready to start developing.

Hasura Console

Next steps​

Project actions
Note

For more information on which Postgres features we support, check out this page.