Connecting databases to Hasura GraphQL engine¶
Table of contents
Introduction¶
From v2.0.0 onwards Hasura GraphQL engine allows connecting to multiple databases and build a unified GraphQL API based on the
database schemas.
Connect a database¶
In versions v2.0.0 and above, databases can be connected and removed dynamically without having to restart the GraphQL
engine instance via the console / metadata APIs / CLI:
Head to Data -> Manage -> Connect database
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
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
}
}
}
}
}
Note
- You can connect to databases either using env vars or by using their raw connection string/parameters. It is recommended to use env vars for better security (as connection details are part of Hasura metadata) as well as to allow configuring different databases in different environments (like staging/production) easily.
- A Postgres database can be connected using the
HASURA_GRAPHQL_DATABASE_URLenv var as well in which case it gets added automatically as a database nameddefault
Create a new Postgres DB inside Hasura Cloud
For a quick start with Hasura, you can also create a Postgres database with Heroku from inside of Hasura Cloud. For more information, see Connect new/existing database on Hasura Cloud.
Thank you for subscribing to our newsletter!
