Merge branch 'current' into mirnawong1-patch-28

website/docs/docs/build/environment-variables.md

@@ -97,7 +97,7 @@ While all environment variables are encrypted at rest in dbt Cloud, dbt Cloud ha
 
 dbt Cloud has a number of pre-defined variables built in. Variables are set automatically and cannot be changed.
 
-**dbt Cloud IDE details**
+#### dbt Cloud IDE details
 
 The following environment variable is set automatically for the dbt Cloud IDE:
 
@@ -109,13 +109,16 @@ The following environment variable is set automatically for the dbt Cloud IDE:
 
 Use case — This is useful in cases where you want to dynamically use the Git branch name as a prefix for a [development schema](/docs/build/custom-schemas) ( `{{ env_var ('DBT_CLOUD_GIT_BRANCH') }}` ).
 
-**dbt Cloud context**
+#### dbt Cloud context
 
-The following environment variables are set automatically for deployment runs:
+The following environment variables are set automatically: 
 
-- `DBT_ENV`: This key is reserved for the dbt Cloud application and will always resolve to 'prod'
+- `DBT_ENV`: This key is reserved for the dbt Cloud application and will always resolve to 'prod'. For deployment runs only.
+- `DBT_CLOUD_ENVIRONMENT_NAME`: The name of the dbt Cloud environment in which `dbt` is running. 
+- `DBT_CLOUD_ENVIRONMENT_TYPE`: The type of dbt Cloud environment in which `dbt` is running. The valid values are `development` or `deployment`.
+
+#### Run details
 
-**Run details**
 - `DBT_CLOUD_PROJECT_ID`: The ID of the dbt Cloud Project for this run
 - `DBT_CLOUD_JOB_ID`: The ID of the dbt Cloud Job for this run
 - `DBT_CLOUD_RUN_ID`: The ID of this particular run
@@ -124,7 +127,7 @@ The following environment variables are set automatically for deployment runs:
 - `DBT_CLOUD_ENVIRONMENT_ID`: The ID of the environment for this run
 - `DBT_CLOUD_ACCOUNT_ID`: The ID of the dbt Cloud account for this run
 
-**Git details**
+#### Git details
 
 _The following variables are currently only available for GitHub, GitLab, and Azure DevOps PR builds triggered via a webhook_
 

website/docs/docs/build/saved-queries.md

@@ -102,24 +102,7 @@ saved_queries:
 ```
 </File>
 
-Note, you can set `export_as` to both the saved query and the exports [config](/reference/resource-properties/config), with the exports config value taking precedence. If a key isn't set in the exports config, it will inherit the saved query config value.
-
-#### Project-level saved queries
-
-To enable saved queries at the project level, you can set the `saved-queries` configuration in the [`dbt_project.yml` file](/reference/dbt_project.yml). This saves you time in configuring saved queries in each file:
-
-<File name='dbt_project.yml'>
-
-```yaml
-saved-queries:
-  my_saved_query:
-    config:
-      +cache:
-        enabled: true
-```
-</File>
-
-For more information on `dbt_project.yml` and config naming conventions, see the [dbt_project.yml reference page](/reference/dbt_project.yml#naming-convention).
+Note, that you can set `export_as` to both the saved query and the exports [config](/reference/resource-properties/config), with the exports config value taking precedence. If a key isn't set in the exports config, it will inherit the saved query config value.
 
 #### Where clause
 
@@ -171,6 +154,26 @@ saved_queries:
 </File>
 </VersionBlock>
 
+<VersionBlock firstVersion="1.7">
+
+#### Project-level saved queries
+
+To enable saved queries at the project level, you can set the `saved-queries` configuration in the [`dbt_project.yml` file](/reference/dbt_project.yml). This saves you time in configuring saved queries in each file:
+
+<File name='dbt_project.yml'>
+
+```yaml
+saved-queries:
+  my_saved_query:
+    config:
+      +cache:
+        enabled: true
+```
+</File>
+
+For more information on `dbt_project.yml` and config naming conventions, see the [dbt_project.yml reference page](/reference/dbt_project.yml#naming-convention).
+</VersionBlock>
+
 To build `saved_queries`, use the [`--resource-type` flag](/reference/global-configs/resource-type) and run the command `dbt build --resource-type saved_query`.
 
 ## Configure exports

website/docs/docs/cloud/manage-access/set-up-snowflake-oauth.md

@@ -35,15 +35,21 @@ To get started, copy the connection's redirect URI from dbt Cloud:
 
 ### Create a security integration
 
-In Snowflake, execute a query to create a security integration. Please find the complete documentation on creating a security integration for custom clients [here](https://docs.snowflake.net/manuals/sql-reference/sql/create-security-integration.html#syntax). In the following example `create or replace security integration` query, replace `YOUR_ACCESS_URL` with the [appropriate Access URL](/docs/cloud/about-cloud/access-regions-ip-addresses) for your region and plan.
+In Snowflake, execute a query to create a security integration. Please find the complete documentation on creating a security integration for custom clients [here](https://docs.snowflake.net/manuals/sql-reference/sql/create-security-integration.html#syntax). 
+
+In the following `CREATE OR REPLACE SECURITY INTEGRATION` example query, replace `<REDIRECT_URI>` with the [appropriate Access URL](/docs/cloud/about-cloud/access-regions-ip-addresses) for your region and plan. You can find this in dbt Cloud by:
+- Navigating to **Account settings**  and then **Connections** 
+- Click on the Snowflake connection 
+- Copy the URL under **Redirect URI**
+<Lightbox src="/img/docs/dbt-cloud/access-control/oauth-connections.jpg" width="70%" title="Copy the 'Redirect URI' URL in dbt Cloud and replace it in the 'OAUTH_REDIRECT_URI' field." />
 
 ```
 CREATE OR REPLACE SECURITY INTEGRATION DBT_CLOUD
   TYPE = OAUTH
   ENABLED = TRUE
   OAUTH_CLIENT = CUSTOM
   OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
-  OAUTH_REDIRECT_URI = 'LOCATED_REDIRECT_URI'
+  OAUTH_REDIRECT_URI = '<REDIRECT_URI>'
   OAUTH_ISSUE_REFRESH_TOKENS = TRUE
   OAUTH_REFRESH_TOKEN_VALIDITY = 7776000;
 ```

website/docs/docs/dbt-versions/release-notes.md

@@ -20,9 +20,11 @@ Release notes are grouped by month for both multi-tenant and virtual private clo
 
 ## September 2024
 
+- **New:** There are two new [environment variable defaults](/docs/build/environment-variables#dbt-cloud-context) — `DBT_CLOUD_ENVIRONMENT_NAME` and `DBT_CLOUD_ENVIRONMENT_TYPE`.
 - **New:** The [Amazon Athena warehouse connection](/docs/cloud/connect-data-platform/connect-amazon-athena) is available as a public preview for dbt Cloud accounts that have upgraded to [`versionless`](/docs/dbt-versions/versionless-cloud).
 
 ## August 2024
+
 - **Fix:** Fixed an issue in [dbt Explorer](/docs/collaborate/explore-projects) where navigating to a consumer project from a public node resulted in displaying a random public model rather than the original selection. 
 - **New**: You can now configure metrics at granularities at finer time grains, such as hour, minute, or even by the second. This is particularly useful for more detailed analysis and for datasets where high-resolution time data is required, such as minute-by-minute event tracking. Refer to [dimensions](/docs/build/dimensions) for more information about time granularity.
 - **Enhancement**: Microsoft Excel now supports [saved selections](/docs/cloud-integrations/semantic-layer/excel#using-saved-selections) and [saved queries](/docs/cloud-integrations/semantic-layer/excel#using-saved-queries). Use Saved selections to save your query selections within the Excel application. The application also clears stale data in [trailing rows](/docs/cloud-integrations/semantic-layer/excel#other-settings) by default. To return your results and keep any previously selected data intact, un-select the **Clear trailing rows** option. 

website/docs/guides/adapter-creation.md

@@ -556,6 +556,108 @@ While much of dbt's adapter-specific functionality can be modified in adapter ma
 
 See [this GitHub discussion](https://github.com/dbt-labs/dbt-core/discussions/5468) for information on the macros required for `GRANT` statements:
 
+### Behavior change flags
+
+Starting in `dbt-adapters==1.5.0` and `dbt-core==1.8.7`, adapter maintainers can implement their own behavior change flags. Refer to [Behavior changes](https://docs.getdbt.com/reference/global-configs/behavior-changes)for more information. 
+
+Behavior Flags are not intended to be long-living feature flags. They should be implemented with the expectation that the behavior will be the default within an expected period of time. To implement a behavior change flag, you must provide a name for the flag, a default setting (`True` / `False`), an optional source, and a description and/or a link to the flag's documentation on docs.getdbt.com. 
+
+We recommend having a description and documentation link whenever possible. The description and/or docs should provide end users context for why the flag exists, why they may see a warning, and why they may want to utilize the behavior flag. Behavior change flags can be implemented by overwriting `_behavior_flags()` on the adapter in `impl.py`:
+
+<File name='impl.py'>
+
+```python
+class ABCAdapter(BaseAdapter):
+    ...
+    @property
+    def _behavior_flags(self) -> List[BehaviorFlag]:
+        return [
+            {
+                "name": "enable_new_functionality_requiring_higher_permissions",
+                "default": False,
+                "source": "dbt-abc",
+                "description": (
+                    "The dbt-abc adapter is implementing a new method for sourcing metadata. "
+                    "This is a more performant way for dbt to source metadata but requires higher permissions on the platform. "
+                    "Enabling this without granting the requisite permissions will result in an error. "
+                    "This feature is expected to be required by Spring 2025."
+                ),
+                "docs_url": "https://docs.getdbt.com/reference/global-configs/behavior-changes#abc-enable_new_functionality_requiring_higher_permissions",
+            }
+        ]
+```
+
+</File>
+
+Once a behavior change flag has been implemented, it can be referenced on the adapter both in `impl.py` and in Jinja macros:
+
+<File name='impl.py'>
+
+```python
+class ABCAdapter(BaseAdapter):
+    ...
+    def some_method(self, *args, **kwargs):
+        if self.behavior.enable_new_functionality_requiring_higher_permissions:
+            # do the new thing
+        else:
+            # do the old thing
+```
+
+</File>
+
+<File name='adapters.sql'>
+
+```sql
+{% macro some_macro(**kwargs) %}
+    {% if adapter.behavior.enable_new_functionality_requiring_higher_permissions %}
+        {# do the new thing #}
+    {% else %}
+        {# do the old thing #}
+    {% endif %}
+{% endmacro %}
+```
+
+</File>
+
+Every time the behavior flag evaluates to `False,` it warns the user, informing them that a change will occur in the future.
+
+This warning doesn't display when the flag evaluates to `True` as the user is already in the new experience.
+
+Recognizing that the warnings can be disruptive and are not always necessary, you can evaluate the flag without triggering the warning. Simply append `.no_warn` to the end of the flag.
+
+
+<File name='impl.py'>
+
+```python
+    class ABCAdapter(BaseAdapter):
+        ...
+        def some_method(self, *args, **kwargs):
+            if self.behavior.enable_new_functionality_requiring_higher_permissions.no_warn:
+                # do the new thing
+            else:
+                # do the old thing
+```
+
+</File>
+
+<File name='adapters.sql'>
+
+```sql
+{% macro some_macro(**kwargs) %}
+    {% if adapter.behavior.enable_new_functionality_requiring_higher_permissions.no_warn %}
+        {# do the new thing #}
+    {% else %}
+        {# do the old thing #}
+    {% endif %}
+{% endmacro %}
+```
+
+</File>
+
+It's best practice to evaluate a behavior flag as few times as possible. This will make it easier to remove once the behavior change has matured.
+
+As a result, evaluating the flag earlier in the logic flow is easier. Then, take either the old or the new path. While this may create some duplication in code, using behavior flags in this way provides a safer way to implement a change, which we are already admitting is risky or even breaking in nature.
+
 ### Other files
 
 #### `profile_template.yml`

website/docs/reference/global-configs/behavior-changes.md

@@ -41,7 +41,12 @@ By contrast, behavior change migrations happen slowly, over the course of months
 
 These flags _must_ be set in the `flags` dictionary in `dbt_project.yml`. They configure behaviors closely tied to project code, which means they should be defined in version control and modified through pull or merge requests, with the same testing and peer review.
 
-The following example displays the current flags and their current default values in the latest dbt Cloud and dbt Core versions. To opt out of a specific behavior change, set the values of the flag to `False` in `dbt_project.yml`. You'll continue to see warnings for legacy behaviors that you have opted out of explicitly until you either resolve them (switch the flag to `True`) or choose to silence the warnings using the `warn_error_options.silence` flag.
+The following example displays the current flags and their current default values in the latest dbt Cloud and dbt Core versions. To opt out of a specific behavior change, set the values of the flag to `False` in `dbt_project.yml`. You will continue to see warnings for legacy behaviors you’ve opted out of, until you either:
+
+- Resolve the issue (by switching the flag to `True`)
+- Silence the warnings using the `warn_error_options.silence` flag
+
+Here's an example of the available behavior change flags with their default values:
 
 <File name='dbt_project.yml'>
 
@@ -50,6 +55,7 @@ flags:
   require_explicit_package_overrides_for_builtin_materializations: False
   require_model_names_without_spaces: False
   source_freshness_run_project_hooks: False
+  restrict_direct_pg_catalog_access: False
 ```
 
 </File>
@@ -61,7 +67,7 @@ When we use dbt Cloud in the following table, we're referring to accounts that h
 | require_explicit_package_overrides_for_builtin_materializations | 2024.04.141      | 2024.06.192         | 1.6.14, 1.7.14  | 1.8.0             |
 | require_resource_names_without_spaces                           | 2024.05.146      | TBD*                | 1.8.0           | 1.9.0             |
 | source_freshness_run_project_hooks                              | 2024.03.61       | TBD*                | 1.8.0           | 1.9.0             |
-| [Redshift] restrict_direct_pg_catalog_access                    | 2024.09.242      | TBD*                | dbt-redshift v1.9.0           | 1.9.0             |
+| [Redshift] [restrict_direct_pg_catalog_access](#redshift-restrict_direct_pg_catalog_access)    | 2024.09.242      | TBD*                | dbt-redshift v1.9.0           | 1.9.0             |
 
 When the dbt Cloud Maturity is "TBD," it means we have not yet determined the exact date when these flags' default values will change. Affected users will see deprecation warnings in the meantime, and they will receive emails providing advance warning ahead of the maturity date. In the meantime, if you are seeing a deprecation warning, you can either:
 - Migrate your project to support the new behavior, and then set the flag to `True` to stop seeing the warnings.

website/plugins/buildRSSFeeds/index.js

@@ -8,13 +8,20 @@ module.exports = function buildRSSFeedsPlugin() {
   return {
     name: 'docusaurus-build-rss-feeds-plugin',
     async loadContent() {
+
+      // Skip generating RSS feeds in non-production environments
+      if (process.env.VERCEL_ENV !== "production") {
+        console.log('RSS Feeds are only generated in production. Skipping creation of RSS Feed.')
+        return null
+      }
+
       // Release Notes directory
       const releaseNotesDirectory = 'docs/docs/dbt-versions/release-notes'
 
       // Get all files and file data within all release notes directories
       const releaseNotesFiles = getDirectoryFiles(releaseNotesDirectory, [], true)
 
-      if(!releaseNotesFiles || !releaseNotesFiles.length) 
+      if (!releaseNotesFiles || !releaseNotesFiles.length)
         return null
 
       // Generate RSS feeds