server/docs: follow up on the naming convention

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4563
GitOrigin-RevId: 0ae1f226a63dae34e6cb0d001b4915c05b0974cf
This commit is contained in:
paritosh-08 2022-05-27 11:25:45 +05:30 committed by hasura-bot
parent 2b3d7c407b
commit 42da1dbc2e
17 changed files with 74 additions and 37 deletions

View File

@ -724,7 +724,7 @@ naming-conventions)
echo -e "\n$(time_elapsed): <########## TEST GRAPHQL-ENGINE WITH EXPERIMENTAL FEATURE: NAMING CONVENTIONS ########>\n"
export HASURA_GRAPHQL_ADMIN_SECRET="HGE$RANDOM"
export HASURA_GRAPHQL_EXPERIMENTAL_FEATURES=naming_conventions
export HASURA_GRAPHQL_EXPERIMENTAL_FEATURES=naming_convention
run_hge_with_args serve
wait_for_port 8080
@ -1247,7 +1247,7 @@ admin_users = postgres' >pgbouncer/pgbouncer.ini
backend-mssql)
echo -e "\n$(time_elapsed): <########## TEST GRAPHQL-ENGINE WITH SQL SERVER BACKEND ###########################################>\n"
export HASURA_GRAPHQL_EXPERIMENTAL_FEATURES=naming_conventions
export HASURA_GRAPHQL_EXPERIMENTAL_FEATURES=naming_convention
run_hge_with_args serve
wait_for_port 8080

View File

@ -2,11 +2,48 @@
## Next release
### Naming conventions in HGE
Now, users can specify the naming convention of the auto-generated names in the HGE.
This is an experimental feature and is postgres only for now. There are two naming
conventions possible as of now:
| 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 |
To configure the naming convention for a source, set the naming convention in source-
customisation while adding the source:
```JSON
{
"resource_version": 2,
"metadata": {
"version": 1,
"sources": [
{
"name": "default",
"kind": "postgres",
"tables": [],
"configuration": {},
"customization": {
"naming_convention": "graphql-default"
}
}
]
}
}
```
To set the default naming convention (this will be used across the sources in HGE),
use the environment variable `HASURA_GRAPHQL_DEFAULT_NAMING_CONVENTION`. Please note
that the global default can be overridden by the source customisation mentioned above.
Note: The naming convention won't be applied to the custom field names and custom
table names (i.e. if the custom table name is `my_table` and `naming_convention`
is `graphql-default`, the field names generated will be `my_table`, `my_tableByPk`,
`my_tableAggregate` and so on).
### Bug fixes and improvements
- server: do not serialize env vars in logs or errors for remote schemas
- server: add support for naming conventions for auto generated names (postgres only)
- server: add support for configurable naming conventions for auto generated names (postgres only)
- server: fix failure when executing consecutive delete mutations on mssql (#8462)
## v2.7.0

View File

@ -66,7 +66,7 @@ X-Hasura-Role: admin
"prefix": "some_type_name_prefix",
"suffix": "some_type_name_suffix"
},
"naming_conventions": "hasura-default"
"naming_convention": "hasura-default"
}
}
}

View File

@ -874,7 +874,7 @@ session variable of the same name.
"prefix": String,
"suffix": String
},
"naming_conventions": String
"naming_convention": String
}
```
@ -882,23 +882,23 @@ session variable of the same name.
|----------------------|----------|-----------------------------------------------------|------------------------------------------------|
| `root_fields` | false | [RootFieldsCustomization](#rootfieldscustomization) | Customization of root field names for a source |
| `type_names` | false | [SourceTypeCustomization](#sourcetypecustomization) | Customization of type names for a source |
| `naming_conventions` | false | String | Naming conventions for a source |
| `naming_convention` | false | String | Naming conventions for a source |
:::info Note
Please note that the naming convention feature is an experimental feature for now.
To use this feature, please use the `--experimental-features=naming_conventions`
To use this feature, please use the `--experimental-features=naming_convention`
flag or set the `HASURA_GRAPHQL_EXPERIMENTAL_FEATURES` environment variable to
`naming_conventions`.
`naming_convention`.
The naming convention can either be `graphql-default` or `hasura-default` (default).
**The `graphql-default` naming convention is supported only for postgres databases right now.**
Typecase for each of the naming convention is mentioned below:
| Naming Convention | Field names | Type names |
|-------------------|-------------|-------------|
| hasura-default | Snake case | Snake case |
| graphql-default | Camel case | Pascal case |
| 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 |
The naming convention can be overridden by `custom_name` in [Table Config](#table-config)
or by setting [Custom Root Fields](#custom-root-fields).

View File

@ -759,7 +759,7 @@ When the `--infer-function-permissions` flag is set to `true` or the flag is omi
<td>
List of experimental features to be enabled. A comma separated value is expected. Options:
`inherited_roles`, `naming_conventions, streaming_subscriptions`.
`inherited_roles`, `naming_convention, streaming_subscriptions`.
<em>(Available for versions > v2.0.0)</em>

View File

@ -520,7 +520,7 @@ elif [ "$MODE" = "test" ]; then
# are defined.
export HASURA_GRAPHQL_PG_SOURCE_URL_1=${HASURA_GRAPHQL_PG_SOURCE_URL_1-$PG_DB_URL}
export HASURA_GRAPHQL_PG_SOURCE_URL_2=${HASURA_GRAPHQL_PG_SOURCE_URL_2-$PG_DB_URL}
export HASURA_GRAPHQL_EXPERIMENTAL_FEATURES="inherited_roles, naming_conventions"
export HASURA_GRAPHQL_EXPERIMENTAL_FEATURES="inherited_roles, naming_convention"
export HASURA_GRAPHQL_MSSQL_SOURCE_URL=$MSSQL_CONN_STR
# Using --metadata-database-url flag to test multiple backends

View File

@ -292,7 +292,7 @@ buildRoleContext options sources remotes allActionInfos customTypes role remoteS
sourceCustomization =
if EFNamingConventions `elem` expFeatures
then sourceCustomization'
else sourceCustomization' {_scNamingConventions = Nothing}
else sourceCustomization' {_scNamingConvention = Nothing}
buildRelayRoleContext ::
forall m.
@ -404,7 +404,7 @@ buildRelayRoleContext options sources allActionInfos customTypes role expFeature
sourceCustomization =
if EFNamingConventions `elem` expFeatures
then sourceCustomization'
else sourceCustomization' {_scNamingConventions = Nothing}
else sourceCustomization' {_scNamingConvention = Nothing}
-- | Builds the schema context for unauthenticated users.
--

View File

@ -118,7 +118,7 @@ instance FromJSON NamingCase where
parseNamingConventionFromText :: Text -> Either String NamingCase
parseNamingConventionFromText "hasura-default" = Right HasuraCase
parseNamingConventionFromText "graphql-default" = Right GraphqlCase
parseNamingConventionFromText _ = Left "naming_conventions can either be \"hasura-default\" or \"graphql-default\""
parseNamingConventionFromText _ = Left "naming_convention can either be \"hasura-default\" or \"graphql-default\""
mkCustomizedTypename :: Maybe SourceTypeCustomization -> NamingCase -> MkTypename
mkCustomizedTypename stc tCase = MkTypename ((applyTypeNameCaseCust tCase) . (applyTypeCust stc))
@ -197,7 +197,7 @@ applyPrefixSuffix (Just prefix) (Just suffix) name = prefix <> name <> suffix
data SourceCustomization = SourceCustomization
{ _scRootFields :: !(Maybe RootFieldsCustomization),
_scTypeNames :: !(Maybe SourceTypeCustomization),
_scNamingConventions :: !(Maybe NamingCase)
_scNamingConvention :: !(Maybe NamingCase)
}
deriving (Eq, Show, Generic)
@ -219,7 +219,7 @@ getSourceTypeCustomization :: SourceCustomization -> SourceTypeCustomization
getSourceTypeCustomization = fromMaybe emptySourceTypeCustomization . _scTypeNames
getNamingConvention :: SourceCustomization -> NamingCase
getNamingConvention = fromMaybe HasuraCase . _scNamingConventions
getNamingConvention = fromMaybe HasuraCase . _scNamingConvention
-- | Function to apply root field name customizations.
newtype MkRootFieldName = MkRootFieldName {runMkRootFieldName :: G.Name -> G.Name}
@ -256,7 +256,7 @@ withSourceCustomization sc@SourceCustomization {..} namingConventionSupport defa
-- have restricted this feature to postgres for now.
tCase <-
case namingConventionSupport of
AllConventions -> pure (fromMaybe defaultNC _scNamingConventions)
AllConventions -> pure (fromMaybe defaultNC _scNamingConvention)
OnlyHasuraCase -> case namingConv of
GraphqlCase -> throw400 NotSupported $ "sources other than postgres do not support graphql-default as naming convention yet"
HasuraCase -> pure HasuraCase

View File

@ -713,11 +713,11 @@ enabledAPIsEnv =
experimentalFeaturesEnv :: (String, String)
experimentalFeaturesEnv =
( "HASURA_GRAPHQL_EXPERIMENTAL_FEATURES",
"Comma separated list of experimental features. (all: inherited_roles,optimize_permission_filters and naming_conventions). "
"Comma separated list of experimental features. (all: inherited_roles,optimize_permission_filters and naming_convention). "
<> "optimize_permission_filters: Use experimental SQL optimization"
<> "transformations for permission filters. "
<> "inherited_roles: ignored; inherited roles cannot be switched off"
<> "naming_conventions: apply naming convention (graphql-default/hasura-default) based on source customization"
<> "naming_convention: apply naming convention (graphql-default/hasura-default) based on source customization"
)
gracefulShutdownEnv :: (String, String)

View File

@ -402,11 +402,11 @@ readExperimentalFeatures = mapM readAPI . T.splitOn "," . T.pack
"inherited_roles" -> Right EFInheritedRoles
"streaming_subscriptions" -> Right EFStreamingSubscriptions
"optimize_permission_filters" -> Right EFOptimizePermissionFilters
"naming_conventions" -> Right EFNamingConventions
"naming_convention" -> Right EFNamingConventions
_ ->
Left $
"Only expecting list of comma separated experimental features, options are:"
++ "inherited_roles, streaming_subscriptions, optimize_permission_filters, naming_conventions"
++ "inherited_roles, streaming_subscriptions, optimize_permission_filters, naming_convention"
readLogLevel :: String -> Either String L.LogLevel
readLogLevel s = case T.toLower $ T.strip $ T.pack s of

View File

@ -60,15 +60,15 @@ instance FromJSON ExperimentalFeature where
parseJSON = withText "ExperimentalFeature" $ \case
"inherited_roles" -> pure EFInheritedRoles
"optimize_permission_filters" -> pure EFOptimizePermissionFilters
"naming_conventions" -> pure EFNamingConventions
"naming_convention" -> pure EFNamingConventions
"streaming_subscriptions" -> pure EFStreamingSubscriptions
_ -> fail "ExperimentalFeature can only be one of these value: inherited_roles, optimize_permission_filters, naming_conventions or streaming_subscriptions"
_ -> fail "ExperimentalFeature can only be one of these value: inherited_roles, optimize_permission_filters, naming_convention or streaming_subscriptions"
instance ToJSON ExperimentalFeature where
toJSON = \case
EFInheritedRoles -> "inherited_roles"
EFOptimizePermissionFilters -> "optimize_permission_filters"
EFNamingConventions -> "naming_conventions"
EFNamingConventions -> "naming_convention"
EFStreamingSubscriptions -> "streaming_subscriptions"
data MaintenanceMode a = MaintenanceModeEnabled a | MaintenanceModeDisabled

View File

@ -16,7 +16,7 @@
idle_timeout: 180
retries:
customization:
naming_conventions: graphql-default
naming_convention: graphql-default
- description: create enum table
url: /v1/query

View File

@ -18,7 +18,7 @@
idle_timeout: 180
retries:
customization:
naming_conventions: graphql-default
naming_convention: graphql-default
- description: create table 1
url: /v1/query

View File

@ -17,4 +17,4 @@
max_connections: 50
idle_timeout: 180
customization:
naming_conventions: graphql-default
naming_convention: graphql-default

View File

@ -18,7 +18,7 @@
idle_timeout: 180
retries:
customization:
naming_conventions: graphql-default
naming_convention: graphql-default
- description: create table 1
url: /v1/query
@ -218,7 +218,7 @@
idle_timeout: 180
retries:
customization:
naming_conventions: hasura-default
naming_convention: hasura-default
- description: track table
url: /v1/metadata

View File

@ -21,7 +21,7 @@
root_fields:
prefix: test
suffix: Query
naming_conventions: graphql-default
naming_convention: graphql-default
- description: create table 1
url: /v1/query
@ -224,7 +224,7 @@
root_fields:
prefix: test_
suffix: _query
naming_conventions: hasura-default
naming_convention: hasura-default
- description: track table
url: /v1/metadata

View File

@ -5,8 +5,8 @@ import os
@pytest.mark.skipif(
os.getenv('HASURA_GRAPHQL_EXPERIMENTAL_FEATURES') is None or
not 'naming_conventions' in os.getenv('HASURA_GRAPHQL_EXPERIMENTAL_FEATURES'),
reason="This test expects the (naming_conventions) experimental feature turned on")
not 'naming_convention' in os.getenv('HASURA_GRAPHQL_EXPERIMENTAL_FEATURES'),
reason="This test expects the (naming_convention) experimental feature turned on")
class TestNamingConventions:
@classmethod