feat: Stream on external table resource

MIGRATION_GUIDE.md

@@ -9,12 +9,13 @@ across different versions.
 
 ## v0.96.0 ➞ v0.97.0
 
-### *(new feature)* snowflake_stream_on_table resource
+### *(new feature)* snowflake_stream_on_table, snowflake_stream_on_external_table resource
 
-To enhance clarity and functionality, the new resource `snowflake_stream_on_table` has been introduced to replace the previous `snowflake_stream`. Recognizing that the old resource carried multiple responsibilities within a single entity, we opted to divide it into more specialized resources.
+To enhance clarity and functionality, the new resources `snowflake_stream_on_table` and `snowflake_stream_on_external_table` have been introduced to replace the previous `snowflake_stream`. Recognizing that the old resource carried multiple responsibilities within a single entity, we opted to divide it into more specialized resources.
 The newly introduced resources are aligned with the latest Snowflake documentation at the time of implementation, and adhere to our [new conventions](#general-changes).
 This segregation was based on the object on which the stream is created. The mapping between SQL statements and the resources is the following:
 - `ON TABLE <table_name>` -> `snowflake_stream_on_table`
+- `ON EXTERNAL TABLE <external_table_name>` -> `snowflake_stream_on_external_table` (this was previously not supported)
 
 To use the new `stream_on_table`, change the old `stream` from
 ```terraform

docs/resources/stream_on_external_table.md

@@ -0,0 +1,164 @@
+---
+page_title: "snowflake_stream_on_external_table Resource - terraform-provider-snowflake"
+subcategory: ""
+description: |-
+  Resource used to manage streams on external tables. For more information, check stream documentation https://docs.snowflake.com/en/sql-reference/sql/create-stream.
+---
+
+!> **V1 release candidate** This resource was reworked and 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 resource if needed. Any errors reported will be resolved with a higher priority. We encourage checking this resource out before the V1 release. Please follow the [migration guide](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/MIGRATION_GUIDE.md#v0960--v0970) to use it.
+
+!> **Note about copy_grants** Fields like `external_table`, `insert_only`, `at`, `before` can not be ALTERed on Snowflake side (check [docs](https://docs.snowflake.com/en/sql-reference/sql/alter-stream)), and a change means recreation of the resource. ForceNew can not be used because it does not preserve grants from `copy_grants`. Beware that even though a change is marked as update, the resource is recreated.
+
+# snowflake_stream_on_external_table (Resource)
+
+Resource used to manage streams on external tables. For more information, check [stream documentation](https://docs.snowflake.com/en/sql-reference/sql/create-stream).
+
+## Example Usage
+
+```terraform
+resource "snowflake_external_table" "external_table" {
+  database    = "db"
+  schema      = "schema"
+  name        = "external_table"
+  comment     = "External table"
+  file_format = "TYPE = CSV FIELD_DELIMITER = '|'"
+  location    = "@stage/directory/"
+
+  column {
+    name = "id"
+    type = "int"
+  }
+
+  column {
+    name = "data"
+    type = "text"
+  }
+}
+
+# basic resource
+resource "snowflake_stream_on_external_table" "stream" {
+  name     = "stream"
+  schema   = "schema"
+  database = "database"
+
+  external_table = snowflake_external_table.external_table.fully_qualified_name
+}
+
+
+# resource with additional fields
+resource "snowflake_stream_on_external_table" "stream" {
+  name     = "stream"
+  schema   = "schema"
+  database = "database"
+
+  copy_grants    = true
+  external_table = snowflake_external_table.external_table.fully_qualified_name
+  insert_only    = "true"
+
+  at {
+    statement = "8e5d0ca9-005e-44e6-b858-a8f5b37c5726"
+  }
+
+  comment = "A stream."
+}
+```
+-> **Note** Instead of using fully_qualified_name, you can reference objects managed outside Terraform by constructing a correct ID, consult [identifiers guide](https://registry.terraform.io/providers/Snowflake-Labs/snowflake/latest/docs/guides/identifiers#new-computed-fully-qualified-name-field-in-resources).
+<!-- TODO(SNOW-1634854): include an example showing both methods-->
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `database` (String) The database in which to create the stream. Due to technical limitations (read more [here](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/docs/technical-documentation/identifiers_rework_design_decisions.md#known-limitations-and-identifier-recommendations)), avoid using the following characters: `|`, `.`, `(`, `)`, `"`
+- `external_table` (String) Specifies an identifier for the external table the stream will monitor. Due to technical limitations (read more [here](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/docs/technical-documentation/identifiers_rework_design_decisions.md#known-limitations-and-identifier-recommendations)), avoid using the following characters: `|`, `.`, `(`, `)`, `"`
+- `name` (String) Specifies the identifier for the stream; must be unique for the database and schema in which the stream is created. Due to technical limitations (read more [here](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/docs/technical-documentation/identifiers_rework_design_decisions.md#known-limitations-and-identifier-recommendations)), avoid using the following characters: `|`, `.`, `(`, `)`, `"`
+- `schema` (String) The schema in which to create the stream. Due to technical limitations (read more [here](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/docs/technical-documentation/identifiers_rework_design_decisions.md#known-limitations-and-identifier-recommendations)), avoid using the following characters: `|`, `.`, `(`, `)`, `"`
+
+### Optional
+
+- `at` (Block List, Max: 1) This field specifies that the request is inclusive of any changes made by a statement or transaction with a timestamp equal to the specified parameter. Due to Snowflake limitations, the provider does not detect external changes on this field. External changes for this field won't be detected. In case you want to apply external changes, you can re-create the resource manually using "terraform taint". (see [below for nested schema](#nestedblock--at))
+- `before` (Block List, Max: 1) This field specifies that the request refers to a point immediately preceding the specified parameter. This point in time is just before the statement, identified by its query ID, is completed.  Due to Snowflake limitations, the provider does not detect external changes on this field. External changes for this field won't be detected. In case you want to apply external changes, you can re-create the resource manually using "terraform taint". (see [below for nested schema](#nestedblock--before))
+- `comment` (String) Specifies a comment for the stream.
+- `copy_grants` (Boolean) Retains the access permissions from the original stream when a stream is recreated using the OR REPLACE clause. That is sometimes used when the provider detects changes for fields that can not be changed by ALTER. This value will not have any effect when creating a new stream.
+- `insert_only` (String) Specifies whether this is an insert-only stream. Available options are: "true" or "false". When the value is not set in the configuration the provider will put "default" there which means to use the Snowflake default for this value.
+
+### Read-Only
+
+- `describe_output` (List of Object) Outputs the result of `DESCRIBE STREAM` for the given stream. (see [below for nested schema](#nestedatt--describe_output))
+- `fully_qualified_name` (String) Fully qualified name of the resource. For more information, see [object name resolution](https://docs.snowflake.com/en/sql-reference/name-resolution).
+- `id` (String) The ID of this resource.
+- `show_output` (List of Object) Outputs the result of `SHOW STREAMS` for the given stream. (see [below for nested schema](#nestedatt--show_output))
+
+<a id="nestedblock--at"></a>
+### Nested Schema for `at`
+
+Optional:
+
+- `offset` (String) Specifies the difference in seconds from the current time to use for Time Travel, in the form -N where N can be an integer or arithmetic expression (e.g. -120 is 120 seconds, -30*60 is 1800 seconds or 30 minutes).
+- `statement` (String) Specifies the query ID of a statement to use as the reference point for Time Travel. This parameter supports any statement of one of the following types: DML (e.g. INSERT, UPDATE, DELETE), TCL (BEGIN, COMMIT transaction), SELECT.
+- `stream` (String) Specifies the identifier (i.e. name) for an existing stream on the queried table or view. The current offset in the stream is used as the AT point in time for returning change data for the source object.
+- `timestamp` (String) Specifies an exact date and time to use for Time Travel. The value must be explicitly cast to a TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ, or TIMESTAMP_TZ data type.
+
+
+<a id="nestedblock--before"></a>
+### Nested Schema for `before`
+
+Optional:
+
+- `offset` (String) Specifies the difference in seconds from the current time to use for Time Travel, in the form -N where N can be an integer or arithmetic expression (e.g. -120 is 120 seconds, -30*60 is 1800 seconds or 30 minutes).
+- `statement` (String) Specifies the query ID of a statement to use as the reference point for Time Travel. This parameter supports any statement of one of the following types: DML (e.g. INSERT, UPDATE, DELETE), TCL (BEGIN, COMMIT transaction), SELECT.
+- `stream` (String) Specifies the identifier (i.e. name) for an existing stream on the queried table or view. The current offset in the stream is used as the AT point in time for returning change data for the source object.
+- `timestamp` (String) Specifies an exact date and time to use for Time Travel. The value must be explicitly cast to a TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ, or TIMESTAMP_TZ data type.
+
+
+<a id="nestedatt--describe_output"></a>
+### Nested Schema for `describe_output`
+
+Read-Only:
+
+- `base_tables` (List of String)
+- `comment` (String)
+- `created_on` (String)
+- `database_name` (String)
+- `invalid_reason` (String)
+- `mode` (String)
+- `name` (String)
+- `owner` (String)
+- `owner_role_type` (String)
+- `schema_name` (String)
+- `source_type` (String)
+- `stale` (String)
+- `stale_after` (String)
+- `table_name` (String)
+- `type` (String)
+
+
+<a id="nestedatt--show_output"></a>
+### Nested Schema for `show_output`
+
+Read-Only:
+
+- `base_tables` (List of String)
+- `comment` (String)
+- `created_on` (String)
+- `database_name` (String)
+- `invalid_reason` (String)
+- `mode` (String)
+- `name` (String)
+- `owner` (String)
+- `owner_role_type` (String)
+- `schema_name` (String)
+- `source_type` (String)
+- `stale` (String)
+- `stale_after` (String)
+- `table_name` (String)
+- `type` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+terraform import snowflake_stream_on_external_table.example '"<database_name>"."<schema_name>"."<stream_name>"'
+```

docs/resources/stream_on_table.md

@@ -7,6 +7,8 @@ description: |-
 
 !> **V1 release candidate** This resource was reworked and 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 resource if needed. Any errors reported will be resolved with a higher priority. We encourage checking this resource out before the V1 release. Please follow the [migration guide](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/MIGRATION_GUIDE.md#v0960--v0970) to use it.
 
+!> **Note about copy_grants** Fields like `table`, `append_only`, `at`, `before`, `show_initial_rows` can not be ALTERed on Snowflake side (check [docs](https://docs.snowflake.com/en/sql-reference/sql/alter-stream)), and a change means recreation of the resource. ForceNew can not be used because it does not preserve grants from `copy_grants`. Beware that even though a change is marked as update, the resource is recreated.
+
 # snowflake_stream_on_table (Resource)
 
 Resource used to manage streams on tables. For more information, check [stream documentation](https://docs.snowflake.com/en/sql-reference/sql/create-stream).
@@ -63,7 +65,7 @@ resource "snowflake_stream_on_table" "stream" {
 - `at` (Block List, Max: 1) This field specifies that the request is inclusive of any changes made by a statement or transaction with a timestamp equal to the specified parameter. Due to Snowflake limitations, the provider does not detect external changes on this field. External changes for this field won't be detected. In case you want to apply external changes, you can re-create the resource manually using "terraform taint". (see [below for nested schema](#nestedblock--at))
 - `before` (Block List, Max: 1) This field specifies that the request refers to a point immediately preceding the specified parameter. This point in time is just before the statement, identified by its query ID, is completed.  Due to Snowflake limitations, the provider does not detect external changes on this field. External changes for this field won't be detected. In case you want to apply external changes, you can re-create the resource manually using "terraform taint". (see [below for nested schema](#nestedblock--before))
 - `comment` (String) Specifies a comment for the stream.
-- `copy_grants` (Boolean) Retains the access permissions from the original stream when a new stream is created using the OR REPLACE clause. Use only if the resource is already managed by Terraform. Otherwise, this field is skipped.
+- `copy_grants` (Boolean) Retains the access permissions from the original stream when a stream is recreated using the OR REPLACE clause. That is sometimes used when the provider detects changes for fields that can not be changed by ALTER. This value will not have any effect when creating a new stream.
 - `show_initial_rows` (String) Specifies whether to return all existing rows in the source table as row inserts the first time the stream is consumed. Available options are: "true" or "false". When the value is not set in the configuration the provider will put "default" there which means to use the Snowflake default for this value. External changes for this field won't be detected. In case you want to apply external changes, you can re-create the resource manually using "terraform taint".
 
 ### Read-Only

examples/resources/snowflake_stream_on_external_table/import.sh

@@ -0,0 +1 @@
+terraform import snowflake_stream_on_external_table.example '"<database_name>"."<schema_name>"."<stream_name>"'

examples/resources/snowflake_stream_on_external_table/resource.tf

@@ -0,0 +1,45 @@
+resource "snowflake_external_table" "external_table" {
+  database    = "db"
+  schema      = "schema"
+  name        = "external_table"
+  comment     = "External table"
+  file_format = "TYPE = CSV FIELD_DELIMITER = '|'"
+  location    = "@stage/directory/"
+
+  column {
+    name = "id"
+    type = "int"
+  }
+
+  column {
+    name = "data"
+    type = "text"
+  }
+}
+
+# basic resource
+resource "snowflake_stream_on_external_table" "stream" {
+  name     = "stream"
+  schema   = "schema"
+  database = "database"
+
+  external_table = snowflake_external_table.external_table.fully_qualified_name
+}
+
+
+# resource with additional fields
+resource "snowflake_stream_on_external_table" "stream" {
+  name     = "stream"
+  schema   = "schema"
+  database = "database"
+
+  copy_grants    = true
+  external_table = snowflake_external_table.external_table.fully_qualified_name
+  insert_only    = "true"
+
+  at {
+    statement = "8e5d0ca9-005e-44e6-b858-a8f5b37c5726"
+  }
+
+  comment = "A stream."
+}

pkg/acceptance/bettertestspoc/assert/resourceassert/gen/resource_schema_def.go

@@ -53,4 +53,8 @@ var allResourceSchemaDefs = []ResourceSchemaDef{
 		name:   "StreamOnTable",
 		schema: resources.StreamOnTable().Schema,
 	},
+	{
+		name:   "StreamOnExternalTable",
+		schema: resources.StreamOnExternalTable().Schema,
+	},
 }