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",
}
},
"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"
}
}
}
}

Args syntax

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

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

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 will be replaced if the source with given name already exists (default: false)
customizationfalseSourceCustomizationCustomize root fields and type names for the source

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)

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 will be replaced if the source with given name already exists (default: false)
customizationfalseSourceCustomizationCustomize root fields and type names for the source

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)