Connect Databases to Hasura GraphQL Engine

Introduction

You can quickly and easily connect a new, existing, or demo database to Hasura GraphQL Engine using the Hasura Console, CLI or API. You can also connect to multiple databases in order to build a unified GraphQL API.

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.

Connection methods

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.

On Hasura Cloud

Console

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 the list of supported databases.

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

On the Hasura Console, navigate to Data -> Manage -> Connect Database

Option 1: Create and connect a new database

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

Click on Connect Neon Database to create and connect a new Postgres database to your Hasura Project.

Option 2: Connect an existing database

To use an existing database, choose Connect existing database.

• Give the database a name, say default
• Choose the database type from the list of supported databases
• Enter your database connection details
• Click Connect Database

Check out this section for other steps required to ensure connectivity to your database from Hasura Cloud if needed.

CLI

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

- name: <db_name>
  kind: postgres
  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
        }
      }
    }
  }
}

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.

On Hasura deployed via Docker

Console

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 the URL the HASURA_GRAPHQL_ENABLE_CONSOLE environment variable or the --enable-console flag must be set to true.

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

• Give the database a name, say default
• Choose the database type from the list of supported databases
• Enter your database connection details
• Click Connect Database

CLI

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

- name: <db_name>
  kind: postgres
  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
        }
      }
    }
  }
}

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.