feat: Docs, test, and missing parameter (#3280)

- Update docs
- Update migration guide
- Add execute as
- change execute as SDK
- Add tests to procedures
- Add examples and import instructions
- Describe limitations
- Deprecate old function and procedure

MIGRATION_GUIDE.md

@@ -9,6 +9,40 @@ across different versions.
 
 ## v0.99.0 ➞ v0.100.0
 
+### *(preview feature/deprecation)* Function and procedure resources
+
+`snowflake_function` is now deprecated in favor of 5 new preview resources:
+
+- `snowflake_function_java`
+- `snowflake_function_javascript`
+- `snowflake_function_python`
+- `snowflake_function_scala`
+- `snowflake_function_sql`
+
+It will be removed with the v1 release. Please check the docs for the new resources and adjust your configuration files.
+For no downtime migration, follow our [guide](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/docs/technical-documentation/resource_migration.md).
+
+The new resources are more aligned with current features like:
+- external access integrations support
+- secrets support
+- argument default values
+
+`snowflake_procedure` is now deprecated in favor of 5 new preview resources:
+
+- `snowflake_procedure_java`
+- `snowflake_procedure_javascript`
+- `snowflake_procedure_python`
+- `snowflake_procedure_scala`
+- `snowflake_procedure_sql`
+
+It will be removed with the v1 release. Please check the docs for the new resources and adjust your configuration files.
+For no downtime migration, follow our [guide](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/docs/technical-documentation/resource_migration.md).
+
+The new resources are more aligned with current features like:
+- external access integrations support
+- secrets support
+- argument default values
+
 ### *(new feature)* Account role data source
 Added a new `snowflake_account_roles` data source for account roles. Now it reflects It's based on `snowflake_roles` data source.
 `account_roles` field now organizes output of show under `show_output` field.

docs/index.md

@@ -362,7 +362,9 @@ provider "snowflake" {
 ## Currently deprecated resources
 
 - [snowflake_database_old](./docs/resources/database_old)
+- [snowflake_function](./docs/resources/function)
 - [snowflake_oauth_integration](./docs/resources/oauth_integration)
+- [snowflake_procedure](./docs/resources/procedure)
 - [snowflake_role](./docs/resources/role) - use [snowflake_account_role](./docs/resources/account_role) instead
 - [snowflake_saml_integration](./docs/resources/saml_integration) - use [snowflake_saml2_integration](./docs/resources/saml2_integration) instead
 - [snowflake_stream](./docs/resources/stream)

docs/resources/function.md

@@ -7,7 +7,7 @@ description: |-
 
 # snowflake_function (Resource)
 
-
+~> **Deprecation** This resource is deprecated and will be removed in a future major version release. Please use snowflake_function_java, snowflake_function_javascript, snowflake_function_python, snowflake_function_scala, and snowflake_function_sql instead. <deprecation>
 
 ## Example Usage
 

docs/resources/function_java.md

@@ -5,11 +5,44 @@ description: |-
   Resource used to manage java function objects. For more information, check function documentation https://docs.snowflake.com/en/sql-reference/sql/create-function.
 ---
 
+-> **Note** External changes to `is_secure`, `return_results_behavior`, and `null_input_behavior` are not currently supported. They will be handled in the following versions of the provider which may still affect this resource.
+
+-> **Note** `COPY GRANTS` and `OR REPLACE` are not currently supported.
+
+-> **Note** `RETURN... [[ NOT ] NULL]` is not currently supported. It will be improved in the following versions of the provider which may still affect this resource.
+
+-> **Note** Use of return type `TABLE` is currently limited. It will be improved in the following versions of the provider which may still affect this resource.
+
+-> **Note** Snowflake is not returning full data type information for arguments which may lead to unexpected plan outputs. Diff suppression for such cases will be improved.
+
+-> **Note** Snowflake is not returning the default values for arguments so argument's `arg_default_value` external changes cannot be tracked.
+
+-> **Note** Limit the use of special characters (`.`, `'`, `/`, `"`, `(`, `)`, `[`, `]`, `{`, `}`, ` `) in argument names, stage ids, and secret ids. It's best to limit to only alphanumeric and underscores. There is a lot of parsing of SHOW/DESCRIBE outputs involved and using special characters may limit the possibility to achieve the correct results.
+
+~> **Required warehouse** This resource may require active warehouse. Please, make sure you have either set a DEFAULT_WAREHOUSE for the user, or specified a warehouse in the provider configuration.
+
 # snowflake_function_java (Resource)
 
 Resource used to manage java function objects. For more information, check [function documentation](https://docs.snowflake.com/en/sql-reference/sql/create-function).
 
-
+## Example Usage
+
+```terraform
+resource "snowflake_function_java" "w" {
+  database = "Database"
+  schema   = "Schema"
+  name     = "Name"
+  arguments {
+    arg_data_type = "VARCHAR(100)"
+    arg_name      = "x"
+  }
+  return_type         = "VARCHAR(100)"
+  handler             = "TestFunc.echoVarchar"
+  function_definition = "\n\tclass TestFunc {\n\t\tpublic static String echoVarchar(String x) {\n\t\t\treturn x;\n\t\t}\n\t}\n"
+}
+```
+-> **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
@@ -173,3 +206,14 @@ Read-Only:
 - `schema_name` (String)
 - `secrets` (String)
 - `valid_for_clustering` (Boolean)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+terraform import snowflake_function_java.example '"<database_name>"."<schema_name>"."<function_name>"(varchar, varchar, varchar)'
+```
+
+Note: Snowflake is not returning all information needed to populate the state correctly after import (e.g. data types with attributes like NUMBER(32, 10) are returned as NUMBER, default values for arguments are not returned at all).
+Also, `ALTER` for functions is very limited so most of the attributes on this resource are marked as force new. Because of that, in multiple situations plan won't be empty after importing and manual state operations may be required.

docs/resources/function_javascript.md

@@ -5,11 +5,46 @@ description: |-
   Resource used to manage javascript function objects. For more information, check function documentation https://docs.snowflake.com/en/sql-reference/sql/create-function.
 ---
 
+-> **Note** External changes to `is_secure`, `return_results_behavior`, and `null_input_behavior` are not currently supported. They will be handled in the following versions of the provider which may still affect this resource.
+
+-> **Note** `COPY GRANTS` and `OR REPLACE` are not currently supported.
+
+-> **Note** `RETURN... [[ NOT ] NULL]` is not currently supported. It will be improved in the following versions of the provider which may still affect this resource.
+
+-> **Note** Use of return type `TABLE` is currently limited. It will be improved in the following versions of the provider which may still affect this resource.
+
+-> **Note** Snowflake is not returning full data type information for arguments which may lead to unexpected plan outputs. Diff suppression for such cases will be improved.
+
+-> **Note** Snowflake is not returning the default values for arguments so argument's `arg_default_value` external changes cannot be tracked.
+
+-> **Note** Limit the use of special characters (`.`, `'`, `/`, `"`, `(`, `)`, `[`, `]`, `{`, `}`, ` `) in argument names, stage ids, and secret ids. It's best to limit to only alphanumeric and underscores. There is a lot of parsing of SHOW/DESCRIBE outputs involved and using special characters may limit the possibility to achieve the correct results.
+
+~> **Required warehouse** This resource may require active warehouse. Please, make sure you have either set a DEFAULT_WAREHOUSE for the user, or specified a warehouse in the provider configuration.
+
 # snowflake_function_javascript (Resource)
 
 Resource used to manage javascript function objects. For more information, check [function documentation](https://docs.snowflake.com/en/sql-reference/sql/create-function).
 
-
+## Example Usage
+
+```terraform
+# Minimal
+resource "snowflake_function_javascript" "minimal" {
+  database = snowflake_database.test.name
+  schema   = snowflake_schema.test.name
+  name     = "my_javascript_function"
+  arguments {
+    arg_data_type = "VARIANT"
+    arg_name      = "x"
+  }
+  function_definition = <<EOF
+    return x;
+  EOF
+  return_type         = "VARIANT"
+}
+```
+-> **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
@@ -139,3 +174,14 @@ Read-Only:
 - `schema_name` (String)
 - `secrets` (String)
 - `valid_for_clustering` (Boolean)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+terraform import snowflake_function_javascript.example '"<database_name>"."<schema_name>"."<function_name>"(varchar, varchar, varchar)'
+```
+
+Note: Snowflake is not returning all information needed to populate the state correctly after import (e.g. data types with attributes like NUMBER(32, 10) are returned as NUMBER, default values for arguments are not returned at all).
+Also, `ALTER` for functions is very limited so most of the attributes on this resource are marked as force new. Because of that, in multiple situations plan won't be empty after importing and manual state operations may be required.

docs/resources/function_python.md

@@ -5,11 +5,51 @@ description: |-
   Resource used to manage python function objects. For more information, check function documentation https://docs.snowflake.com/en/sql-reference/sql/create-function.
 ---
 
+-> **Note** External changes to `is_secure`, `return_results_behavior`, and `null_input_behavior` are not currently supported. They will be handled in the following versions of the provider which may still affect this resource.
+
+-> **Note** `COPY GRANTS` and `OR REPLACE` are not currently supported.
+
+-> **Note** `RETURN... [[ NOT ] NULL]` is not currently supported. It will be improved in the following versions of the provider which may still affect this resource.
+
+-> **Note** `is_aggregate` is not currently supported. It will be improved in the following versions of the provider which may still affect this resource.
+
+-> **Note** Use of return type `TABLE` is currently limited. It will be improved in the following versions of the provider which may still affect this resource.
+
+-> **Note** Snowflake is not returning full data type information for arguments which may lead to unexpected plan outputs. Diff suppression for such cases will be improved.
+
+-> **Note** Snowflake is not returning the default values for arguments so argument's `arg_default_value` external changes cannot be tracked.
+
+-> **Note** Limit the use of special characters (`.`, `'`, `/`, `"`, `(`, `)`, `[`, `]`, `{`, `}`, ` `) in argument names, stage ids, and secret ids. It's best to limit to only alphanumeric and underscores. There is a lot of parsing of SHOW/DESCRIBE outputs involved and using special characters may limit the possibility to achieve the correct results.
+
+~> **Required warehouse** This resource may require active warehouse. Please, make sure you have either set a DEFAULT_WAREHOUSE for the user, or specified a warehouse in the provider configuration.
+
 # snowflake_function_python (Resource)
 
 Resource used to manage python function objects. For more information, check [function documentation](https://docs.snowflake.com/en/sql-reference/sql/create-function).
 
-
+## Example Usage
+
+```terraform
+# Minimal
+resource "snowflake_function_python" "minimal" {
+  database        = snowflake_database.test.name
+  schema          = snowflake_schema.test.name
+  name            = "my_function_function"
+  runtime_version = "3.8"
+  arguments {
+    arg_data_type = "NUMBER(36, 2)"
+    arg_name      = "x"
+  }
+  function_definition = <<EOF
+    def some_function(x):
+      return x
+  EOF
+  handler             = "some_function"
+  return_type         = "NUMBER(36, 2)"
+}
+```
+-> **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
@@ -164,3 +204,14 @@ Read-Only:
 - `schema_name` (String)
 - `secrets` (String)
 - `valid_for_clustering` (Boolean)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+terraform import snowflake_function_python.example '"<database_name>"."<schema_name>"."<function_name>"(varchar, varchar, varchar)'
+```
+
+Note: Snowflake is not returning all information needed to populate the state correctly after import (e.g. data types with attributes like NUMBER(32, 10) are returned as NUMBER, default values for arguments are not returned at all).
+Also, `ALTER` for functions is very limited so most of the attributes on this resource are marked as force new. Because of that, in multiple situations plan won't be empty after importing and manual state operations may be required.

docs/resources/function_scala.md

@@ -5,11 +5,97 @@ description: |-
   Resource used to manage scala function objects. For more information, check function documentation https://docs.snowflake.com/en/sql-reference/sql/create-function.
 ---
 
+-> **Note** External changes to `is_secure`, `return_results_behavior`, and `null_input_behavior` are not currently supported. They will be handled in the following versions of the provider which may still affect this resource.
+
+-> **Note** `COPY GRANTS` and `OR REPLACE` are not currently supported.
+
+-> **Note** `RETURN... [[ NOT ] NULL]` is not currently supported. It will be improved in the following versions of the provider which may still affect this resource.
+
+-> **Note** Snowflake is not returning full data type information for arguments which may lead to unexpected plan outputs. Diff suppression for such cases will be improved.
+
+-> **Note** Snowflake is not returning the default values for arguments so argument's `arg_default_value` external changes cannot be tracked.
+
+-> **Note** Limit the use of special characters (`.`, `'`, `/`, `"`, `(`, `)`, `[`, `]`, `{`, `}`, ` `) in argument names, stage ids, and secret ids. It's best to limit to only alphanumeric and underscores. There is a lot of parsing of SHOW/DESCRIBE outputs involved and using special characters may limit the possibility to achieve the correct results.
+
+~> **Required warehouse** This resource may require active warehouse. Please, make sure you have either set a DEFAULT_WAREHOUSE for the user, or specified a warehouse in the provider configuration.
+
 # snowflake_function_scala (Resource)
 
 Resource used to manage scala function objects. For more information, check [function documentation](https://docs.snowflake.com/en/sql-reference/sql/create-function).
 
-
+## Example Usage
+
+```terraform
+# Minimal
+resource "snowflake_function_scala" "minimal" {
+  database = snowflake_database.test.name
+  schema   = snowflake_schema.test.name
+  name     = "my_scala_function"
+  arguments {
+    arg_data_type = "VARCHAR(100)"
+    arg_name      = "x"
+  }
+  function_definition = <<EOF
+  class TestFunc {
+    def echoVarchar(x : String): String = {
+      return x
+    }
+  }
+  EOF
+  runtime_version     = "2.12"
+  handler             = "TestFunc.echoVarchar"
+  return_type         = "VARCHAR(100)"
+}
+
+# Complete
+resource "snowflake_function_scala" "complete" {
+  database  = snowflake_database.test.name
+  schema    = snowflake_schema.test.name
+  name      = "my_scala_function"
+  is_secure = "false"
+  arguments {
+    arg_data_type = "VARCHAR(100)"
+    arg_name      = "x"
+  }
+  comment                      = "some comment"
+  external_access_integrations = ["external_access_integration_name", "external_access_integration_name_2"]
+  function_definition          = <<EOF
+  class TestFunc {
+    def echoVarchar(x : String): String = {
+      return x
+    }
+  }
+  EOF
+  handler                      = "TestFunc.echoVarchar"
+  null_input_behavior          = "CALLED ON NULL INPUT"
+  return_results_behavior      = "VOLATILE"
+  return_type                  = "VARCHAR(100)"
+  imports {
+    path_on_stage  = "jar_name.jar"
+    stage_location = "~"
+  }
+  imports {
+    path_on_stage  = "second_jar_name.jar"
+    stage_location = "~"
+  }
+  packages        = ["com.snowflake:snowpark:1.14.0", "com.snowflake:telemetry:0.1.0"]
+  runtime_version = "2.12"
+  secrets {
+    secret_id            = snowflake_secret_with_authorization_code_grant.one.fully_qualified_name
+    secret_variable_name = "abc"
+  }
+  secrets {
+    secret_id            = snowflake_secret_with_authorization_code_grant.two.fully_qualified_name
+    secret_variable_name = "def"
+  }
+  target_path {
+    path_on_stage  = "target_jar_name.jar"
+    stage_location = snowflake_stage.test.fully_qualified_name
+  }
+}
+```
+-> **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
@@ -173,3 +259,14 @@ Read-Only:
 - `schema_name` (String)
 - `secrets` (String)
 - `valid_for_clustering` (Boolean)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+terraform import snowflake_function_scala.example '"<database_name>"."<schema_name>"."<function_name>"(varchar, varchar, varchar)'
+```
+
+Note: Snowflake is not returning all information needed to populate the state correctly after import (e.g. data types with attributes like NUMBER(32, 10) are returned as NUMBER, default values for arguments are not returned at all).
+Also, `ALTER` for functions is very limited so most of the attributes on this resource are marked as force new. Because of that, in multiple situations plan won't be empty after importing and manual state operations may be required.