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

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