Merge branch 'dev' into listing-data-source

# Conflicts:
#	MIGRATION_GUIDE.md

Author: sfc-gh-jcieslak

CONTRIBUTING.md

@@ -8,12 +8,13 @@
 - [Making a contribution](#making-a-contribution)
   - [Discuss a change with us!](#discuss-a-change-with-us)
   - [Follow the code conventions inside the repository](#follow-the-code-conventions-inside-the-repository)
-  - [Introducing a new part of the SDK](#introducing-a-new-part-of-the-sdk)
   - [Test the change](#test-the-change)
   - [Describe the breaking changes](#describe-the-breaking-changes)
   - [Before submitting the PR](#before-submitting-the-pr)
   - [Naming and describing the PR](#naming-and-describing-the-pr)
   - [Requesting the review](#requesting-the-review)
+  - [Adding support for a new snowflake object](#adding-support-for-a-new-snowflake-object)
+    - [Introducing a new part of the SDK](#add-the-object-to-the-sdk)
 - [Advanced Debugging](#advanced-debugging)
 - [Extending the migration script](#extending-the-migration-script)
 
@@ -104,10 +105,6 @@ It's best to approach us through the GitHub issues: either by commenting the alr
 ### Follow the code conventions inside the repository
 We believe that code following the same conventions is easier to maintain and extend. When working on the given part of the provider try to follow the local solutions and not introduce too much new ideas.
 
-### Introducing a new part of the SDK
-
-To create new objects in our SDK we use quickly created generator that outputs the majority of the files needed. These files should be later edited and filled with the missing parts. We plan to improve the generator later on, but it should be enough for now. Please read more in the [generator readme](pkg/sdk/generator/README.md).
-
 ### Test the change
 Every introduced change should be tested. Depending on the type of the change it may require (any or mix of):
 - adding/modifying existing unit tests (e.g. changing the behavior of validation in the SDK)
@@ -144,8 +141,107 @@ We check for the new PRs in our repository every day Monday-Friday. We usually n
 
 During our review we try to point out the unhandled special cases, missing tests, and deviations from the established conventions. Remember, review comment is like an invitation to dance: you don't have to agree but please provide the substantive reasons.
 
+Please do not resolve our comments. We prefer to resolve ourselves after the comments are followed up by the contributor.
+
 **⚠️ Important ⚠️** Tests and checks are not run automatically after your PR. We run them manually, when we are happy with the state of the change (even if some corrections are still necessary).
 
+## Adding Support for a new Snowflake Object
+This guide describes the end-to-end process to add support for a new Snowflake object in the Terraform provider. Work is typically split into multiple PRs: SDK first, then SDK integration tests, followed by the Terraform resource, and finally the data source (SDK → integration tests → resource → data source).
+
+### Prerequisites and conventions
+- Use the SDK generator to define the object and produce the bulk of implementation and validations. See the SDK generator [README](pkg/sdk/generator/README.md) for file layout, generation parts, and commands.
+
+- Do not edit generated files; place any custom helpers or overrides in *_ext.go files. This is the pattern used across the SDK
+
+- Map both SHOW and DESCRIBE outputs. If the outputs differ, generate separate mapping structs and conversion paths; do not force a shared struct across both operations.
+
+### Add the object to the SDK
+- Create `<object_name_plural>_def.go` in the SDK generator defs directory
+
+- Use the DSL to configure operations: CREATE/ALTER/DROP, DESCRIBE, SHOW, and optional ShowById helpers. For example, notebooks use DescribeOperation, ShowOperation, and ShowByIdOperationWithFiltering to support both SHOW and DESCRIBE flows plus a by-ID retrieval.
+
+- If the server returns different shapes for SHOW and DESCRIBE, generate and map them separately.
+
+- From repository root, run make generate-sdk to build all parts
+
+- Expect the generator to create interface, DTOs, builders, validations, impl, and unit test placeholders (e.g., `_gen.go`, `_dto_gen.go`, `_dto_builders_gen.go`, `_validations_gen.go`, `_impl_gen.go`, `_gen_test.go`).
+
+- Avoid encoding server-side numeric ranges unless they are stable and guaranteed (rely on Snowflake for ranges/limits validations, check for only basic cases like integers being non-negative).
+
+- Implement unit tests.
+
+Take a look at [generator readme](pkg/sdk/generator/README.md) and an example [SDK implementation for notebooks](https://github.com/snowflakedb/terraform-provider-snowflake/pull/4084).
+
+### Add integration tests
+Add integration tests under the SDK’s testint package to validate the SDK behavior against a live Snowflake connection.
+
+Recommended coverage:
+- Lifecycle: create, show, describe, alter (set/unset combinations), rename, drop, and show-by-id where applicable. Prefer asserting fields you directly control (e.g., comment) and anything with server defaults you depend on.
+
+- Nil handling: ensure tests don’t panic on optional pointers (e.g., check for `nil` before calling `.Name()` on an identifier pointer).
+
+- ALTER validations: test both invalid “none set” and “more than one set” branches when you have ExactlyOneValueSet or AtLeastOneValueSet rules.
+
+- Error parity: assert the correct error kinds for missing objects (e.g., prefer consistent “object does not exist or not authorized” variants).
+
+- Assertion helpers: the generator can produce “object asserts” for SHOW/DESC outputs. Use generated assertion structs for concision, but add nil-checks to avoid panics in optional fields.
+
+- use `make generate-snowflake-object-assertions` to generate the assertions for the integration tests.
+
+Take a look at [generator readme](pkg/sdk/generator/README.md) and an example [Integration tests implementation for notebooks](https://github.com/snowflakedb/terraform-provider-snowflake/pull/4123).
+
+### Add resource
+Implement the resource schema, read/create/update/delete, acceptance tests, and docs. Use the SDK as the source of truth and mirror its SHOW/DESC coverage and validations.
+
+- Schema design
+  - Prefer nested blocks for structured inputs. For example, “create from a stage” is modeled as a `from { stage = "<db>.<schema>.<stage>" path = "path/to/file" }` block rather than a flat string, to align with Snowflake semantics and improve validation.
+
+  - Validate identifiers with the provider’s identifier validators (e.g., `IsValidIdentifier[...]`) and suppress quoting-only diffs for identifier fields (`suppressIdentifierQuoting`).
+
+- Update semantics
+  - If it's possible, implement rename in-place (`ALTER … RENAME TO …`) rather than ForceNew. Align with how recently refactored resources handle renames.
+
+  - Detect external changes for derived outputs via SHOW/DESC triggers when possible. If a particular field cannot be detected externally (e.g., notebooks “from” location due to Snowflake limitations), document that limitation explicitly in the resource docs.
+
+- Defaults and constraints surfaced in docs
+  - Where Snowflake restricts identifier casing (e.g., only upper-case identifiers are valid for specific warehouse references), document it explicitly and add validators to prevent invalid inputs in plans.
+
+- Documentation and migration guide
+  - Add a Migration Guide entry under the correct version, grouping object support under a single H3 “(new feature) snowflake_” heading with H4 subsections for “Added resource” and “Added data source”.
+
+  - When server capabilities are incomplete, document current limitations and ensure Update/Create sequences handle supported paths without requiring double-applies. Remember to use the model builder and assertions that you can automatically generate.
+
+- Implement acceptance tests
+  - Provide “basic” and “complete” cases; test rename, validations, and plan drift (ConfigPlanChecks). Avoid relying on “Safe” client wrappers for correctness checks; validate against the same paths real users hit.
+
+- use `make generate-show-output-schemas` to generate show schemas.
+
+- use `make generate-all-assertions-and-config-models` to generate assertions and config models.
+
+Take a look at an example [Resource implementation for notebooks](https://github.com/snowflakedb/terraform-provider-snowflake/pull/4195)
+
+### Add data source
+While not strictly required to “support” the object, a data source improves discoverability and enables read-only use cases. For parity with other objects, we recommend adding one.
+
+Example patterns validated by the data source:
+- Filtering aligned to SHOW
+  - Support `like`, `starts_with`, and `limit { rows, from }` to mirror SHOW filters; include `with_describe` to optionally call DESCRIBE for each item. Keep `with_describe` default-on but allow turning it off to reduce calls in large accounts.
+
+- Output shape
+  - Aggregate into a single `<object_name_plural>` collection with nested `show_output` (SHOW) and `describe_output` (DESCRIBE) blocks containing fields as strings/numbers
+
+- Documentation and examples
+  - Provide simple, filter, and pagination examples; include a note about default behavior of `with_describe`.
+
+- Provider preview gate and migration guide
+  - Add the “Added data source” H4 subsection under the same feature entry in the Migration Guide and link Snowflake’s SHOW docs where appropriate.
+
+- use `make generate-all-assertions-and-config-models` to generate config model.
+
+- use `make docs` to generate documentation based on the `.md.tmpl` file (which is the file you should edit instead of `.md` file).
+
+Take a look at [Data source implementation for notebooks](https://github.com/snowflakedb/terraform-provider-snowflake/pull/4209) and its follow up with extra tests [Extended test coverage for notebooks](https://github.com/snowflakedb/terraform-provider-snowflake/pull/4237)
+
 ## Advanced Debugging
 
 If you want to build and test the provider locally (manually, not through acceptance tests), build the binary first using `make build-local` or install to the proper local directory by invoking `make install-tf` (to uninstall run `make uninstall-tf`).

FAQ.md

@@ -81,7 +81,7 @@ Please refer to [this document](https://github.com/snowflakedb/terraform-provide
 - For a new way of referencing object identifiers in resources, take a look at the ["New computed fully qualified name field in resources" ](https://github.com/snowflakedb/terraform-provider-snowflake/blob/main/docs/guides/identifiers_rework_design_decisions.md#new-computed-fully-qualified-name-field-in-resources) section.
 
 ### Is this provider compatible with OpenTofu?
-OpenTofu is not currently supported. While it's mostly compatible with Terraform,
-OpenTofu's [reactive implementation of new Terraform features based on community demand](https://opentofu.org/faq/#opentofu-compatibility) may decrease compatibility over time.
+Although, the provider is present in the OpenTofu Registry ([see](https://github.com/snowflakedb/terraform-provider-snowflake/issues/3874)), it is not currently supported.
+While it's mostly compatible with Terraform, OpenTofu's [reactive implementation of new Terraform features based on community demand](https://opentofu.org/faq/#opentofu-compatibility) may decrease compatibility over time.
 We plan to research OpenTofu support in the future, but there's no timeline yet (once planned, it will appear in the [roadmap](https://github.com/snowflakedb/terraform-provider-snowflake/blob/main/ROADMAP.md)).
 For now, you must research and assess the risk of provider incompatibility.

MIGRATION_GUIDE.md

@@ -24,7 +24,7 @@ for changes required after enabling given [Snowflake BCR Bundle](https://docs.sn
 > [!TIP]
 > If you're still using the `Snowflake-Labs/snowflake` source, see [Upgrading from Snowflake-Labs Provider](./SNOWFLAKEDB_MIGRATION.md) to upgrade to the snowflakedb namespace.
 
-## v2.11.0 ➞ v2.12.0
+## v2.11.x ➞ v2.12.0
 
 ### *(new feature)* snowflake_listings datasource
 Added a new preview data source for listings. See reference [docs](https://docs.snowflake.com/en/sql-reference/sql/show-listings).
@@ -33,12 +33,35 @@ This data source focuses on base query commands (SHOW LISTINGS and DESCRIBE LIST
 
 This feature will be marked as a stable feature in future releases. Breaking changes are expected, even without bumping the major version. To use this feature, add `snowflake_listings_datasource` to `preview_features_enabled` field in the provider configuration.
 
+### *(improvement)* snowflake_scim_integration now accepts custom role names for run_as_role
+
+Previously, the `run_as_role` field in the [snowflake_scim_integration](https://registry.terraform.io/providers/snowflakedb/snowflake/2.11.0/docs/resources/scim_integration) resource only accepted predefined role names: `OKTA_PROVISIONER`, `AAD_PROVISIONER`, or `GENERIC_SCIM_PROVISIONER`.
+
+Now, the field accepts any custom role name, allowing you to use organization-specific roles for SCIM provisioning. This field is now case-sensitive. The exception is if you set any of `okta_provisioner`, `aad_provisioner`, or `generic_scim_provisioner`.
+To maintain compatibility and avoid breaking changes, for these values, the provider makes them uppercase (like it was doing before). This will be changed in the v3 version of the provider (the field will behave like all other identifier fields).
+- If you use `OKTA_PROVISIONER`, `AAD_PROVISIONER`, or `GENERIC_SCIM_PROVISIONER` roles in Snowflake, please make them uppercase in your configuration (this will result in an empty plan).
+- If you use `okta_provisioner`, `aad_provisioner`, or `generic_scim_provisioner` roles in Snowflake, please handle them in provider with snowflake_execute, or rename the roles entirely.
+
+Existing configurations using predefined roles will continue to work without modifications, but please bear in mind the potential case-sensitive changes in v3.
+
+References: [#3917](https://github.com/snowflakedb/terraform-provider-snowflake/issues/3917).
+
+### *(new feature)* Added serverless task parameters
+Added support for new serverless task fields:
+- `target_completion_interval` - Specifies the target completion interval for serverless tasks; also added as a computed value to `show_output`.
+- `serverless_task_min_statement_size` (parameter) - Minimum statement size for serverless tasks; also added as a computed value to `parameters`.
+- `serverless_task_max_statement_size` (parameter) - Maximum statement size for serverless tasks; also added as a computed value to `parameters`.
+
+These fields are available in the `snowflake_task` resource for serverless task configurations.
+
+No changes in configuration are required for existing tasks. You can optionally update your configurations to use these new parameters.
+
 ### *(improvement)* New fields in user resources and data sources output fields
-We adjusted the `show_output` by adding the missing `has_workload_identity ` field. This concerns `user`, `service_user`, and `legacy_service_user` resources and `users` data source.
+We adjusted the `show_output` by adding the missing `has_workload_identity` field. This concerns `user`, `service_user`, and `legacy_service_user` resources and `users` data source.
 
 ## v2.10.x ➞ v2.11.0
 
-### *(new feature)* snowflake_notebook
+### *(new feature)* Notebooks preview feature
 
 #### Added resource
 Added a new preview resource for managing notebooks. See reference [docs](https://docs.snowflake.com/en/sql-reference/sql/create-notebook).

docs/data-sources/tasks.md

@@ -224,6 +224,8 @@ Read-Only:
 - `rows_per_resultset` (List of Object) (see [below for nested schema](#nestedobjatt--tasks--parameters--rows_per_resultset))
 - `s3_stage_vpce_dns_name` (List of Object) (see [below for nested schema](#nestedobjatt--tasks--parameters--s3_stage_vpce_dns_name))
 - `search_path` (List of Object) (see [below for nested schema](#nestedobjatt--tasks--parameters--search_path))
+- `serverless_task_max_statement_size` (List of Object) (see [below for nested schema](#nestedobjatt--tasks--parameters--serverless_task_max_statement_size))
+- `serverless_task_min_statement_size` (List of Object) (see [below for nested schema](#nestedobjatt--tasks--parameters--serverless_task_min_statement_size))
 - `statement_queued_timeout_in_seconds` (List of Object) (see [below for nested schema](#nestedobjatt--tasks--parameters--statement_queued_timeout_in_seconds))
 - `statement_timeout_in_seconds` (List of Object) (see [below for nested schema](#nestedobjatt--tasks--parameters--statement_timeout_in_seconds))
 - `strict_json_output` (List of Object) (see [below for nested schema](#nestedobjatt--tasks--parameters--strict_json_output))
@@ -635,6 +637,30 @@ Read-Only:
 - `value` (String)
 
 
+<a id="nestedobjatt--tasks--parameters--serverless_task_max_statement_size"></a>
+### Nested Schema for `tasks.parameters.serverless_task_max_statement_size`
+
+Read-Only:
+
+- `default` (String)
+- `description` (String)
+- `key` (String)
+- `level` (String)
+- `value` (String)
+
+
+<a id="nestedobjatt--tasks--parameters--serverless_task_min_statement_size"></a>
+### Nested Schema for `tasks.parameters.serverless_task_min_statement_size`
+
+Read-Only:
+
+- `default` (String)
+- `description` (String)
+- `key` (String)
+- `level` (String)
+- `value` (String)
+
+
 <a id="nestedobjatt--tasks--parameters--statement_queued_timeout_in_seconds"></a>
 ### Nested Schema for `tasks.parameters.statement_queued_timeout_in_seconds`
 
@@ -973,9 +999,20 @@ Read-Only:
 - `schedule` (String)
 - `schema_name` (String)
 - `state` (String)
+- `target_completion_interval` (List of Object) (see [below for nested schema](#nestedobjatt--tasks--show_output--target_completion_interval))
 - `task_relations` (List of Object) (see [below for nested schema](#nestedobjatt--tasks--show_output--task_relations))
 - `warehouse` (String)
 
+<a id="nestedobjatt--tasks--show_output--target_completion_interval"></a>
+### Nested Schema for `tasks.show_output.target_completion_interval`
+
+Read-Only:
+
+- `hours` (Number)
+- `minutes` (Number)
+- `seconds` (Number)
+
+
 <a id="nestedobjatt--tasks--show_output--task_relations"></a>
 ### Nested Schema for `tasks.show_output.task_relations`
 

docs/resources/scim_integration.md

@@ -46,7 +46,7 @@ resource "snowflake_scim_integration" "test" {
 
 - `enabled` (Boolean) Specify whether the security integration is enabled.
 - `name` (String) String that specifies the identifier (i.e. name) for the integration; must be unique in your account. Due to technical limitations (read more [here](../guides/identifiers_rework_design_decisions#known-limitations-and-identifier-recommendations)), avoid using the following characters: `|`, `.`, `"`.
-- `run_as_role` (String) Specify the SCIM role in Snowflake that owns any users and roles that are imported from the identity provider into Snowflake using SCIM. Provider assumes that the specified role is already provided. Valid options are: `OKTA_PROVISIONER` | `AAD_PROVISIONER` | `GENERIC_SCIM_PROVISIONER`.
+- `run_as_role` (String) Specify the SCIM role in Snowflake that owns any users and roles that are imported from the identity provider into Snowflake using SCIM. Provider assumes that the specified role is already provided. This field is case-sensitive. The exception is using `generic_scim_provisioner`, `okta_provisioner`, or `aad_provisioner`, which are automatically converted to uppercase for backwards compatibility.
 - `scim_client` (String) Specifies the client type for the scim integration. Valid options are: `OKTA` | `AZURE` | `GENERIC`.
 
 ### Optional