Skip to main content
Version: v2.x

Metadata API Reference: Databases

Introduction

Add/remove databases in Hasura GraphQL Engine.

Supported from

The Metadata API is supported for versions v2.0.0 and above and replaces the older schema/Metadata API.

pg_add_source

pg_add_source is used to connect a Postgres database to Hasura.

Add a database with name pg1:

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

{
"type": "pg_add_source",
"args": {
"name": "pg1",
"configuration": {
"connection_info": {
"database_url": {
"from_env": "<DB_URL_ENV_VAR>"
},
"pool_settings": {
"max_connections": 50,
"idle_timeout": 180,
"retries": 1,
"pool_timeout": 360,
"connection_lifetime": 600
},
"use_prepared_statements": true,
"isolation_level": "read-committed"
},
"connection_template": {
"template": "{{ if $.request.session?[\"x-hasura-role\"] == \"admin\" }} {{$.primary}} {{else}} {{$.connection_set.db_1}} {{ end }}"
},
"connection_set": [
{
"name": "db_1",
"connection_info": {
"database_url": {
"from_env": "<DB_URL_ENV_VAR>"
}
}
}
]
},
"replace_configuration": false,
"customization": {
"root_fields": {
"namespace": "some_field_name",
"prefix": "some_field_name_prefix",
"suffix": "some_field_name_suffix"
},
"type_names": {
"prefix": "some_type_name_prefix",
"suffix": "some_type_name_suffix"
},
"naming_convention": "hasura-default"
}
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueSourceNameName of the Postgres database
configurationtruePGConfigurationDatabase connection configuration
replace_configurationfalseBooleanIf set to true the configuration and customization will be replaced if the source with given name already exists (default: false)
customizationfalseSourceCustomizationCustomize root fields and type names for the source
Deprecated field

The replace_configuration field is deprecated in favour of the pg_update_source API.

Note

The schema specified in the extensions_schema is expected to exist in the search path of your database.

pg_drop_source

pg_drop_source is used to remove a Postgres database from Hasura.

Remove a database with name pg1:

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

{
"type": "pg_drop_source",
"args": {
"name": "pg1",
"cascade": true
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueSourceNameName of the Postgres database
cascadefalseBooleanWhen set to true, the effect (if possible) is cascaded to any Metadata dependent objects (relationships, permissions etc.) from other sources (default: false)

rename_source

rename_source is used to rename an existing source.

Given there already exists a database with name pg1, we can rename it to pg2 using:

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

{
"type": "rename_source",
"args": {
"name": "pg1",
"new_name": "pg2"
}
}

Note that all settings are kept, only the name is changed.

Args syntax

KeyRequiredSchemaDescription
nametrueSourceNameName of the database
new_nametrueSourceNameName of the database

pg_update_source

pg_update_source is used to update Postgres source in Hasura.

Update a database with name pg1:

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

{
"type": "pg_update_source",
"args": {
"name": "pg1",
"configuration": {
"connection_info": {
"database_url": {
"from_env": "<DB_URL_ENV_VAR>"
},
"pool_settings": {
"max_connections": 50,
"idle_timeout": 180,
"retries": 1,
"pool_timeout": 360,
"connection_lifetime": 600
},
"use_prepared_statements": true,
"isolation_level": "read-committed",
}
},
"customization": {
"root_fields": {
"namespace": "some_field_name",
"prefix": "some_field_name_prefix",
"suffix": "some_field_name_suffix"
},
"type_names": {
"prefix": "some_type_name_prefix",
"suffix": "some_type_name_suffix"
},
"naming_convention": "hasura-default"
}
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueSourceNameName of the Postgres database
configurationfalsePGConfigurationDatabase connection configuration
customizationfalseSourceCustomizationCustomize root fields and type names for the source

mssql_add_source

mssql_add_source is used to connect an MS SQL Server database to Hasura.

Add a database with name mssql1:

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

{
"type": "mssql_add_source",
"args": {
"name": "mssql1",
"configuration": {
"connection_info": {
"connection_string": {
"from_env": "<CONN_STRING_ENV_VAR>"
},
"pool_settings": {
"max_connections": 50,
"idle_timeout": 180
}
}
},
"customization": {
"root_fields": {
"namespace": "some_field_name",
"prefix": "some_field_name_prefix",
"suffix": "some_field_name_suffix"
},
"type_names": {
"prefix": "some_type_name_prefix",
"suffix": "some_type_name_suffix"
}
}
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueSourceNameName of the MS SQL Server database
configurationtrueMsSQLConfigurationDatabase connection configuration
replace_configurationfalseBooleanIf set to true the configuration and customization will be replaced if the source with given name already exists (default: false)
customizationfalseSourceCustomizationCustomize root fields and type names for the source
Deprecated field

The replace_configuration field is deprecated in favour of the mssql_update_source API.

mssql_drop_source

mssql_drop_source is used to remove an MS SQL Server database from Hasura.

Remove a database with name mssql1:

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

{
"type": "mssql_drop_source",
"args": {
"name": "mssql1"
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueSourceNameName of the MS SQL Server database
cascadefalseBooleanWhen set to true, the effect (if possible) is cascaded to any Metadata dependent objects (relationships, permissions etc.) from other sources (default: false)

mssql_update_source

mssql_update_source is used to update an already existing MS SQL Server source in Hasura.

Update a database with name mssql1:

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

{
"type": "mssql_update_source",
"args": {
"name": "mssql1",
"configuration": {
"connection_info": {
"connection_string": {
"from_env": "<CONN_STRING_ENV_VAR>"
},
"pool_settings": {
"max_connections": 50,
"idle_timeout": 180
}
}
},
"customization": {
"root_fields": {
"namespace": "some_field_name",
"prefix": "some_field_name_prefix",
"suffix": "some_field_name_suffix"
},
"type_names": {
"prefix": "some_type_name_prefix",
"suffix": "some_type_name_suffix"
}
}
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueSourceNameName of the MS SQL Server database
configurationfalseMsSQLConfigurationDatabase connection configuration
customizationfalseSourceCustomizationCustomize root fields and type names for the source

bigquery_add_source

bigquery_add_source is used to connect a BigQuery database to Hasura.

Add a database with name bigquery1:

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

{
"type": "bigquery_add_source",
"args": {
"name": "bigquery1",
"configuration": {
"service_account": "bigquery_service_account",
"project_id": "bigquery_project_id",
"datasets": "dataset1, dataset2"
},
"customization": {
"root_fields": {
"namespace": "some_field_name",
"prefix": "some_field_name_prefix",
"suffix": "some_field_name_suffix"
},
"type_names": {
"prefix": "some_type_name_prefix",
"suffix": "some_type_name_suffix"
}
}
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueSourceNameName of the BigQuery database
configurationtrueBigQueryConfigurationDatabase connection configuration
replace_configurationfalseBooleanIf set to true the configuration and customization will be replaced if the source with given name already exists (default: false)
customizationfalseSourceCustomizationCustomize root fields and type names for the source
Deprecated field

The replace_configuration field is deprecated in favour of the bigquery_update_source API.

bigquery_drop_source

bigquery_drop_source is used to remove a BigQuery database from Hasura.

Remove a database with name bigquery1:

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

{
"type": "bigquery_drop_source",
"args": {
"name": "bigquery1"
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueSourceNameName of the BigQuery database
cascadefalseBooleanWhen set to true, the effect (if possible) is cascaded to any Metadata dependent objects (relationships, permissions etc.) from other sources (default: false)

bigquery_update_source

bigquery_update_source is used to update an already existing BigQuery source in Hasura.

Update a database with name bigquery1:

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

{
"type": "bigquery_update_source",
"args": {
"name": "bigquery1",
"configuration": {
"service_account": "bigquery_service_account",
"project_id": "bigquery_project_id",
"datasets": "dataset1, dataset2"
},
"customization": {
"root_fields": {
"namespace": "some_field_name",
"prefix": "some_field_name_prefix",
"suffix": "some_field_name_suffix"
},
"type_names": {
"prefix": "some_type_name_prefix",
"suffix": "some_type_name_suffix"
}
}
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueSourceNameName of the BigQuery database
configurationfalseBigQueryConfigurationDatabase connection configuration
customizationfalseSourceCustomizationCustomize root fields and type names for the source