Adding 1.8 install changes (#5002)

closes #4999 ## What are you changing in this pull request and why? Updating adapter and core install content for v1.8. You now need to explicitly install core and the adapter as they have been decoupled. --------- Co-authored-by: colin-rogers-dbt <[email protected]> Co-authored-by: Mirna Wong <[email protected]>
dbt-labs · Feb 28, 2024 · 3dd2933 · 3dd2933
1 parent 9d43db7
commit 3dd2933
Show file tree

Hide file tree

Showing 5 changed files with 111 additions and 22 deletions.
diff --git a/website/docs/best-practices/how-we-build-our-metrics/semantic-layer-2-setup.md b/website/docs/best-practices/how-we-build-our-metrics/semantic-layer-2-setup.md
@@ -30,7 +30,8 @@ Next, before you start writing code, you need to install MetricFlow:
 
 - Download MetricFlow as an extension of a dbt adapter from PyPI  (dbt Core users only). The MetricFlow is compatible with Python versions 3.8 through 3.11. 
   - **Note**: You'll need to manage versioning between dbt Core, your adapter, and MetricFlow.
-- We'll use pip to install MetricFlow and our dbt adapter:
+- Beginning in v1.8, installing an adapter does not automatically install `dbt-core`. This is because adapters and dbt Core versions have been decoupled from each other so we no longer want to overwrite existing dbt-core installations.
+- Use pip to install MetricFlow and the dbt adapter.
 
 ```shell
 # activate a virtual environment for your project,

diff --git a/website/docs/docs/core/homebrew-install.md b/website/docs/docs/core/homebrew-install.md
@@ -35,13 +35,13 @@ brew install git
 brew tap dbt-labs/dbt
 ```
 
-Now you're ready to install dbt. Once you know [which adapter](/docs/supported-data-platforms) you're using, you can install it as `dbt-<adapter>`. For instance, if using Postgres:
+Now you're ready to install dbt. Once you know [which adapter](/docs/supported-data-platforms) you're using, you can install it as `dbt-ADAPTER_NAME`. For instance, if using Postgres:
 
 ```shell
 brew install dbt-postgres
 ```
 
-Everywhere below that you see `<adapter>`, replace it with the adapter name you're using.
+Everywhere below that you see `ADAPTER_NAME`, replace it with the adapter name you're using.
 
 **Note**: If you're using an adapter that isn't available as a Homebrew formula, we recommend you use [pip](/docs/core/pip-install) instead.
 
@@ -51,17 +51,17 @@ To upgrade dbt, use:
 
 ```shell
 brew update
-brew upgrade dbt-<adapter>
+brew upgrade dbt-ADAPTER_NAME
 ```
 
 ### Switching versions
 
 You can install and use multiple versions of dbt with Homebrew through something called Homebrew "links." To allow installation of another version of dbt, first unlink the current version:
 
 ```shell
-brew unlink dbt-<adapter>
-brew install dbt-<adapter>@1.0.0
-brew link dbt-<adapter>@1.0.0
+brew unlink dbt-ADAPTER_NAME
+brew install dbt-ADAPTER_NAME@1.0.0
+brew link dbt-ADAPTER_NAME@1.0.0
 ```
 
 Now, you can use dbt Core v1.0.0:
@@ -74,12 +74,12 @@ installed version: 1.0.0
 Up to date!
 
 Plugins:
-  - <adapter>: 1.0.0
+  - ADAPTER_NAME: 1.0.0
 ```
 
 You can switch between versions by linking the one you want to use:
 
 ```shell
-brew unlink dbt-<adapter>@1.0.0
-brew link dbt-<adapter>@0.21.1
+brew unlink dbt-ADAPTER_NAME@1.0.0
+brew link dbt-ADAPTER_NAME@0.21.1
 ```
diff --git a/website/docs/docs/core/pip-install.md b/website/docs/docs/core/pip-install.md
@@ -3,20 +3,21 @@ title: "Install with pip"
 description: "You can use pip to install dbt Core and adapter plugins from the command line."
 ---
 
-You need to use `pip` to install dbt Core on Windows or Linux operating systems. You can use `pip` or [Homebrew](/docs/core/homebrew-install) for installing dbt Core on a MacOS. 
+You need to use `pip` to install dbt Core on Windows or Linux operating systems. You can use `pip` or [Homebrew](/docs/core/homebrew-install) for installing dbt Core on a MacOS.
 
 You can install dbt Core and plugins using `pip` because they are Python modules distributed on [PyPI](https://pypi.org/project/dbt-core/).
 
 <FAQ path="Core/install-pip-os-prereqs" />
 <FAQ path="Core/install-python-compatibility" />
 
 ### Using virtual environments
-We recommend using virtual environments (venv) to namespace pip modules. 
+
+We recommend using virtual environments (venv) to namespace pip modules.
 
 1. Create a new venv:
 
 ```shell
-python3 -m venv dbt-env				# create the environment
+python -m venv dbt-env				# create the environment
 ```
 
 2. Activate that same virtual environment each time you create a shell window or session:
@@ -27,6 +28,7 @@ dbt-env\Scripts\activate			# activate the environment for Windows
 ```
 
 #### Create an alias
+
 To activate your dbt environment with every new shell window or session, you can create an alias for the source command in your $HOME/.bashrc, $HOME/.zshrc, or whichever config file your shell draws from. 
 
 For example, add the following to your rc file, replacing <PATH_TO_VIRTUAL_ENV_CONFIG> with the path to your virtual environment configuration.
@@ -36,10 +38,31 @@ alias env_dbt='source <PATH_TO_VIRTUAL_ENV_CONFIG>/bin/activate'
 ```
 
 ### Installing the adapter
-Once you know [which adapter](/docs/supported-data-platforms) you're using, you can install it as `dbt-<adapter>`. For example, if using Postgres:
+
+Once you decide [which adapter](/docs/supported-data-platforms) you're using, you can install using the command line. Beginning in v1.8, installing an adapter does not automatically install `dbt-core`. This is because adapters and dbt Core versions have been decoupled from each other so we no longer want to overwrite existing dbt-core installations.
+
+<VersionBlock firstVersion="1.8">
 
 ```shell
-python -m pip install dbt-postgres
+python -m pip install dbt-core dbt-ADAPTER_NAME
+```
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.7">
+
+```shell
+python -m pip install dbt-ADAPTER_NAME
+```
+
+</VersionBlock>
+
+For example, if using Postgres:
+
+<VersionBlock firstVersion="1.8">
+
+```shell
+python -m pip install dbt-core dbt-postgres
 ```
 
 This will install `dbt-core` and `dbt-postgres` _only_:
@@ -56,13 +79,36 @@ Plugins:
 ```
 
 All adapters build on top of `dbt-core`. Some also depend on other adapters: for example, `dbt-redshift` builds on top of `dbt-postgres`. In that case, you would see those adapters included by your specific installation, too.
+</VersionBlock>
+
+<VersionBlock lastVersion="1.7">
+
+```shell
+python -m pip install dbt-postgres
+```
+
+This will install `dbt-core` and `dbt-postgres` _only_:
+
+```shell
+$ dbt --version
+installed version: 1.0.0
+   latest version: 1.0.0
+
+Up to date!
+
+Plugins:
+  - postgres: 1.0.0
+```
+
+Some adapters depend on other adapters. For example, `dbt-redshift` builds on top of `dbt-postgres`. In that case, you would see those adapters included by your specific installation, too.
+</VersionBlock>
 
 ### Upgrade adapters
 
 To upgrade a specific adapter plugin:
 
 ```shell
-python -m pip install --upgrade dbt-<adapter>
+python -m pip install --upgrade dbt-ADAPTER_NAME
 ```
 
 ### Install dbt-core only
@@ -72,6 +118,7 @@ If you're building a tool that integrates with dbt Core, you may want to install
 ```shell
 python -m pip install dbt-core
 ```
+
 ### Change dbt Core versions
 
 You can upgrade or downgrade versions of dbt Core by using the `--upgrade` option on the command line (CLI). For more information, see [Best practices for upgrading in Core versions](/docs/dbt-versions/core#best-practices-for-upgrading).

diff --git a/website/docs/docs/core/source-install.md b/website/docs/docs/core/source-install.md
@@ -12,28 +12,58 @@ Downloading and building dbt Core will enable you to contribute to the project b
 
 ### Installing dbt Core
 
-To install `dbt-core` from the GitHub code source:
+Beginning in v1.8, installing an adapter does not automatically install `dbt-core`. This is because adapters and dbt Core versions have been decoupled from each other so we no longer want to overwrite existing dbt-core installations
+
+<VersionBlock firstVersion="1.8">
+
+To install `dbt-core` only from the GitHub code source:
+
+```shell
+git clone https://github.com/dbt-labs/dbt-core.git
+cd dbt-core
+python -m pip install -r requirements.txt
+```
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.7">
+
+To install `dbt-core` and `dbt-postgres` from the GitHub code source:
 
 ```shell
 git clone https://github.com/dbt-labs/dbt-core.git
 cd dbt-core
 python -m pip install -r requirements.txt
 ```
+</VersionBlock>
 
-This will install `dbt-core` and `dbt-postgres`. To install in editable mode (includes your local changes as you make them), use `python -m pip install -e editable-requirements.txt` instead.
+To install in editable mode, which includes your local changes as you make them:
+
+```shell
+python -m pip install -e editable-requirements.txt` instead.
+```
 
 ### Installing adapter plugins
 
-To install an adapter plugin from source, you will need to first locate its source repository. For instance, the `dbt-redshift` adapter is located at https://github.com/dbt-labs/dbt-redshift.git, so I can clone it and install from there:
+To install an adapter plugin from source, you will need to first locate its source repository. For instance, the `dbt-redshift` adapter is located at https://github.com/dbt-labs/dbt-redshift.git, so you can clone it and install from there:
+
+<VersionBlock firstVersion="1.8">
+
+You will also need to install `dbt-core` before installing an adapter plugin.
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.7">
+
+You do _not_ need to install `dbt-core` before installing an adapter plugin -- the plugin includes `dbt-core` among its dependencies, and it will install the latest compatible version automatically.
+</VersionBlock>
 
 ```shell
 git clone https://github.com/dbt-labs/dbt-redshift.git
 cd dbt-redshift
 python -m pip install .
 ```
 
-You do _not_ need to install `dbt-core` before installing an adapter plugin -- the plugin includes `dbt-core` among its dependencies, and it will install the latest compatible version automatically.
-
 To install in editable mode, such as while contributing, use `python -m pip install -e .` instead.
 
 <FAQ path="Core/install-pip-os-prereqs" />

diff --git a/website/snippets/_setup-pages-intro.md b/website/snippets/_setup-pages-intro.md
@@ -12,9 +12,20 @@
 
 <h2> Installing {props.meta.pypi_package}</h2>
 
-Use `pip` to install the adapter, which automatically installs `dbt-core` and any additional dependencies. Use the following command for installation:
+Use `pip` to install the adapter. Before 1.8, installing the adapter would automatically install `dbt-core` and any additional dependencies. Beginning in 1.8, installing an adapter does not automatically install `dbt-core`. This is because adapters and dbt Core versions have been decoupled from each other so we no longer want to overwrite existing dbt-core installations.
+Use the following command for installation:
+<VersionBlock firstVersion="1.8">
+
+<code>python -m pip install dbt-core {props.meta.pypi_package}</code>
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.7">
+
 <code>python -m pip install {props.meta.pypi_package}</code>
 
+</VersionBlock>
+
 <h2> Configuring {props.meta.pypi_package} </h2>
 
 <p>For {props.meta.platform_name}-specific configuration, please refer to <a href={props.meta.config_page}>{props.meta.platform_name} configs.</a> </p>