From d328d673ca74b7d0edb51c19c404785995bc0ae3 Mon Sep 17 00:00:00 2001 From: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> Date: Thu, 9 Jun 2022 15:16:29 +0530 Subject: [PATCH] docs: restructure naming conventions page PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4670 Co-authored-by: paritosh-08 <85472423+paritosh-08@users.noreply.github.com> GitOrigin-RevId: 848295d1dae95c618aac37da8df520412b08a677 --- .../postgres/schema/naming-convention.mdx | 233 +++++++++++------- .../graphql-engine-flags/reference.mdx | 20 ++ 2 files changed, 169 insertions(+), 84 deletions(-) diff --git a/docs/docs/graphql/core/databases/postgres/schema/naming-convention.mdx b/docs/docs/graphql/core/databases/postgres/schema/naming-convention.mdx index 3bdf62f0da4..32f0ffca3f4 100644 --- a/docs/docs/graphql/core/databases/postgres/schema/naming-convention.mdx +++ b/docs/docs/graphql/core/databases/postgres/schema/naming-convention.mdx @@ -1,6 +1,6 @@ --- -sidebar_label: Naming Convention -sidebar_position: 13 +sidebar_label: Naming conventions +sidebar_position: 9.5 description: Customizing auto generated names in Hasura with a naming convention keywords: - hasura @@ -16,7 +16,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import GraphiQLIDE from '@site/src/components/GraphiQLIDE'; -# Postgres: Naming Conventions +# Postgres: Naming conventions ## Introduction @@ -25,7 +25,7 @@ convention for these autogenerated names can be customised to suit your needs. :::tip Note -Naming Convention is an experimental feature and can be enabled by adding `naming-convention` to the +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`. ::: @@ -33,22 +33,23 @@ Naming Convention is an experimental feature and can be enabled by adding `namin :::note Supported from -Naming Convention is available at version `v2.8.0` and higher. +Naming conventions are available at version `v2.8.0` and higher. ::: :::info Database Support -Naming Convention is only available on Postgres sources +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 +- `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. This is the only naming convention available prior to `v2.8.0`. +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: @@ -66,105 +67,169 @@ Suppose you have a table called `my_table` in schema `my_schema`, this conventio | `hasura-default` | Snake case | Snake case | Snake case | as defined | | `graphql-default` | Camel case | Pascal case | Camel case | Uppercased | -## How to set a naming convention? -To set a naming convention in Hasura Server, you can do the following: +:::tip Note -### Set default naming convention for all sources +- Setting [custom table and field names](/graphql/core/databases/postgres/schema/custom-field-names.mdx) + 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 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 +**For example:** -To set the naming convention of a particular source, you can set the `naming_convention` field in the -[source customization](/graphql/core/api-reference/syntax-defs.mdx#sourcecustomization) field of the metadata. -Setting the convention in the source customization will override the default naming convention. - -## Example - -Consider a schema named, `app_db`, with the following two tables: +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`. -Note that we have a foreign key setup 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: -For the above setup, an example graphql query looks like the following: +**hasura-default** + + + +**graphql-default** + + + +## 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} + + + Console support will be added soon. + + + + + Head to the + `/metadata/databases/databases.yaml` file and add the database + configuration as below: + + ```yaml {6-7} + - name: + configuration: + connection_info: + database_url: + from_env: + customization: + naming_convention: hasura-default + tables: [] + functions: [] + ``` + + Apply the metadata by running: + + ```bash + hasura metadata apply + ``` + + + + + You can set the naming convention of a particular source using the `customization` field in the + [pg_add_source](/graphql/core/api-reference/metadata-api/source.mdx#metadata-pg-add-source) metadata API. + + ```http {16-18} + POST /v1/metadata HTTP/1.1 + Content-Type: application/json + X-Hasura-Role: admin - - ", + "configuration": { + "connection_info": { + "database_url": { + "from_env": "" } } - } + }, + "customization": { + "naming_convention": "hasura-default" + }, + "replace_configuration": true } } - `} - /> - - - - - + ``` + :::tip Note -Note that setting custom table names and [custom field names](/graphql/core/databases/postgres/schema/custom-field-names.mdx) -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. +Setting the convention in the source customization will override the default naming convention. ::: + + + diff --git a/docs/docs/graphql/core/deployment/graphql-engine-flags/reference.mdx b/docs/docs/graphql/core/deployment/graphql-engine-flags/reference.mdx index 5ab23b74163..e579d0e53e8 100644 --- a/docs/docs/graphql/core/deployment/graphql-engine-flags/reference.mdx +++ b/docs/docs/graphql/core/deployment/graphql-engine-flags/reference.mdx @@ -856,6 +856,26 @@ Used to set the connection initialisation timeout for (default: `3`) + + + + +N/A + + + +`HASURA_GRAPHQL_DEFAULT_NAMING_CONVENTION` + + + + +Used to set the default naming convention for all sources. See +[naming convention](/graphql/core/databases/postgres/schema/naming-convention.mdx) for more information. + +(default: `hasura-default`) + +(Available for versions ≥ v2.8.0) +