chore: Add annotation about fully_qualified_name and fix handling gra…

…nteeName (#3009)

<!-- Feel free to delete comments as you fill this in -->

<!-- summary of changes -->
- add a new guide for identifiers
- add a note about using object references if you don't manage
referenced objects
- fix a typo in one of the examples
- improve handling database role grants with a test for mixed case
## Test Plan
<!-- detail ways in which this PR has been tested or needs to be tested
-->
* [x] acceptance tests
<!-- add more below if you think they are relevant -->

MIGRATION_GUIDE.md

@@ -47,6 +47,8 @@ writing
 
 ```object_name = snowflake_table.fully_qualified_name```
 
+See more details in [identifiers guide](./docs/guides/identifiers.md#new-computed-fully-qualified-name-field-in-resources).
+
 See [example usage](https://registry.terraform.io/providers/Snowflake-Labs/snowflake/latest/docs/resources/grant_privileges_to_account_role).
 
 Some of the resources are excluded from this change:

docs/guides/identifiers.md

@@ -0,0 +1,25 @@
+---
+page_title: "Identifiers rework"
+subcategory: ""
+description: |-
+
+---
+# Identifiers rework
+
+## New computed fully qualified name field in resources
+
+With the combination of quotes, old parsing methods, and other factors, it was a struggle to specify the fully qualified name of an object needed (e.g. [#2164](https://github.com/Snowflake-Labs/terraform-provider-snowflake/issues/2164), [#2754](https://github.com/Snowflake-Labs/terraform-provider-snowflake/issues/2754)). Starting from version v0.95.0, every resource that represents an object in Snowflake (e.g. user, role), and not an association (e.g. grants) will have a new computed field named `fully_qualified_name`. With the new computed field, it will be much easier to use resources requiring fully qualified names, for examples of usage head over to the [documentation for granting privileges to account role](https://registry.terraform.io/providers/Snowflake-Labs/snowflake/latest/docs/resources/grant_privileges_to_account_role).
+
+For example, instead of writing
+
+```object_name = “\”${snowflake_table.database}\”.\”${snowflake_table.schema}\”.\”${snowflake_table.name}\””```
+
+now we can write
+
+```object_name = snowflake_table.fully_qualified_name```
+
+This is our recommended way of referencing other objects. However, if you don't manage table in Terraform, you can construct the proper id yourself like before: `"\"database_name\".\"schema_name\".\"table_name\""` Note that quotes are necessary for correct parsing of an identifier.
+
+This change was announced in v0.95.0 [migration guide](https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/MIGRATION_GUIDE.md#new-fully_qualified_name-field-in-the-resources).
+
+<!--- TODO: fill the rest of the document -->

docs/resources/account.md

@@ -35,6 +35,8 @@ resource "snowflake_account" "ac1" {
   region               = "AWS_US_WEST_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

docs/resources/account_parameter.md

@@ -23,6 +23,9 @@ resource "snowflake_account_parameter" "p2" {
 }
 ```
 
+-> **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
 

docs/resources/account_password_policy_attachment.md

@@ -23,6 +23,9 @@ resource "snowflake_account_password_policy_attachment" "attachment" {
 }
 ```
 
+-> **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
 

docs/resources/account_role.md

@@ -25,6 +25,8 @@ resource "snowflake_account_role" "complete" {
   comment = "my account role"
 }
 ```
+-> **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

docs/resources/alert.md

@@ -27,6 +27,9 @@ resource "snowflake_alert" "alert" {
 }
 ```
 
+-> **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
 

docs/resources/api_authentication_integration_with_authorization_code_grant.md

@@ -36,6 +36,8 @@ resource "snowflake_api_authentication_integration_with_authorization_code_grant
   oauth_token_endpoint         = "https://example.com"
 }
 ```
+-> **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

docs/resources/api_authentication_integration_with_client_credentials.md

@@ -34,6 +34,8 @@ resource "snowflake_api_authentication_integration_with_client_credentials" "tes
   oauth_token_endpoint        = "https://example.com"
 }
 ```
+-> **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

docs/resources/api_authentication_integration_with_jwt_bearer.md

@@ -37,6 +37,8 @@ resource "snowflake_api_authentication_integration_with_jwt_bearer" "test" {
   oauth_assertion_issuer       = "issuer"
 }
 ```
+-> **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

docs/resources/api_integration.md

@@ -38,6 +38,9 @@ resource "snowflake_api_integration" "gcp" {
 }
 ```
 
+-> **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
 

docs/resources/cortex_search_service.md

@@ -53,6 +53,8 @@ resource "snowflake_cortex_search_service" "test" {
   comment    = "some comment"
 }
 ```
+-> **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

docs/resources/database.md

@@ -76,6 +76,8 @@ resource "snowflake_database" "primary" {
   }
 }
 ```
+-> **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

docs/resources/database_old.md

@@ -44,6 +44,9 @@ resource "snowflake_database_old" "from_share" {
 }
 ```
 
+-> **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
 

docs/resources/database_role.md

@@ -19,6 +19,9 @@ resource "snowflake_database_role" "db_role" {
 }
 ```
 
+-> **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
 

docs/resources/dynamic_table.md

@@ -26,6 +26,9 @@ resource "snowflake_dynamic_table" "dt" {
 }
 ```
 
+-> **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
 

docs/resources/email_notification_integration.md

@@ -21,6 +21,9 @@ resource "snowflake_email_notification_integration" "email_int" {
 }
 ```
 
+-> **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
 

docs/resources/external_function.md

@@ -31,6 +31,9 @@ resource "snowflake_external_function" "test_ext_func" {
 }
 ```
 
+-> **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
 

docs/resources/external_oauth_integration.md

@@ -28,7 +28,7 @@ resource "snowflake_external_oauth_integration" "test" {
   comment                                         = "comment"
   enabled                                         = true
   external_oauth_allowed_roles_list               = ["user1"]
-  external_oauth_any_role_mode                    = "ENABLED"
+  external_oauth_any_role_mode                    = "ENABLE"
   external_oauth_audience_list                    = ["https://example.com"]
   external_oauth_issuer                           = "issuer"
   external_oauth_jws_keys_url                     = ["https://example.com"]
@@ -43,7 +43,7 @@ resource "snowflake_external_oauth_integration" "test" {
 resource "snowflake_external_oauth_integration" "test" {
   comment                                         = "comment"
   enabled                                         = true
-  external_oauth_any_role_mode                    = "ENABLED"
+  external_oauth_any_role_mode                    = "ENABLE"
   external_oauth_audience_list                    = ["https://example.com"]
   external_oauth_blocked_roles_list               = ["user1"]
   external_oauth_issuer                           = "issuer"
@@ -57,6 +57,8 @@ resource "snowflake_external_oauth_integration" "test" {
   external_oauth_type                             = "CUSTOM"
 }
 ```
+-> **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

docs/resources/external_table.md

@@ -31,6 +31,9 @@ resource "snowflake_external_table" "external_table" {
 }
 ```
 
+-> **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
 

docs/resources/failover_group.md

@@ -48,6 +48,9 @@ resource "snowflake_failover_group" "target_failover_group" {
 }
 ```
 
+-> **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
 

docs/resources/file_format.md

@@ -20,6 +20,9 @@ resource "snowflake_file_format" "example_file_format" {
 }
 ```
 
+-> **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
 

docs/resources/function.md

@@ -87,6 +87,9 @@ resource "snowflake_function" "sql_test" {
 }
 ```
 
+-> **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
 

docs/resources/grant_account_role.md

@@ -48,6 +48,9 @@ resource "snowflake_grant_account_role" "g" {
 }
 ```
 
+-> **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
 

docs/resources/grant_application_role.md

@@ -40,6 +40,9 @@ resource "snowflake_grant_application_role" "g" {
 }
 ```
 
+-> **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
 

docs/resources/grant_database_role.md

@@ -59,6 +59,9 @@ resource "snowflake_grant_database_role" "g" {
 }
 ```
 
+-> **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
 

docs/resources/grant_ownership.md

@@ -207,6 +207,8 @@ resource "snowflake_schema" "test" {
   name       = "schema"
 }
 ```
+-> **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-->
 
 ## Granting ownership on pipes
 To transfer ownership of a pipe, there must be additional conditions met. Otherwise, additional manual work

docs/resources/grant_privileges_to_account_role.md

@@ -254,6 +254,8 @@ resource "snowflake_grant_privileges_to_account_role" "example" {
 
 ## ID: "\"role_name\"|false|false|SELECT,INSERT|OnSchemaObject|OnFuture|TABLES|InSchema|\"database\".\"my_schema\""
 ```
+-> **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

docs/resources/grant_privileges_to_database_role.md

@@ -172,6 +172,8 @@ resource "snowflake_grant_privileges_to_database_role" "example" {
   }
 }
 ```
+-> **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

docs/resources/grant_privileges_to_share.md

@@ -95,6 +95,8 @@ resource "snowflake_grant_privileges_to_share" "example" {
 
 ## ID: "\"share_name\"|SELECT|OnView|\"database_name\".\"schema_name\".\"view_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

docs/resources/managed_account.md

@@ -24,6 +24,9 @@ resource "snowflake_managed_account" "account" {
 }
 ```
 
+-> **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
 

docs/resources/masking_policy.md

@@ -37,6 +37,9 @@ resource "snowflake_masking_policy" "test" {
 }
 ```
 
+-> **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
 

docs/resources/materialized_view.md

@@ -28,6 +28,9 @@ SQL
 }
 ```
 
+-> **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