From 48dd3d4531ae191e5302ea5e45846007c288bbf4 Mon Sep 17 00:00:00 2001 From: Shyam Sundar J Date: Sun, 30 Oct 2022 19:36:06 +0530 Subject: [PATCH 1/8] updating README files with config generation steps --- docs/internals/README.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/internals/README.md b/docs/internals/README.md index dd45c5c640..5d1db364e2 100644 --- a/docs/internals/README.md +++ b/docs/internals/README.md @@ -34,12 +34,12 @@ The account should have access to all entities that are defined in the runtime c #### 2.2 Supply a `connection-string` for the respective `database-type` -Project startup requires a config that can be generated using hawaii-cli. +Project startup requires a config that can be generated using dab-cli. ##### Use Cli-tool to Generate the config Below command will let you generate the config file with the required database-type and connection-string (**Note:** --name denotes name of the generated config, do not add extension). ``` -hawaii init --name dab-config.XXX --database-type <> --connection-string <> +dab init --name dab-config.XXX --database-type <> --connection-string <> ``` In your editor of choice, you can locate template configuration files in the `DataGateway.Service` directory of the form `dab-config.XXX.json`. @@ -114,7 +114,7 @@ Schema and data population files are included that are necessary for running sam **Cli-tool**: -When we do `hawaii init`, it will automatically generate the default Host settings with default authentication(**Note:** --host-mode is an optional flag that takes in the environment: Production/Development. Updating other keys are not supported currently). Below is the default Host setting that is generated with host-mode as Development. by Default authentication-provider will be "EasyAuth". +When we do `dab init`, it will automatically generate the default Host settings with default authentication(**Note:** --host-mode is an optional flag that takes in the environment: Production/Development. Updating other keys are not supported currently). Below is the default Host setting that is generated with host-mode as Development. by Default authentication-provider will be "EasyAuth". ```json "host": { @@ -136,9 +136,9 @@ When we do `hawaii init`, it will automatically generate the default Host settin #### Setting up Role and Actions -Hawaii-cli allows us to specify role and actions for every entity using the --permission option. permissions can only be specified with add/update command. +Dab-cli allows us to specify role and actions for every entity using the --permission option. permissions can only be specified with add/update command. ``` -hawaii add <> --source <> --permissions "<>:<>" --fields.include <> --fields.exclude <> +dab add <> --source <> --permissions "<>:<>" --fields.include <> --fields.exclude <> ``` **NOTE:** `<>` here can be **anonymous/authenticated**. @@ -146,9 +146,9 @@ hawaii add <> --source <> --permissions "<>:<>" Example: ``` -hawaii add MY_ENTITY -s "my_source" --permissions "anonymous:read" -hawaii update MY_ENTITY --permissions "authenticated:create,update" -hawaii update MY_ENTITY --permissions "authenticated:delete" --fields.include "*" --fields.exclude "id,date" +dab add MY_ENTITY -s "my_source" --permissions "anonymous:read" +dab update MY_ENTITY --permissions "authenticated:create,update" +dab update MY_ENTITY --permissions "authenticated:delete" --fields.include "*" --fields.exclude "id,date" ``` **Generated Config:** ``` @@ -226,9 +226,19 @@ HTTP requests must have the `Authorization` HTTP header set with the value `Bear 4. Select **Build Solution** (Do not select rebuild, as any changes to configuration files may not be reflected in the build folder.) 5. Start runtime +#### Local Development + +For local development, the required config files can be generated along with the build. + +1. The **ConfigGenerators** directory contains the DAB commands for each database type. +2. Update the **connection-string** property of the **init** command. +3. Execute the command `dotnet build -p:generateConfigFiles=true`. This builds the project and generates the config files. +4. The runtime can be run using the above mentioned steps. +5. After performing the code changes, the build can be performed using one of the two ways. + #### Which configuration file is used? -1. Hawaii runtime determines the name of the configuration file based on environment values, following the same behavior offered by ASP.NET Core for the `appsettings.json` file. It expects the configuration file in the same directory as the runtime. +1. DAB runtime determines the name of the configuration file based on environment values, following the same behavior offered by ASP.NET Core for the `appsettings.json` file. It expects the configuration file in the same directory as the runtime. 2. The precedence followed is in the following order from high to low: From 976819384628cdff2adc4333f859d69036e00e17 Mon Sep 17 00:00:00 2001 From: Shyam Sundar J Date: Sun, 30 Oct 2022 19:42:10 +0530 Subject: [PATCH 2/8] adding build instructions after code changes --- docs/internals/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/internals/README.md b/docs/internals/README.md index 5d1db364e2..afa6e9c3c1 100644 --- a/docs/internals/README.md +++ b/docs/internals/README.md @@ -234,7 +234,9 @@ For local development, the required config files can be generated along with the 2. Update the **connection-string** property of the **init** command. 3. Execute the command `dotnet build -p:generateConfigFiles=true`. This builds the project and generates the config files. 4. The runtime can be run using the above mentioned steps. -5. After performing the code changes, the build can be performed using one of the two ways. +5. After performing the code changes, the build can be performed using one of the two ways. + - If there are changes to the dab commands, execute `dotnet build -p:generateConfigFiles=true` + - If there are no changes to the dab commands, execute `dotnet build` #### Which configuration file is used? From e34dd09e99e14d138c3241052e3f86050fb09fd3 Mon Sep 17 00:00:00 2001 From: Shyam Sundar J Date: Sun, 30 Oct 2022 19:47:39 +0530 Subject: [PATCH 3/8] updating dab-cli to dab --- docs/internals/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/internals/README.md b/docs/internals/README.md index afa6e9c3c1..e4536103cc 100644 --- a/docs/internals/README.md +++ b/docs/internals/README.md @@ -34,7 +34,7 @@ The account should have access to all entities that are defined in the runtime c #### 2.2 Supply a `connection-string` for the respective `database-type` -Project startup requires a config that can be generated using dab-cli. +Project startup requires a config that can be generated using dab. ##### Use Cli-tool to Generate the config Below command will let you generate the config file with the required database-type and connection-string (**Note:** --name denotes name of the generated config, do not add extension). @@ -136,7 +136,7 @@ When we do `dab init`, it will automatically generate the default Host settings #### Setting up Role and Actions -Dab-cli allows us to specify role and actions for every entity using the --permission option. permissions can only be specified with add/update command. +dab allows us to specify role and actions for every entity using the --permission option. permissions can only be specified with add/update command. ``` dab add <> --source <> --permissions "<>:<>" --fields.include <> --fields.exclude <> ``` From 04b25fadbb43c4b7a841bfee992a44726179cfa7 Mon Sep 17 00:00:00 2001 From: Shyam Sundar J Date: Sun, 30 Oct 2022 19:51:16 +0530 Subject: [PATCH 4/8] updating local build instruction --- docs/internals/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/internals/README.md b/docs/internals/README.md index e4536103cc..93ef699857 100644 --- a/docs/internals/README.md +++ b/docs/internals/README.md @@ -234,9 +234,7 @@ For local development, the required config files can be generated along with the 2. Update the **connection-string** property of the **init** command. 3. Execute the command `dotnet build -p:generateConfigFiles=true`. This builds the project and generates the config files. 4. The runtime can be run using the above mentioned steps. -5. After performing the code changes, the build can be performed using one of the two ways. - - If there are changes to the dab commands, execute `dotnet build -p:generateConfigFiles=true` - - If there are no changes to the dab commands, execute `dotnet build` +5. After performing the code changes, the build can be performed using one of the two ways. If there are changes to the dab commands, execute `dotnet build -p:generateConfigFiles=true`. If not, executing `dotnet build` will suffice. #### Which configuration file is used? From 4d079dd1ca4aefc786687dade8f1fcfa21e5bf03 Mon Sep 17 00:00:00 2001 From: Shyam Sundar J Date: Sun, 30 Oct 2022 20:20:25 +0530 Subject: [PATCH 5/8] re-wording --- docs/internals/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/internals/README.md b/docs/internals/README.md index 93ef699857..d83bfdbe5b 100644 --- a/docs/internals/README.md +++ b/docs/internals/README.md @@ -233,8 +233,8 @@ For local development, the required config files can be generated along with the 1. The **ConfigGenerators** directory contains the DAB commands for each database type. 2. Update the **connection-string** property of the **init** command. 3. Execute the command `dotnet build -p:generateConfigFiles=true`. This builds the project and generates the config files. -4. The runtime can be run using the above mentioned steps. -5. After performing the code changes, the build can be performed using one of the two ways. If there are changes to the dab commands, execute `dotnet build -p:generateConfigFiles=true`. If not, executing `dotnet build` will suffice. +4. Now, the DAB can be started using one of the available methods. +5. After performing the code changes, the build can be performed using one of the two commands. If there are changes to the dab commands, execute `dotnet build -p:generateConfigFiles=true`. If not, executing `dotnet build` will suffice. #### Which configuration file is used? From 02a67cbf9afe2e7177aa4b8e367e01272a541973 Mon Sep 17 00:00:00 2001 From: Shyam Sundar J Date: Mon, 31 Oct 2022 18:09:32 +0530 Subject: [PATCH 6/8] re-wording the steps --- docs/internals/README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/internals/README.md b/docs/internals/README.md index d83bfdbe5b..39c0ad4be3 100644 --- a/docs/internals/README.md +++ b/docs/internals/README.md @@ -226,15 +226,16 @@ HTTP requests must have the `Authorization` HTTP header set with the value `Bear 4. Select **Build Solution** (Do not select rebuild, as any changes to configuration files may not be reflected in the build folder.) 5. Start runtime -#### Local Development +#### An alternative way to Build and Generate Config Files -For local development, the required config files can be generated along with the build. +The following steps outline an alternative way of building the project. This is particularly useful for development in local. + +1. The **ConfigGenerators** directory contains text files with DAB commands for each database type. +2. Based on your choice of database, in the respective text file, update the **connection-string** property of the **init** command. +3. Execute the command `dotnet build -p:generateConfigFiles=true`. This builds the project and generates the config files. The generated config files can be used to start DAB. +4. After performing the code changes, the build can be performed using one of the two commands. If there are changes to the dab commands, execute `dotnet build -p:generateConfigFiles=true`. If not, executing `dotnet build` will suffice. +5. DAB can be started using one of the various methods outlined in this document. -1. The **ConfigGenerators** directory contains the DAB commands for each database type. -2. Update the **connection-string** property of the **init** command. -3. Execute the command `dotnet build -p:generateConfigFiles=true`. This builds the project and generates the config files. -4. Now, the DAB can be started using one of the available methods. -5. After performing the code changes, the build can be performed using one of the two commands. If there are changes to the dab commands, execute `dotnet build -p:generateConfigFiles=true`. If not, executing `dotnet build` will suffice. #### Which configuration file is used? From f2f8887f8af30ba9afe52d1e226d3cab8fc0bb51 Mon Sep 17 00:00:00 2001 From: Shyam Sundar J Date: Mon, 28 Nov 2022 22:40:56 +0530 Subject: [PATCH 7/8] incorporating review suggestions --- docs/internals/README.md | 36 +++++++++--------------------------- 1 file changed, 9 insertions(+), 27 deletions(-) diff --git a/docs/internals/README.md b/docs/internals/README.md index 39c0ad4be3..642000f01d 100644 --- a/docs/internals/README.md +++ b/docs/internals/README.md @@ -34,12 +34,12 @@ The account should have access to all entities that are defined in the runtime c #### 2.2 Supply a `connection-string` for the respective `database-type` -Project startup requires a config that can be generated using dab. +Project startup requires a config that can be generated using the DAB CLI tool. ##### Use Cli-tool to Generate the config Below command will let you generate the config file with the required database-type and connection-string (**Note:** --name denotes name of the generated config, do not add extension). ``` -dab init --name dab-config.XXX --database-type <> --connection-string <> +dab init --name dab-config.xyz.json --database-type <> --connection-string <> ``` In your editor of choice, you can locate template configuration files in the `DataGateway.Service` directory of the form `dab-config.XXX.json`. @@ -114,7 +114,7 @@ Schema and data population files are included that are necessary for running sam **Cli-tool**: -When we do `dab init`, it will automatically generate the default Host settings with default authentication(**Note:** --host-mode is an optional flag that takes in the environment: Production/Development. Updating other keys are not supported currently). Below is the default Host setting that is generated with host-mode as Development. by Default authentication-provider will be "EasyAuth". +The command, `dab init` will automatically generate the default host settings with default authentication(**Note:** --host-mode is an optional flag that takes in the environment: Production/Development. Updating other keys are not supported currently). Below are the default host settings generated when host-mode is set as Development. By default, the authentication-provider will be **StaticWebApps**. ```json "host": { @@ -136,7 +136,7 @@ When we do `dab init`, it will automatically generate the default Host settings #### Setting up Role and Actions -dab allows us to specify role and actions for every entity using the --permission option. permissions can only be specified with add/update command. +dab allows us to specify roles and actions for every entity using the `--permission` option. Permissions can only be specified with the add/update commands. ``` dab add <> --source <> --permissions "<>:<>" --fields.include <> --fields.exclude <> ``` @@ -226,36 +226,18 @@ HTTP requests must have the `Authorization` HTTP header set with the value `Bear 4. Select **Build Solution** (Do not select rebuild, as any changes to configuration files may not be reflected in the build folder.) 5. Start runtime -#### An alternative way to Build and Generate Config Files +#### An alternative way to generate config files -The following steps outline an alternative way of building the project. This is particularly useful for development in local. +The following steps outline an alternative way of generating config files to assist with local development. 1. The **ConfigGenerators** directory contains text files with DAB commands for each database type. 2. Based on your choice of database, in the respective text file, update the **connection-string** property of the **init** command. -3. Execute the command `dotnet build -p:generateConfigFiles=true`. This builds the project and generates the config files. The generated config files can be used to start DAB. -4. After performing the code changes, the build can be performed using one of the two commands. If there are changes to the dab commands, execute `dotnet build -p:generateConfigFiles=true`. If not, executing `dotnet build` will suffice. -5. DAB can be started using one of the various methods outlined in this document. - +3. Execute the command `dotnet build -p:generateConfigFiles=true` in the directory `data-api-builder\src` to build the project and generate the config file that can be used when starting DAB. The config files will be generated in the directory `data-api-builder\src\Service`. +4. DAB can be started using one of the various methods outlined in this document. #### Which configuration file is used? -1. DAB runtime determines the name of the configuration file based on environment values, following the same behavior offered by ASP.NET Core for the `appsettings.json` file. It expects the configuration file in the same directory as the runtime. - -2. The precedence followed is in the following order from high to low: - - a. Command Line Argument e.g. `--ConfigFileName=custom-config.json` - - b. Value of `DAB_ENVIRONMENT` suffixed to dab-config. - e.g. setting `DAB_ENVIRONMENT=Development` will prompt the runtime to look for `dab-config.Development.json` - - c. Value of `ASPNETCORE_ENVIRONMENT` suffixed to dab-config. - e.g. setting `ASPNETCORE_ENVIRONMENT=MsSql` will prompt the runtime to look for `dab-config.MsSql.json` - - d. By default, runtime will look for `dab-config.json` - -3. For any of the configuration file names determined for the environment, if there is another file with the `.overrides` suffix in the current directory, that overridden file name will instead be picked up. -e.g. if both `dab-config.json` and `dab-config.overrides.json` are present, precedence will be given to `dab-config.overrides.json` - however, the runtime will still follow the above rules of precedence. -e.g. When DAB_ENVIRONMENT is set as `Development` and if all three config files exist- `dab-config.Development.json`, `dab-config.json`, `dab-config.overrides.json`- the runtime will pick `dab-config.Development.json`. +[This document](https://github.com/Azure/data-api-builder/blob/main/docs/configuration-file.md#environments-support) describes this in detail. #### Command Line From 3da8806520718fdaa873e22cf6c5a27aef21e19b Mon Sep 17 00:00:00 2001 From: Shyam Sundar J Date: Wed, 30 Nov 2022 19:39:55 +0530 Subject: [PATCH 8/8] incorporating review feedbacks --- docs/internals/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/internals/README.md b/docs/internals/README.md index 642000f01d..4010034d63 100644 --- a/docs/internals/README.md +++ b/docs/internals/README.md @@ -34,15 +34,15 @@ The account should have access to all entities that are defined in the runtime c #### 2.2 Supply a `connection-string` for the respective `database-type` -Project startup requires a config that can be generated using the DAB CLI tool. +Project startup requires a config file, which can be generated using the DAB CLI tool. ##### Use Cli-tool to Generate the config -Below command will let you generate the config file with the required database-type and connection-string (**Note:** --name denotes name of the generated config, do not add extension). +Below command will let you generate the config file with the required database-type and connection-string (**Note:** --name denotes name of the generated config file. There are no patterns or restrictions on the name of the config file). ``` dab init --name dab-config.xyz.json --database-type <> --connection-string <> ``` -In your editor of choice, you can locate template configuration files in the `DataGateway.Service` directory of the form `dab-config.XXX.json`. +In your editor of choice, you can locate template configuration files in the `DataGateway.Service` directory of the form `dab-config.xyz.json`. Supply a value `connection-string` for the project to be able to connect the service to your database. These connection strings will be specific to the instance of the database that you are running. Example connection strings are provided for assistance. @@ -136,7 +136,7 @@ The command, `dab init` will automatically generate the default host settings wi #### Setting up Role and Actions -dab allows us to specify roles and actions for every entity using the `--permission` option. Permissions can only be specified with the add/update commands. +DAB allows us to specify roles and actions for every entity using the `--permission` option. Permissions can only be specified with the add/update commands. ``` dab add <> --source <> --permissions "<>:<>" --fields.include <> --fields.exclude <> ```