Merge branch 'v1-ready-remove-deprecated' into v1-ready-preview-resou…

…rces
Snowflake-Labs · Nov 25, 2024 · 311bfc1 · 311bfc1
2 parents 0c97cb9 + fb65fa3
commit 311bfc1
Show file tree

Hide file tree

Showing 89 changed files with 2,008 additions and 427 deletions.
diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md
@@ -39,6 +39,13 @@ Additionally, `JWT` value is no longer available for `authenticator` field in th
 
 ## v0.98.0 ➞ v0.99.0
 
+### *(new feature)* snowflake_tags datasource
+Added a new datasource enabling querying and filtering tags. Notes:
+- all results are stored in `tags` field.
+- `like` field enables tags filtering by name.
+- `in` field enables tags filtering by `account`, `database`, `schema`, `application` and `application_package`.
+- `SHOW TAGS` output is enclosed in `show_output` field inside `tags`.
+
 ### snowflake_tag_masking_policy_association deprecation
 `snowflake_tag_masking_policy_association` is now deprecated in favor of `snowflake_tag` with a new `masking_policy` field. It will be removed with the v1 release. Please adjust your configuration files.
 
@@ -125,7 +132,8 @@ We have added new fields to match the ones in [the driver](https://pkg.go.dev/gi
 To be more consistent with other configuration options, we have decided to add `driver_tracing` to the configuration schema. This value can also be configured by `SNOWFLAKE_DRIVER_TRACING` environmental variable and by `drivertracing` field in the TOML file. The previous `SF_TF_GOSNOWFLAKE_LOG_LEVEL` environmental variable is not supported now, and was removed from the provider.
 
 #### *(behavior change)* deprecated fields
-Because of new fields `account_name` and `organization_name`, `account` is now deprecated. It will be removed with the v1 release. Please adjust your configurations from
+Because of new fields `account_name` and `organization_name`, `account` is now deprecated. It will be removed with the v1 release.
+If you use Terraform configuration file, adjust it from
 ```terraform
 provider "snowflake" {
 	account = "ORGANIZATION-ACCOUNT"
@@ -140,6 +148,31 @@ provider "snowflake" {
 }
 ```
 
+If you use TOML configuration file, adjust it from
+```toml
+[default]
+	account = "ORGANIZATION-ACCOUNT"
+}
+```
+
+to
+```toml
+[default]
+	organizationname = "ORGANIZATION"
+	accountname    = "ACCOUNT"
+}
+```
+
+If you use environmental variables, adjust them from
+```bash
+SNOWFLAKE_ACCOUNT = "ORGANIZATION-ACCOUNT"
+```
+
+```bash
+SNOWFLAKE_ORGANIZATION_NAME = "ORGANIZATION"
+SNOWFLAKE_ACCOUNT_NAME = "ACCOUNT"
+```
+
 #### *(behavior change)* changed behavior of some fields
 For the fields that are not deprecated, we focused on improving validations and documentation. Also, we adjusted some fields to match our [driver's](https://github.com/snowflakedb/gosnowflake) defaults. Specifically:
 - Relaxed validations for enum fields like `protocol` and `authenticator`. Now, the case on such fields is ignored.

diff --git a/docs/data-sources/streams.md b/docs/data-sources/streams.md
@@ -14,9 +14,120 @@ Datasource used to get details of filtered streams. Filtering is aligned with th
 ## Example Usage
 
 ```terraform
-data "snowflake_streams" "current" {
-  database = "MYDB"
-  schema   = "MYSCHEMA"
+# Simple usage
+data "snowflake_streams" "simple" {
+}
+
+output "simple_output" {
+  value = data.snowflake_streams.simple.streams
+}
+
+# Filtering (like)
+data "snowflake_streams" "like" {
+  like = "stream-name"
+}
+
+output "like_output" {
+  value = data.snowflake_streams.like.streams
+}
+
+# Filtering by prefix (like)
+data "snowflake_streams" "like_prefix" {
+  like = "prefix%"
+}
+
+output "like_prefix_output" {
+  value = data.snowflake_streams.like_prefix.streams
+}
+
+# Filtering (limit)
+data "snowflake_streams" "limit" {
+  limit {
+    rows = 10
+    from = "prefix-"
+  }
+}
+
+output "limit_output" {
+  value = data.snowflake_streams.limit.streams
+}
+
+# Filtering (in)
+data "snowflake_streams" "in_account" {
+  in {
+    account = true
+  }
+}
+
+data "snowflake_streams" "in_database" {
+  in {
+    database = "<database_name>"
+  }
+}
+
+data "snowflake_streams" "in_schema" {
+  in {
+    schema = "<database_name>.<schema_name>"
+  }
+}
+
+data "snowflake_streams" "in_application" {
+  in {
+    application = "<application_name>"
+  }
+}
+
+data "snowflake_streams" "in_application_package" {
+  in {
+    application_package = "<application_package_name>"
+  }
+}
+
+output "in_output" {
+  value = {
+    "account" : data.snowflake_streams.in_account.streams,
+    "database" : data.snowflake_streams.in_database.streams,
+    "schema" : data.snowflake_streams.in_schema.streams,
+    "application" : data.snowflake_streams.in_application.streams,
+    "application_package" : data.snowflake_streams.in_application_package.streams,
+  }
+}
+
+output "in_output" {
+  value = data.snowflake_streams.in.streams
+}
+
+# Without additional data (to limit the number of calls make for every found stream)
+data "snowflake_streams" "only_show" {
+  # with_describe is turned on by default and it calls DESCRIBE STREAM for every stream found and attaches its output to streams.*.describe_output field
+  with_describe = false
+}
+
+output "only_show_output" {
+  value = data.snowflake_streams.only_show.streams
+}
+
+# Ensure the number of streams is equal to at least one element (with the use of postcondition)
+data "snowflake_streams" "assert_with_postcondition" {
+  like = "stream-name%"
+  lifecycle {
+    postcondition {
+      condition     = length(self.streams) > 0
+      error_message = "there should be at least one stream"
+    }
+  }
+}
+
+# Ensure the number of streams is equal to at exactly one element (with the use of check block)
+check "stream_check" {
+  data "snowflake_streams" "assert_with_check_block" {
+    like = "stream-name"
+  }
+
+  assert {
+    condition     = length(data.snowflake_streams.assert_with_check_block.streams) == 1
+    error_message = "streams filtered by '${data.snowflake_streams.assert_with_check_block.like}' returned ${length(data.snowflake_streams.assert_with_check_block.streams)} streams where one was expected"
+  }
 }
 ```
 

diff --git a/docs/data-sources/tags.md b/docs/data-sources/tags.md
@@ -0,0 +1,156 @@
+---
+page_title: "snowflake_tags Data Source - terraform-provider-snowflake"
+subcategory: ""
+description: |-
+  Datasource used to get details of filtered tags. Filtering is aligned with the current possibilities for SHOW TAGS https://docs.snowflake.com/en/sql-reference/sql/show-tags query. The results of SHOW are encapsulated in one output collection tags.
+---
+
+!> **V1 release candidate** This data source is a release candidate for the V1. We do not expect significant changes in it before the V1. We will welcome any feedback and adjust the data source if needed. Any errors reported will be resolved with a higher priority. We encourage checking this data source out before the V1 release. Please follow the [migration guide](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/MIGRATION_GUIDE.md#v0980--v0990) to use it.
+
+# snowflake_tags (Data Source)
+
+Datasource used to get details of filtered tags. Filtering is aligned with the current possibilities for [SHOW TAGS](https://docs.snowflake.com/en/sql-reference/sql/show-tags) query. The results of SHOW are encapsulated in one output collection `tags`.
+
+## Example Usage
+
+```terraform
+# Simple usage
+data "snowflake_tags" "simple" {
+}
+
+output "simple_output" {
+  value = data.snowflake_tags.simple.tags
+}
+
+# Filtering (like)
+data "snowflake_tags" "like" {
+  like = "tag-name"
+}
+
+output "like_output" {
+  value = data.snowflake_tags.like.tags
+}
+
+# Filtering by prefix (like)
+data "snowflake_tags" "like_prefix" {
+  like = "prefix%"
+}
+
+output "like_prefix_output" {
+  value = data.snowflake_tags.like_prefix.tags
+}
+
+# Filtering (in)
+data "snowflake_tags" "in_account" {
+  in {
+    account = true
+  }
+}
+
+data "snowflake_tags" "in_database" {
+  in {
+    database = "<database_name>"
+  }
+}
+
+data "snowflake_tags" "in_schema" {
+  in {
+    schema = "<database_name>.<schema_name>"
+  }
+}
+
+data "snowflake_tags" "in_application" {
+  in {
+    application = "<application_name>"
+  }
+}
+
+data "snowflake_tags" "in_application_package" {
+  in {
+    application_package = "<application_package_name>"
+  }
+}
+
+output "in_output" {
+  value = {
+    "account" : data.snowflake_tags.in_account.tags,
+    "database" : data.snowflake_tags.in_database.tags,
+    "schema" : data.snowflake_tags.in_schema.tags,
+    "application" : data.snowflake_tags.in_application.tags,
+    "application_package" : data.snowflake_tags.in_application_package.tags,
+  }
+}
+
+output "in_output" {
+  value = data.snowflake_tags.in.tags
+}
+
+# Ensure the number of tags is equal to at least one element (with the use of postcondition)
+data "snowflake_tags" "assert_with_postcondition" {
+  like = "tag-name%"
+  lifecycle {
+    postcondition {
+      condition     = length(self.tags) > 0
+      error_message = "there should be at least one tag"
+    }
+  }
+}
+
+# Ensure the number of tags is equal to at exactly one element (with the use of check block)
+check "tag_check" {
+  data "snowflake_tags" "assert_with_check_block" {
+    like = "tag-name"
+  }
+
+  assert {
+    condition     = length(data.snowflake_tags.assert_with_check_block.tags) == 1
+    error_message = "tags filtered by '${data.snowflake_tags.assert_with_check_block.like}' returned ${length(data.snowflake_tags.assert_with_check_block.tags)} tags where one was expected"
+  }
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Optional
+
+- `in` (Block List, Max: 1) IN clause to filter the list of objects (see [below for nested schema](#nestedblock--in))
+- `like` (String) Filters the output with **case-insensitive** pattern, with support for SQL wildcard characters (`%` and `_`).
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+- `tags` (List of Object) Holds the aggregated output of all tags details queries. (see [below for nested schema](#nestedatt--tags))
+
+<a id="nestedblock--in"></a>
+### Nested Schema for `in`
+
+Optional:
+
+- `account` (Boolean) Returns records for the entire account.
+- `application` (String) Returns records for the specified application.
+- `application_package` (String) Returns records for the specified application package.
+- `database` (String) Returns records for the current database in use or for a specified database.
+- `schema` (String) Returns records for the current schema in use or a specified schema. Use fully qualified name.
+
+
+<a id="nestedatt--tags"></a>
+### Nested Schema for `tags`
+
+Read-Only:
+
+- `show_output` (List of Object) (see [below for nested schema](#nestedobjatt--tags--show_output))
+
+<a id="nestedobjatt--tags--show_output"></a>
+### Nested Schema for `tags.show_output`
+
+Read-Only:
+
+- `allowed_values` (Set of String)
+- `comment` (String)
+- `created_on` (String)
+- `database_name` (String)
+- `name` (String)
+- `owner` (String)
+- `owner_role_type` (String)
+- `schema_name` (String)
diff --git a/docs/technical-documentation/resource_migration.md b/docs/technical-documentation/resource_migration.md
@@ -1,7 +1,7 @@
 
 # Resource migration
 
-Here's a guide on how to migrate deprecated resources to their new counter-parts before v1 release.
+Here's a guide on how to migrate deprecated resources to their new counter-parts.
 The migration can be done in two ways. Either you can remove old grant resources and replace them with new ones or perform
 more complicated migration, but without revoking any grant (no downtime migration). We'll focus on the second one as the first approach
 is pretty straight forward. As an example we'll take `snowflake_database_grant` to `snowflake_grant_privileges_to_account_role` migration with one privilege granted to two roles: