From 0641649b67e467ed678e081e569f4f5b6d769aa4 Mon Sep 17 00:00:00 2001 From: Joel Labes Date: Tue, 17 Dec 2024 18:24:26 +1300 Subject: [PATCH 1/5] Update grants to include revocation examples --- .../docs/reference/resource-configs/grants.md | 69 ++++++++++++++++++- 1 file changed, 66 insertions(+), 3 deletions(-) diff --git a/website/docs/reference/resource-configs/grants.md b/website/docs/reference/resource-configs/grants.md index 99b61ef2413..9e9559a1b63 100644 --- a/website/docs/reference/resource-configs/grants.md +++ b/website/docs/reference/resource-configs/grants.md @@ -11,12 +11,12 @@ The grant resource configs enable you to apply permissions at build time to a sp dbt aims to use the most efficient approach when updating grants, which varies based on the adapter you're using, and whether dbt is replacing or updating an object that already exists. You can always check the debug logs for the full set of grant and revoke statements that dbt runs. -dbt encourages you to use grants as resource configs whenever possible. In versions prior to Core v1.2, you were limited to using hooks for grants. Occasionally, you still might need to write grants statements manually and run them using hooks. For example, hooks may be appropriate if you want to: +You should define grants as resource configs whenever possible, but you might occasionally need to write grants statements manually and run them using hooks. For example, hooks may be appropriate if you want to: -* Apply grants in a more complex or custom manner, beyond what the built-in grants capability can provide. * Apply grants on other database objects besides views and tables. -* Take advantage of more-advanced permission capabilities offered by your data platform, for which dbt does not (yet!) offer out-of-the-box support using resource configuration. * Create more granular row- and column-level access, use masking policies, or apply future grants. +* Take advantage of more-advanced permission capabilities offered by your data platform, for which dbt does not offer out-of-the-box support using resource configuration. +* Apply grants in a more complex or custom manner, beyond what the built-in grants capability can provide. For more information on hooks, see [Hooks & operations](/docs/build/hooks-operations). @@ -154,6 +154,69 @@ Now, the model will grant select to `user_a`, `user_b`, AND `user_c`! - This use of `+`, controlling clobber vs. add merge behavior, is distinct from the use of `+` in `dbt_project.yml` (shown in the example above) for defining configs with dictionary values. For more information, see [the plus prefix](https://docs.getdbt.com/reference/resource-configs/plus-prefix). - `grants` is the first config to support a `+` prefix for controlling config merge behavior. Currently, it's the only one. If it proves useful, we may extend this capability to new and existing configs in the future. +## Revoking grants + +dbt will only modify grants on a node (including revocation) when a `grants` configuration is attached to that node. For example, imagine you had originally specified the following grants in `dbt_project.yml`: + + + +```yml +models: + +grants: + select: ['user_a', 'user_b'] +``` + + + +If you delete the `+grants` section altogether, dbt will assume you no longer want it to manage grants, and will not change anything. To have dbt revoke all existing grants from a node, provide an empty list of grantees instead. + + + + + + + ```yml + models: + +grants: + select: ['user_b'] + ``` + + + + + + + + ```yml + models: + +grants: + select: [] + ``` + + + + + + + + ```yml + models: + + # this section intentionally left blank + ``` + + + + + + ## General examples You can grant each permission to a single grantee, or a set of multiple grantees. In this example, we're granting `select` on this model to just `bi_user`, so that it can be queried in our Business Intelligence (BI) tool. From f5ebf0a47288cba62018411a9c5111c6c0bfcdc7 Mon Sep 17 00:00:00 2001 From: Joel Labes Date: Tue, 17 Dec 2024 18:26:48 +1300 Subject: [PATCH 2/5] link to hooks --- website/docs/reference/resource-configs/grants.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/reference/resource-configs/grants.md b/website/docs/reference/resource-configs/grants.md index 9e9559a1b63..5301b8a30fd 100644 --- a/website/docs/reference/resource-configs/grants.md +++ b/website/docs/reference/resource-configs/grants.md @@ -11,7 +11,7 @@ The grant resource configs enable you to apply permissions at build time to a sp dbt aims to use the most efficient approach when updating grants, which varies based on the adapter you're using, and whether dbt is replacing or updating an object that already exists. You can always check the debug logs for the full set of grant and revoke statements that dbt runs. -You should define grants as resource configs whenever possible, but you might occasionally need to write grants statements manually and run them using hooks. For example, hooks may be appropriate if you want to: +You should define grants as resource configs whenever possible, but you might occasionally need to write grants statements manually and run them using [hooks](/docs/build/hooks-operations). For example, hooks may be appropriate if you want to: * Apply grants on other database objects besides views and tables. * Create more granular row- and column-level access, use masking policies, or apply future grants. @@ -208,7 +208,7 @@ If you delete the `+grants` section altogether, dbt will assume you no longer wa ```yml models: - + # this section intentionally left blank ``` From 133b35714f5309139d81cdd7c261a3cc53e6540d Mon Sep 17 00:00:00 2001 From: Joel Labes Date: Tue, 17 Dec 2024 20:48:35 +1300 Subject: [PATCH 3/5] Add docs for conditional grants --- .../docs/reference/resource-configs/grants.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/website/docs/reference/resource-configs/grants.md b/website/docs/reference/resource-configs/grants.md index 5301b8a30fd..be9918043f6 100644 --- a/website/docs/reference/resource-configs/grants.md +++ b/website/docs/reference/resource-configs/grants.md @@ -154,6 +154,20 @@ Now, the model will grant select to `user_a`, `user_b`, AND `user_c`! - This use of `+`, controlling clobber vs. add merge behavior, is distinct from the use of `+` in `dbt_project.yml` (shown in the example above) for defining configs with dictionary values. For more information, see [the plus prefix](https://docs.getdbt.com/reference/resource-configs/plus-prefix). - `grants` is the first config to support a `+` prefix for controlling config merge behavior. Currently, it's the only one. If it proves useful, we may extend this capability to new and existing configs in the future. +### Conditional grants + +Like any other config, you can use Jinja to vary the grants in different contexts. For example, you might grant different permissions in prod than dev: + + + +```yml +models: + +grants: + select: "{{ ['user_a', 'user_b'] if target.name == 'prod' else ['user_c'] }}" +``` + + + ## Revoking grants dbt will only modify grants on a node (including revocation) when a `grants` configuration is attached to that node. For example, imagine you had originally specified the following grants in `dbt_project.yml`: @@ -312,7 +326,7 @@ models:
-* Granting to / revoking from is only fully supported for Redshift users (not [groups](https://docs.aws.amazon.com/redshift/latest/dg/r_Groups.html) or [roles](https://docs.aws.amazon.com/redshift/latest/dg/r_roles-managing.html)). +* Granting to / revoking from is only fully supported for Redshift users (not [groups](https://docs.aws.amazon.com/redshift/latest/dg/r_Groups.html) or [roles](https://docs.aws.amazon.com/redshift/latest/dg/r_roles-managing.html)). See [dbt-redshift#415](https://github.com/dbt-labs/dbt-redshift/issues/415) for the corresponding issue.
From cebbc272e72383bcf629c3c372995d55f777635f Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Wed, 18 Dec 2024 00:14:57 -0500 Subject: [PATCH 4/5] Update website/docs/reference/resource-configs/grants.md --- website/docs/reference/resource-configs/grants.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/resource-configs/grants.md b/website/docs/reference/resource-configs/grants.md index be9918043f6..15a920cbbe0 100644 --- a/website/docs/reference/resource-configs/grants.md +++ b/website/docs/reference/resource-configs/grants.md @@ -15,7 +15,7 @@ You should define grants as resource configs whenever possible, but you might oc * Apply grants on other database objects besides views and tables. * Create more granular row- and column-level access, use masking policies, or apply future grants. -* Take advantage of more-advanced permission capabilities offered by your data platform, for which dbt does not offer out-of-the-box support using resource configuration. +* Take advantage of more advanced permission capabilities offered by your data platform, for which dbt does not offer out-of-the-box support using resource configuration. * Apply grants in a more complex or custom manner, beyond what the built-in grants capability can provide. For more information on hooks, see [Hooks & operations](/docs/build/hooks-operations). From feeeb7fe275354b04e15ac14b7a94516b2025a44 Mon Sep 17 00:00:00 2001 From: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> Date: Wed, 18 Dec 2024 00:26:21 -0500 Subject: [PATCH 5/5] Apply suggestions from code review Editorial changes --- website/docs/reference/resource-configs/grants.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/reference/resource-configs/grants.md b/website/docs/reference/resource-configs/grants.md index 15a920cbbe0..4b0cda26f52 100644 --- a/website/docs/reference/resource-configs/grants.md +++ b/website/docs/reference/resource-configs/grants.md @@ -170,7 +170,7 @@ models: ## Revoking grants -dbt will only modify grants on a node (including revocation) when a `grants` configuration is attached to that node. For example, imagine you had originally specified the following grants in `dbt_project.yml`: +dbt only modifies grants on a node (including revocation) when a `grants` configuration is attached to that node. For example, imagine you had originally specified the following grants in `dbt_project.yml`: @@ -182,7 +182,7 @@ models: -If you delete the `+grants` section altogether, dbt will assume you no longer want it to manage grants, and will not change anything. To have dbt revoke all existing grants from a node, provide an empty list of grantees instead. +If you delete the entire `+grants` section, dbt assumes you no longer want it to manage grants and doesn't change anything. To have dbt revoke all existing grants from a node, provide an empty list of grantees.