import Tabs from '@theme/Tabs'; import Thumbnail from '@site/src/components/Thumbnail'; import TabItem from '@theme/TabItem'; import GraphiQLIDE from '@site/src/components/GraphiQLIDE';

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 customized to suit your needs.

:::note Supported from

Naming conventions are generally available at v2.34.0 and higher.

This feature is experimental from v2.8.0. You need to enable it by adding naming_convention to the HASURA_GRAPHQL_EXPERIMENTAL_FEATURES environment variable array or with the server flag --experimental-feature.

:::

:::info 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.

:::tip 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, favorite_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.favorite_day.

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

hasura-default

<GraphiQLIDE query={query get_user_aggregate { app_db_app_users_aggregate( distinct_on: referred_by, where: {favorite_day: {_eq: sunday}} ) { aggregate { count stddev_pop { user_id } } } } } response={{ "data": { "app_db_app_users_aggregate": { "aggregate": { "count": 0, "stddev_pop": { "user_id": null } } } } } } />

graphql-default

<GraphiQLIDE query={query get_user_aggregate { appDbAppUsersAggregate( distinctOn: referredBy, where: {favoriteDay: {_eq: SUNDAY}} ) { aggregate { count stddevPop { userId } } } } } response={{ "data": { "appDbAppUsersAggregate": { "aggregate": { "count": 0, "stddevPop": { "userId": null } } } } } } />

:::tip Behavior 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.

:::

Set default naming convention for all sources {#pg-default-naming-convention}

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 {#pg-source-naming-convention}

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 after, enabling the naming conventions, you can choose the naming convention of your choice.

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

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

:::tip Note

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

:::

Backward compatibility

By default, even when graphql-default is selected, the following names keep using hasura-default-style (snake_case) casing, to preserve backward compatibility with schemas generated before September 2023:

• Enum values and the enum type name for named constraints used in on_conflict upserts.
• Type names generated for Postgres scalar casts (for example, the geography/geometry and jsonb/text cast argument types).
• The generated args object type name, and the fromCustomName-derived name used for it, for custom function arguments.

To opt in to the full graphql-default naming for these cases as well, set the environment variable HASURA_FF_NAMING_CONVENTION_SEP_2023=true (case-insensitive). This flag is disabled by default, and only has an effect when a source's naming convention is graphql-default; it has no effect on hasura-default sources.

:::caution

Enabling this flag changes the shape of your GraphQL schema for existing graphql-default sources. Any client queries that reference the affected constraint enum values, cast argument types, or function args type names will need to be updated.

:::