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 index 470445891dc..ac8cdf8819b 100644 --- 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 index 2e2676c4a95..d1d3a482f79 100644 --- 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-`. 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 ``, 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,7 +51,7 @@ To upgrade dbt, use: ```shell brew update -brew upgrade dbt- +brew upgrade dbt-ADAPTER_NAME ``` ### Switching versions @@ -59,9 +59,9 @@ brew upgrade dbt- 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- -brew install dbt-@1.0.0 -brew link dbt-@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: - - : 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-@1.0.0 -brew link dbt-@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 index e1a0e65312c..4fc032da58e 100644 --- a/website/docs/docs/core/pip-install.md +++ b/website/docs/docs/core/pip-install.md @@ -3,7 +3,7 @@ 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/). @@ -11,12 +11,13 @@ You can install dbt Core and plugins using `pip` because they are Python modules ### 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 with the path to your virtual environment configuration. @@ -36,10 +38,31 @@ alias env_dbt='source /bin/activate' ``` ### Installing the adapter -Once you know [which adapter](/docs/supported-data-platforms) you're using, you can install it as `dbt-`. 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. + + ```shell -python -m pip install dbt-postgres +python -m pip install dbt-core dbt-ADAPTER_NAME +``` + + + + + +```shell +python -m pip install dbt-ADAPTER_NAME +``` + + + +For example, if using Postgres: + + + +```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. + + + + +```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. + ### Upgrade adapters To upgrade a specific adapter plugin: ```shell -python -m pip install --upgrade dbt- +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 index d17adc13c53..0f2e532f36e 100644 --- a/website/docs/docs/core/source-install.md +++ b/website/docs/docs/core/source-install.md @@ -12,19 +12,51 @@ 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 + + + +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 +``` + + + + + +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 ``` + -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: + + + +You will also need to install `dbt-core` before installing an adapter plugin. + + + + + +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. + ```shell git clone https://github.com/dbt-labs/dbt-redshift.git @@ -32,8 +64,6 @@ 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. diff --git a/website/snippets/_setup-pages-intro.md b/website/snippets/_setup-pages-intro.md index 5ded5ba5ebc..c3fd011389a 100644 --- a/website/snippets/_setup-pages-intro.md +++ b/website/snippets/_setup-pages-intro.md @@ -12,9 +12,20 @@

Installing {props.meta.pypi_package}

-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: + + +python -m pip install dbt-core {props.meta.pypi_package} + + + + + python -m pip install {props.meta.pypi_package} + +

Configuring {props.meta.pypi_package}

For {props.meta.platform_name}-specific configuration, please refer to {props.meta.platform_name} configs.