dbtenv is a version manager for dbt, automatically installing and switching to the needed adapter and version of dbt.
Project description
dbtenv
dbtenv is a version manager for dbt, automatically installing and switching to the needed adapter and version of dbt.
Quickstart
Installation
- Install pipx (What is pipx?).
- Run
pipx install dbtenv[dbt-alias]
.
Usage
If the dbt-alias
extra is used (dbtenv[dbt-alias]
), dbt commands can be used as normal and will be routed through dbtenv. dbtenv will automatically determine, install and use the required dbt adapter and version.
Illustrative example
dbt --version
dbtenv info: Using dbt-bigquery==1.0.0 (set by dbt_project.yml).
installed version: 1.0.4
latest version: 1.0.4
Up to date!
Plugins:
- bigquery: 1.0.0 - Up to date!
Available Commands
dbtenv --help
- Print documentation and available commands. Can also be run for information on a individual command, e.g.dbtenv versions --help
.dbtenv versions
- List the installable versions of dbt, marking those which are currently installed. Add the--installed
flag to show only those which are installed.dbtenv install <dbt_pip_specifier>
- Install a specific version of dbt, e.g.dbtenv install dbt-snowflake==1.0.0
.dbtenv uninstall <dbt_pip_specifier>
- Uninstall a specific version of dbt, e.g.dbtenv uninstall dbt-snowflake==1.0.0
.dbtenv version
- Print the dbt version dbtenv determines automatically for the current environment.dbtenv which
- Print the full path to the executable of the dbt version dbtenv determines automatically for the current environment.dbtenv execute
- Execute a dbt command.
dbt Version Management
dbtenv will automatically install the required version of dbt for the current project by default. To disable this behaviour, set the environment variable DBTENV_AUTO_INSTALL
to false
.
By default, dbtenv creates virtual environments for each dbt package version within ~/.dbt/versions
. You can customize this location by setting the DBTENV_VENVS_DIRECTORY
environment variable.
By default, dbtenv uses whichever Python version it was installed with to install dbt, but that can be changed by setting a DBTENV_PYTHON
environment variable to the path of a different Python executable, or specifying --python <path>
when running dbtenv install
.
Switching between dbt versions
Adapter type
If dbtenv is invoked within a dbt project, dbtenv will look for the project's default target adapter type in profiles.yml
. If dbt's --target
argument is set, dbtenv will use that target's adapter type instead. To use the dbtenv execute
command outside of a dbt project (such as dbt init
), a pip specifier should be passed to dbtenv execute's --dbt
argument so that dbtenv knows which adapter to use.
dbt version
dbtenv determines the dbt version to use from the following sources, using the first one it finds:
-
The
dbtenv execute
command's optional--dbt <version>
argument. -
The
DBT_VERSION
environment variable. -
If not running within a dbt project:
- The first
.dbt_version
file found searching the working directory path (local version). - The
~/.dbt/version
file (global version).
- The first
-
The current dbt project's dbt_project.yml version requirements.
- If a local or global dbt version has been set, dbtenv will use that version if in the range set by
require-dbt-version
.
- If a local or global dbt version has been set, dbtenv will use that version if in the range set by
-
The locally or globally set version.
-
The max installed dbt version (preferring stable versions).
-
The max installable dbt version (preferring stable versions).
You can:
- Run
dbtenv version --global <version>
to set the dbt version globally in the~/.dbt/version
file. The<version>
can be either a dbt version (e.g. 1.0.0) or full pip specifier (e.g. dbt-snowflake==1.0.0). dbtenv will attempt to automatically detect the required adapter or version from the environment if not specified. - Run
dbtenv version --local <version>
to set the dbt version for the current directory in a.dbt_version
file. The<version>
can be either a dbt version (e.g. 1.0.0) or full pip specifier (e.g. dbt-snowflake==1.0.0). dbtenv will attempt to automatically detect the required adapter or version from the environment if not specified.
Running dbt through dbtenv
dbt-alias
The dbtenv-dbt-alias
package creates an entrypoint for the dbt
command to route through dbtenv. The package is installable using the [dbt-alias]
extra when installing dbtenv. The dbt
command then acts as a direct shortcut to dbtenv execute --
, and means that dbtenv can used as a drop-in replacement to installing dbt normally.
dbtenv execute
Run dbtenv execute -- <dbt arguments>
to execute the dbt version determined automatically from the current environment, or run dbtenv execute --dbt <version> -- <dbt arguments>
to execute a specific dbt version.
For example:
dbtenv execute -- run
will executedbt run
using the version determined automatically from the current environment.dbtenv execute --dbt 1.0.0 -- run
will executedbt run
using dbt 1.0.0, automatically detecting the required adapter from the default target inprofiles.yml
.dbtenv execute --dbt 1.0.0 -- run --target prod
will executedbt run
using dbt 1.0.0, using the required adapter for the 'prod' target inprofiles.yml
.dbtenv execute --dbt 1.0.0==dbt-bigquery -- run
will executedbt run
using dbt-bigquery==1.0.0.
Development
Development setup
- Clone this repository onto your computer.
- Install Poetry
pipx install poetry
(What is pipx?) - Navigate to the
dbtenv
directory, and install the project into a virtual environmentpoetry install
- Activate the virtual environment
poetry shell
- Any
dbtenv
commands will run using the local version of the project.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.