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 calledmy_table
in schemamy_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.
- Type names will be pascal-cased. In the above example, Hasura Server will generate the type
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
andnaming_convention
isgraphql-default
, the field names generated will bemy_table
,my_tableByPk
,my_tableAggregate
and so on. hasura-default
is the naming convention used prior tov2.8.0
.
For example:
Consider a schema named, app_db
, with the following structure:
- app_users: A table with the columns user_id, username, last_seen, favourite_day and referred_by.
- week_days: An enum table with column day_names and rows monday, tuesday and so on.
- We have a foreign key set up between
week_days.day_names
andapp_users.favourite_day
.
For the above schema, a sample GraphQL query will look like the following with the different naming conventions:
hasura-default
graphql-default
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
- CLI
- API
Console support will be added soon.
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
}
}
Note
Setting the convention in the source customization will override the default naming convention.