doc update

Author: padhia

README.md

@@ -1,45 +1,46 @@
 # sfenv
 
-`sfenv` is an *experimental application*, a *minimum viable product* to allow declaratively define Snowflake database environments and generate SQL statements for it.
+`sfenv` helps manage *Snowflake Environments* consisting of Snowflake objects and permissions.
 
-`sfenv` reads a set of *rules* from a YAML (or a JSON) file and produces SQL statements. [RULES.md](./RULES.md) describes the structure of such a file. Also, refer to [sample.yaml](./sample.yaml) for an example of a rules file.
+Snowflake objects and permission are declaratively defined in a YAML/JSON file (called *Rules File*). See [sample.yaml](./sample.yaml) for an example and [RULES.md](./RULES.md) for a detailed description of rules specification.
 
 ## Features
 
 With `sfenv` utility,
 
-1. **Manage** following database objects
+1. A single rule file can be used to manage one or more *environments*
+1. The following database objects are supported
 	- Databases
 	- Schemas
 	- Warehouses
 	- Shares
 	- Users
 	- Application IDs
 	- Access Roles that control fine-grained access to objects or resources
-	- Functional Roles build on *Access Roles* for the purpose of granting permissions to User IDs
-1. **Manage** privileges by following Snowflake recommended [best practices](https://community.snowflake.com/s/article/Snowflake-Security-Overview-and-Best-Practices)
-	- privileges are granted to *Access Roles*
+	- Functional Roles build on *Access Roles* to grant permissions to User IDs
+1. *Privileges* can be defined as per Snowflake's [recommended best practices](https://community.snowflake.com/s/article/Snowflake-Security-Overview-and-Best-Practices)
+	- privileges are granted to *Access Roles* (access roles are database roles when they apply to database objects)
 	- *Access Roles* are granted to *Functional Roles*
 	- *Functional Roles* are granted to *User IDs*
-1. generate incremental (delta) SQL statements for only the changes made since the last time. This greatly reduces the number of SQL statements generated and the time it takes to run them.
-1. manage different permissions for different environments with one rules file.
+1. When the Rules-file is controlled by git, it is possible to generate incremental (delta) SQL statements for only the changes made since the last time (see [Maintaining State](#maintaining-state) below)
+1. Customize permissions for specific environments within one rules file.
 
 # Usage
 
 ```sh
-sfenv [--diff <filename>] [--env <string>] [--only-future] [--allow-drops] [<Rules file>]
+sfenv [--diff <Rules-file>] [--env <string>] [--only-future] [--allow-drops] [<Rules-file>]
 ```
 
 Where:
 
-- `<Rules file>`: A YAML file containing object and privileges definitions
+- `<Rules-file>`: A YAML/JSON file containing object and privileges definitions
 - `--env ENV`: An *environment* name, to derive object and role names (default: `DEV`)
 - `--diff <Rules file>`: Optional, when specified, SQL statements are generated only for the differences between the specified file and main rules file.
-- `--drop <all|non-local|none`: determine how `DROP` SQL statements are produced
-    - `all`: all `DROP` statements are produced as normal SQL statements
-    - `non-local`: `DROP` statements that may lead to data loss (dropping local databases and schemas, but not imported from Shares) are commented out
-    - `none`: all `DROP` statements are commented out
-- `--only-future`: When generating permissions for objects at schema level, generate only `FUTURE` grants (skip `ALL` grants)
+- `--drop <all|non-local|none`: determine how the `DROP` SQL statements are generated
+	- `all`: all `DROP` statements are produced as normal SQL statements
+	- `non-local`: `DROP` statements that may lead to data loss (includes local databases and schemas, but not the *shared* databases) are commented out
+	- `none`: all `DROP` statements are commented out
+- `--only-future`: When generating permissions for objects at the schema level, generate only `FUTURE` grants, and skip `ALL` grants which can be expensive to run
 
 ## Maintaining State
 
@@ -56,13 +57,13 @@ Run the following command to register `sfenv` as a `difftool`.
 ```sh
 git config difftool.sfenv.cmd 'sfenv $REMOTE --diff $LOCAL'
 ```
-Any time you modify the rules file, you can then use the following command to generate SQL statements to automatically process only the changes made since the previous commit
+Any time you modify the rules file, you can then use the following command to generate SQL statements to process only the changes made since the previous commit automatically
 
 ```sh
 git difftool -yt sfenv my-rules.yaml
 ```
 
 # Known Limitations
-1. Support for only a small subset of Snowflake objects. Notably, managing Databases, Schemas, Warehouses, Roles, and permissions (RBAC) is extensively supported.
-1. Error reporting may be terse, especially for YAML or JSON parsing errors. If you aren't sure if the rules file is a valid YAML or JSON file, it might be easier first to locate and fix errors by using any of the freely available online services.
+1. Does not support all available Snowflake objects. Specifically, managing Databases, Schemas, Warehouses, Roles, Users and permissions (RBAC) are fully supported.
+1. Error reporting may be terse, especially for YAML or JSON parsing errors. If you aren't sure if the rules file is a valid YAML or JSON file, it might be easier first to locate and fix mistakes by using any of the freely available online services.
 1. There is no validation of object parameters or privileges. Any unrecognized object parameters or privileges are used verbatim in the generated SQL.

RULES.md

@@ -1,8 +1,8 @@
 # Rules File
 
-Rules file is a `yaml` or `json` file that is used by `sfenv` utility to generate DDLs and DCLs. A rule file contains one YAML/JSON object with several attributes (*sections*) to allow fine-grained creation of objects, roles and permissions.
+Rules file is a `yaml` or a `json` file that is used by `sfenv` utility to generate Snowflake DDLs and DCLs. A *rules-file* consists of a configuration to help derive names, object definitions for one more *object types* (called *sections*), roles and permissions.
 
-Sections (or attributes of the top-level object), are documented below. Only the `config` section is required, any other section may be omitted if not needed.
+All available *sections* are documented below. Only the `config` section is required, all other sections may be omitted when not required.
 
 - **`config`**
 - `imports`
@@ -12,18 +12,18 @@ Sections (or attributes of the top-level object), are documented below. Only the
 - `users`
 - `apps`
 
-Although the syntax doesn't explicitly list, but all object and role definitions accept `tags` mapping object containig a *tag* and a *value*
+Although object properties listed below don't explicitly include them, but all object and role definitions accept `tags` *mapping object* consisting of *tag-name* and a *tag-value*
 
 ## `config`
 
-A YAML/JSON object that controls naming of various database objects such as databases, schemas, roles etc. This object must have all attributes listed in the following example:
+A YAML/JSON object that controls naming of database objects. This section must list all attributes shown in the following example:
 
 **Example**:
 
 ```yaml
 config:
   secadm: "RL_{env}_SECADMIN"
-  sysadm: "RL_{env}_SYSADMIN"
+  dbadm: "RL_{env}_SYSADMIN"
   database: "{db}_{env}"
   schema: "{sch}"
   warehouse: "WH_{env}_{wh}"
@@ -35,11 +35,13 @@ config:
 
 Notes:
 
-- Value for each attribute is a template to derive corresponding database object name by substituting placeholder (names enclosed in `{}`).
-- A special placeholder, named `env`, lets one rule file to generate different sets of SQL statements corresponding to different environments.
+- Each attribute in `config` is a *template* to derive corresponding object name. Names are derived by substituting *placeholders* (variables enclosed in `{}`).
+- A special placeholder, named `env`, lets one rule file to generate different sets of SQL statements for different environments.
 - Value for `env` is supplied at runtime whereas values for all other placeholder names are taken from other sections within the rules file.
-- Access role names are derived using the placeholders of the resource they control.
-- Generated DDLs and DCLs contain appropriate `use role ...` statements to set either `secadm` and `sysadm`, which are security and system admin roles respectively. `secadm` manages other roles and permissions, whereas `sysadm` owns all database resources in an environment.
+- Access role names are derived using the placeholders of the resource type they control.
+- Generated DDLs and DCLs will include appropriate `use role <secadm>|<dbadm>` statements.
+  - `<secadm>` is security administrator ID for an environment and controls permissions
+  - `<dbadm>` is resource owner and owns the created objects
 
 ## `imports`
 
@@ -56,7 +58,6 @@ imports:
       - DBA
       - DEVLOPER
 ```
-### imported share
 An imported share is a YAML/JSON object that has following attributes:
 
 - **`provider`**: provider account name
@@ -107,7 +108,7 @@ A database is a YAML/JSON object that has following attributes:
 - `transient`: `true` if this is a transient database
 - `comment`: comment that'll be part of the generated DDL
 - `schemas`: A YAML/JSON list containing one or more schema YAML/JSON objects
-- `...`: Any other attributes are generated as part of the DDL
+- `...`: Any other attributes are passed through and become part of the DDL
 
 ### schema
 A schema is a YAML/JSON object that defines a database schema and has following attributes:
@@ -116,7 +117,7 @@ A schema is a YAML/JSON object that defines a database schema and has following
 - `managed`: `true` if this is a managed schema
 - `comment`: comment that'll be part of the generated DDL
 - `acc_roles`: A YAML/JSON object containing access role definitions to create
-- `...`: Any other attributes are generated as part of the DDL
+- `...`: Any other attributes are passed through and become part of the DDL
 
 ## `warehouses`
 
@@ -125,35 +126,33 @@ A schema is a YAML/JSON object that defines a database schema and has following
 **Example**
 
 ```yaml
-LOAD: &wh_defaults
-  warehouse_size: SMALL
-  initially_suspended: true
-  auto_suspend: 300
-  auto_resume: true
-  acc_roles:
-    R:
-      warehouse: [usage]
-    RW:
-      role: [R]
-      warehouse: [operate]
-    RWC:
-      role: [RW]
-      warehouse: [monitor, modify]
-
-ETL:
-  <<: *wh_defaults
-  warehouse_size: X-LARGE
+warehouses:
+  LOAD: &wh_defaults
+    warehouse_size: SMALL
+    initially_suspended: true
+    auto_suspend: 300
+    auto_resume: true
+    acc_roles:
+      R:
+        warehouse: [usage]
+      RW:
+        role: [R]
+        warehouse: [operate]
+      RWC:
+        role: [RW]
+        warehouse: [monitor, modify]
+  ETL:
+    <<: *wh_defaults
+    warehouse_size: X-LARGE
 ```
 
-### warehouse
-
 A warehouse is a YAML/JSON object with following attributes:
 - `comment`: comment that'll be part of the generated DDL
 - `acc_roles`: A YAML/JSON object containing access role definitions to create
-- `...`: Any other attributes are generated as part of the DDL
+- `...`: Any other attributes are passed through and become part of the DDL
 
 ## access roles
-An access role is created for either a schema or a warehouse. An access role is specified as a YAML/JSON object with access role name as key and attribute being another YAML/JSON object that encodes a list of permissions for each database object type.
+An access role is created for each schema or a warehouse. An access role is specified as a YAML/JSON object with access role name as key and attribute being another YAML/JSON object that encodes a list of permissions for each database object type.
 
 **Example**
 
@@ -168,35 +167,56 @@ RW:
   table: [insert, update, truncate, delete]
 ```
 
+The above example when specified for a schema will
+- create two database roles, corresponding to `R` and `RW`
+- each access role specifies object type and permissions mapping
+- permissions are list of SQL privileges
+
 ## `roles`
-A YAML/JSON object containing one or more *functional role* names and their definitions
+A YAML/JSON object containing one or more *functional role* names and their properties
 
-### functional role
+### functional roles
 
 A functional role has following attributes:
 - `comment`: comment that'll be part of the generated DDL
-- `acc_roles`: A YAML/JSON list containing *references* to a mix of schema or warehouse access roles
-- `env_acc_roles`: Allows specifying access role references per environment
-
-### access role reference
-An access role reference is a YAML/JSON object that has one of the following set of attributes:
+- `acc_roles`: A YAML/JSON list containing *references* to schema and/or warehouse access roles
+- `env_acc_roles`: Allows overriding access roles for specific environments
 
-**Option 1**
-- `database`: database name
-- `schema`: schema name
-- `acc`: access role name
+**Example**
 
-**Option 2**
-- `warehouse`: warehouse name
-- `acc`: access role name
+```yaml
+roles:
+  DEVELOPER:
+    comment: Developers
+    acc_roles:
+      EDW.CUSTOMER: R
+      BI.CUSTOMER: R
+      LOAD: R
+      ETL: R
+    env_acc_roles:
+      DEV: &dev_permissions
+        EDW.CUSTOMER: RWC
+        BI.CUSTOMER: RWC
+        LOAD: RW
+      QA: *dev_permissions
+```
 
 ## `users`
-A YAML/JSON object containing one or more *user* names and their definitions
+A YAML/JSON object that describes Snowflake user IDs
 
-### user
-A YAML/JSON object with following attributes:
+**Example**
+
+```yaml
+users:
+  JDOE:
+    comment: John Doe
+    roles:
+      - DBA
+      - SYSINFO
+```
+A *user* is an object mapping of name and its properties. Valid properties
 - `comment`: comment that'll be part of the generated DDL
 - `roles`: A YAML/JSON list containing names of the functional roles to be assigned to this user ID
 
 ## `apps`
-A YAML/JSON object, very similar to `users`, except the IDs are created per environment.
+Similar to `users` above except application IDs are created and are specific to an environment.