Skip to content

Commit

Permalink
Update use cases for 'local' packages (#4048)
Browse files Browse the repository at this point in the history
Context:
dbt-labs/dbt-core#8541 (comment)

## What are you changing in this pull request and why?

There are multiple legitimate use cases for 'local' packages, beyond the
one that's currently documented — especially as we see more
multi-project setups.
  • Loading branch information
mirnawong1 authored Sep 8, 2023
2 parents e7c6182 + 9d4f491 commit ae63f53
Showing 1 changed file with 20 additions and 3 deletions.
23 changes: 20 additions & 3 deletions website/docs/docs/build/packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -284,18 +284,35 @@ packages:
</File>

### Local packages
Packages that you have stored locally can be installed by specifying the path to the project, like so:
A "local" package is a dbt project accessible from your local file system. You can install it by specifying the project's path. It works best when you nest the project within a subdirectory relative to your current project's directory.

<File name='packages.yml'>

```yaml
packages:
- local: /opt/dbt/redshift # use a local path
- local: relative/path/to/subdirectory
```
</File>
Local packages should only be used for specific situations, for example, when testing local changes to a package.
Other patterns may work in some cases, but not always. For example, if you install this project as a package elsewhere, or try running it on a different system, the relative and absolute paths will yield the same results.
<File name='packages.yml'>
```yaml
packages:
# not recommended - support for these patterns vary
- local: /../../redshift # relative path to a parent directory
- local: /opt/dbt/redshift # absolute path on the system
```
</File>
There are a few specific use cases where we recommend using a "local" package:
1. **Monorepo** &mdash; When you have multiple projects, each nested in a subdirectory, within a monorepo. "Local" packages allow you to combine projects for coordinated development and deployment.
2. **Testing changes** &mdash; To test changes in one project or package within the context of a downstream project or package that uses it. By temporarily switching the installation to a "local" package, you can make changes to the former and immediately test them in the latter for quicker iteration. This is similar to [editable installs](https://pip.pypa.io/en/stable/topics/local-project-installs/) in Python.
3. **Nested project** &mdash; When you have a nested project that defines fixtures and tests for a project of utility macros, like [the integration tests within the `dbt-utils` package](https://github.com/dbt-labs/dbt-utils/tree/main/integration_tests).


## What packages are available?
Check out [dbt Hub](https://hub.getdbt.com) to see the library of published dbt packages!
Expand Down

0 comments on commit ae63f53

Please sign in to comment.