Skip to main content
Version: v2.x

Connect Databases to Hasura GraphQL Engine


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

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

database setup with new database

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:

database setup with existing 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.

database setup with new database

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.

Hasura Cloud IP field
Hasura Cloud IP field

Connect a database via the Hasura CLI or API

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

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

Apply the Metadata by running:

hasura metadata apply
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.