Connect Databases to Hasura GraphQL Engine

Introduction

You can quickly and easily connect a new, existing, or demo database to Hasura GraphQL Engine in either Hasura Cloud or Hasura Engine running in Docker.

Connect multiple databases

You can also connect to multiple databases in order to build a unified GraphQL API.

Connect a database via the Hasura Console

Hasura Cloud

If you have created your project with Hasura Cloud, click on the Launch Console button to open the Hasura Console in your browser.

Hasura Cloud does not host databases, but does provide integrations with which you can connect databases from many 3rd party managed cloud providers. Check out a list of supported databases here.

To get started quickly with a Postgres database, choose Create New Database:

Follow the prompts or check out our detailed Neon connect page. Hasura Cloud will integrate with your Neon account and manage the initial setup of a Postgres instance. You can always upgrade the instance and manage options later through your Neon account.

Connect to an existing database

To use an existing database, choose Connect existing database and enter your database connection URL and enter your database connection string.

For help finding your particular connection string for your database provider check out our databases page.

You can connect to databases by using environment variables, the raw connection string or connection parameters. It is recommended to use environment variables for better security (as connection details set via a string will be exposed as part of the Hasura Metadata) as well as to allow configuring different databases in different environments (like staging or production) easily.

Allow connections from the Hasura Cloud IP

When using Hasura Cloud, you may need to adjust your connection settings of your database provider to allow connections from the Hasura Cloud IP address.

You can copy the IP address of your Hasura Engine instance from the copy icon in the Hasura Cloud IP field on the Project's details view which you can shortcut to by clicking on your Project name in the Console.

Docker

If you've spun up the Hasura Engine with Docker, you can access the Hasura Console by accessing it in a browser at the URL of your Hasura Engine instance, usually http://localhost:8080.

Enable Hasura Console

To access the Hasura Console via and URL and not via the CLI the HASURA_GRAPHQL_ENABLE_CONSOLE environment variable or --enable-console flag must be set to true.

On the Hasura Console, navigate to the Data tab, you will see the "Connect Database" screen.

You can connect to databases by using environment variables, the raw connection string or connection parameters. It is recommended to use environment variables for better security (as connection details set via a string will be exposed as part of the Hasura Metadata) as well as to allow configuring different databases in different environments (like staging or production) easily.

Connect a database via the Hasura CLI or API

CLI

In your config v3 project, head to the /metadata/databases/databases.yaml file and add the database configuration as below.

- name: <db_name>
  configuration:
    connection_info:
      database_url:
        from_env: <DB_URL_ENV_VAR>
      pool_settings:
        idle_timeout: 180
        max_connections: 50
        retries: 1
    tables: []
    functions: []

Apply the Metadata by running:

hasura metadata apply

API

Depending on the type of database, you can add a database using the sources Metadata API.

For example:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "pg_add_source",
  "args": {
    "name": "<db_name>",
    "configuration": {
      "connection_info": {
        "database_url": {
          "from_env": "<DB_URL_ENV_VAR>"
        },
        "pool_settings": {
          "retries": 1,
          "idle_timeout": 180,
          "max_connections": 50
        }
      }
    }
  }
}

On-the-fly connecting and removing of databases

In versions v2.0.0 and above, databases can be connected and removed dynamically without having to restart the Hasura Engine instance.

Hasura Metadata storage

When using Hasura Cloud, Metadata is stored for you in separate data storage to your connected database(s). When using Docker, if you want to store the Hasura Metadata on a separate database, you can use the HASURA_GRAPHQL_METADATA_DATABASE_URL env var to specify which database to use.

Connect different Hasura instances to the same database

You can connect different Hasura instances (i.e. instances with different Metadata) to the same database as long as there are no Event Triggers in any of the Metadata. Event Triggers store their data in the underlying database and hence different instances acting on the same data can cause undefined behavior during run-time. This should not be a problem if the Hasura instances have the same Metadata.

To connect multiple Hasura instances to the same database, simply follow the steps above for Connect to an existing database for each instance.

Connecting to a database not exposed over the internet

Contact us for VPC peering and on-premise solutions.

More databases

Support for more databases is coming soon. Stay up to date with supported databases here.