Metadata API Reference: Databases

Introduction

Add/remove databases in Hasura GraphQL Engine.

:::tip Supported from

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

:::

pg_add_source {#metadata-pg-add-source}

pg_add_source is used to connect a Postgres database to Hasura.

Add a database with name pg1:

http

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 {#metadata-pg-add-source-syntax}

Key	Required	Schema	Description
name	true	SourceName	Name of the Postgres database
configuration	true	PGConfiguration	Database connection configuration
replace_configuration	false	Boolean	If set to `true` the configuration and customization will be replaced if the source with given name already exists (default: `false`)
customization	false	SourceCustomization	Customize root fields and type names for the source

:::tip Deprecated field

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

:::

:::tip Note

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

:::

pg_drop_source {#metadata-pg-drop-source}

pg_drop_source is used to remove a Postgres database from Hasura.

Remove a database with name pg1:

http

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 {#metadata-pg-drop-source-syntax}

Key	Required	Schema	Description
name	true	SourceName	Name of the Postgres database
cascade	false	Boolean	When set to `true`, the effect (if possible) is cascaded to any Metadata dependent objects (relationships, permissions etc.) from other sources (default: `false`)

pg_get_source_tables {#metadata-pg-get-source-tables}

pg_get_source_tables is used to list the tables available on a given Postgres database.

List the tables available on a database with name pg1:

http

{
  "type": "pg_get_source_tables",
  "args": {
    "source": "pg1"
  }
}

Args syntax {#metadata-pg-get-source-tables-syntax}

Key	Required	Schema	Description
source	true	SourceName	Name of the Postgres database

rename_source {#metadata-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:

http

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 {#metadata-rename-source-syntax}

Key	Required	Schema	Description
name	true	SourceName	Name of the database
new_name	true	SourceName	Name of the database

pg_update_source {#metadata-pg-update-source}

pg_update_source is used to update Postgres source in Hasura.

Update a database with name pg1:

http

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 {#metadata-pg-update-source-syntax}

Key	Required	Schema	Description
name	true	SourceName	Name of the Postgres database
configuration	false	PGConfiguration	Database connection configuration
customization	false	SourceCustomization	Customize root fields and type names for the source

mssql_add_source {#mssql-add-source}

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

Add a database with name mssql1:

http

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 {#mssql-add-source-syntax}

Key	Required	Schema	Description
name	true	SourceName	Name of the MS SQL Server database
configuration	true	MsSQLConfiguration	Database connection configuration
replace_configuration	false	Boolean	If set to `true` the configuration and customization will be replaced if the source with given name already exists (default: `false`)
customization	false	SourceCustomization	Customize root fields and type names for the source

:::tip Deprecated field

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

:::

mssql_drop_source {#mssql-drop-source}

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

Remove a database with name mssql1:

http

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

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

Args syntax {#mssql-drop-source-syntax}

Key	Required	Schema	Description
name	true	SourceName	Name of the MS SQL Server database
cascade	false	Boolean	When set to `true`, the effect (if possible) is cascaded to any Metadata dependent objects (relationships, permissions etc.) from other sources (default: `false`)

mssql_get_source_tables {#mssql-get-source-tables}

mssql_get_source_tables is used to list the tables available on a given MS SQL Server database.

List the tables available on a database with name mssql1:

http

{
  "type": "mssql_get_source_tables",
  "args": {
    "source": "mssql1"
  }
}

Args syntax {#mssql-get-source-tables-syntax}

Key	Required	Schema	Description
source	true	SourceName	Name of the MS SQL Server database

mssql_update_source {#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:

http

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 {#mssql-update-source-syntax}

Key	Required	Schema	Description
name	true	SourceName	Name of the MS SQL Server database
configuration	false	MsSQLConfiguration	Database connection configuration
customization	false	SourceCustomization	Customize root fields and type names for the source

bigquery_add_source {#metadata-bigquery-add-source}

bigquery_add_source is used to connect a BigQuery database to Hasura.

Add a database with name bigquery1:

http

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 {#metadata-bigquery-add-source-syntax}

Key	Required	Schema	Description
name	true	SourceName	Name of the BigQuery database
configuration	true	BigQueryConfiguration	Database connection configuration
replace_configuration	false	Boolean	If set to `true` the configuration and customization will be replaced if the source with given name already exists (default: `false`)
customization	false	SourceCustomization	Customize root fields and type names for the source

:::tip Deprecated field

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

:::

bigquery_drop_source {#metadata-bigquery-drop-source}

bigquery_drop_source is used to remove a BigQuery database from Hasura.

Remove a database with name bigquery1:

http

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

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

Args syntax {#metadata-bigquery-drop-source-syntax}

Key	Required	Schema	Description
name	true	SourceName	Name of the BigQuery database
cascade	false	Boolean	When 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 {#metadata-bigquery-update-source}

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

Update a database with name bigquery1:

http

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 {#metadata-bigquery-update-source-syntax}

Key	Required	Schema	Description
name	true	SourceName	Name of the BigQuery database
configuration	false	BigQueryConfiguration	Database connection configuration
customization	false	SourceCustomization	Customize root fields and type names for the source