Postgres: Naming conventions

Introduction

The Hasura GraphQL engine generates names for various schema objects (fields, types, arguments, etc.) and the naming convention for these autogenerated names can be customised to suit your needs.

Note

Naming conventions are an experimental feature and can be enabled by adding naming_convention to the HASURA_GRAPHQL_EXPERIMENTAL_FEATURES environment variable array or with the server flag --experimental-feature.

Supported from

Naming conventions are available at version v2.8.0 and higher.

Database Support

Naming conventions are only available on Postgres sources.

Supported naming conventions

Currently, Hasura provides two naming conventions:

• hasura-default: This is the default naming convention used in the Hasura server and is used when a naming convention is not explicitly specified. In this naming convention, all names will use snake casing (snake_case) and defined enum table values will not change.

• graphql-default: This is a new naming convention which is more popular in the Javascript ecosystem. Suppose you have a table called my_table in schema my_schema, this convention will work as follows:

  • Type names will be pascal-cased. In the above example, Hasura Server will generate the type MySchemaMyTable for the select field.
  • Field names will be camel-cased. In the above example, Hasura Server will generate the field name mySchemaMyTableAggregate for the aggregate field.
  • Argument names and boolean operators will be camel-cased. For example, Hasura Server will generate argument names like orderBy, distinctOn.
  • Enum values will be upper-cased. i.e. for an enum table, all the values will be upper-cased when used as enum value in Hasura Server.

Naming Convention	Field names	Type names	Arguments	Enum values
hasura-default	Snake case	Snake case	Snake case	as defined
graphql-default	Camel case	Pascal case	Camel case	Uppercased

Note

• Setting custom table and field names in Hasura will override the naming convention of the source. For example, if the custom table name is set to my_table and naming_convention is graphql-default, the field names generated will be my_table, my_tableByPk, my_tableAggregate and so on.
• hasura-default is the naming convention used prior to v2.8.0.

For example:

Consider a schema named, app_db, with the following structure:

1. app_users: A table with the columns user_id, username, last_seen, favourite_day and referred_by.
2. week_days: An enum table with column day_names and rows monday, tuesday and so on.
3. We have a foreign key set up between week_days.day_names and app_users.favourite_day.

For the above schema, a sample GraphQL query will look like the following with the different naming conventions:

hasura-default

GraphiQL

Query Variables

Request Headers

graphql-default

GraphiQL

Query Variables

Request Headers

Behaviour of custom table name

For the graphql-default naming convention and a custom table name for a given table/view, the following rules are followed:

• The custom table name will not be modified (change of case) if it is the first entity for a given name.
• The custom table name may be modified if the name is being prefixed by something.

Sl. no.	Custom table name	Select	Select by pk	Typename	Insert table one
1	table_one	table_one	table_oneByPk	tableOne	insertTable_oneOne
2	tableOne	tableOne	tableOneByPk	tableOne	insertTableOneOne
3	TableOne	TableOne	TableOneByPk	TableOne	insertTableOneOne

Set default naming convention for all sources

For setting the default naming convention for all sources, set the environment variable HASURA_GRAPHQL_DEFAULT_NAMING_CONVENTION to one of hasura-default or graphql-default.

This means any database source will follow this naming convention unless explicitly set to something else.

Set naming convention for a particular source

Console

Currently setting the database naming convention is only allowed at the time of connecting your database. Head to the Data -> Manage -> Connect Database page. Under the GraphQL Field Customization section you can choose the naming convention of your choice.

CLI

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>
  customization:
    naming_convention: hasura-default
  tables: []
  functions: []

Apply the metadata by running:

hasura metadata apply

API

You can set the naming convention of a particular source using the customization field in the pg_add_source metadata API.

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>"
        }
      }
    },
    "customization": {
      "naming_convention": "hasura-default"
    },
    "replace_configuration": true
  }
}

Note

Setting the convention in the source customization will override the default naming convention.