[Bug] Clarification of implementing dbt-tests-adapter for adapters

[cody-scott]

Is this a new bug?

• I believe this is a new bug
• I have searched the existing issues, and I could not find an existing issue for this bug

Current Behavior

The current documentation around implementing the correct dbt-test-adapters is unclear.

The adapter creation guide mentions the dbt-tests-adapter (as part of this repo) https://docs.getdbt.com/guides/adapter-creation?step=4; there is also a dbt-tests-adapter package which looks to be maintained on pypi https://pypi.org/project/dbt-tests-adapter/ which might just be the built version of the link?

The cookiecutter also clones and references the tests adapter as part of the core project, not the adapters project, which pins the project to the latest main branch (1.9.0a1 at the current moment) which is problematic for developing against the stable version.

Expected Behavior

Improved clarity around how adapter developers should be loading in the appropriate version for core/adapters in their projects. Perhaps a flag in the cookiecutter to also pin the development version to a specific version (1.8.latest for example).

Ideally for a developer if they can clone the pypi package and avoid the git+ clones it might be clearer.

Steps To Reproduce

NA

Relevant log output

No response

Environment

- OS:
- Python:
- dbt-adapters:

Additional Context

No response

[dbeatty10]

Thanks for reaching out @cody-scott ! 🏆

You are correct that this repo has multiple packages that are released on PyPI. One of them is dbt-tests-adapter, and its source code is rooted here.

It sounds like you ran into a couple different things while upgrading dbt-sqlserver to be compatible with dbt-core v1.8. But I'm not seeing anything that you're suggesting we change in the dbt-adapters specifically -- is that right?

If you have any feature requests or bugs related to the cookiecutter template, could you please open up separate issue(s) here?

• https://github.com/dbt-labs/dbt-database-adapter-scaffold

If you have suggested updates to the guide for building, testing, documenting, and promoting adapters, could you open separate issue(s) here?

• https://github.com/dbt-labs/docs.getdbt.com

That would help us get all the suggestions in the right places.

[cody-scott]

Correct. Not an issue, but rather more of clarification on the docs side.

Example is should users clone from the git repo, or pypi. We opted for pypi pinning to the same 1.8 dbt version, and plan on doing the same for 1.9.

Cookiecutter suggests repo, which is equally correct?

Seems sorted in our case but might be helpful for others in the future implementations.

As an aside the new test framework has been great to work with vs the older one!

[dbeatty10]

As an aside the new test framework has been great to work with vs the older one!

Awesome to hear! 🤩

Example is should users clone from the git repo, or pypi. We opted for pypi pinning to the same 1.8 dbt version, and plan on doing the same for 1.9.

Cookiecutter suggests repo, which is equally correct?

This is the approach you took, right?

dbt-tests-adapter>=1.8.0, <1.9.0

I can see how this would be useful to only run the tests that have been released in PyPI and align with the version range of dbt-adapters that you are targeting.

Adapters maintained by dbt Labs

This is how we do it for dbt-snowflake:

git+https://github.com/dbt-labs/dbt-adapters.git#subdirectory=dbt-tests-adapter

When doing development, then we can temporarily change the specific branch that a change is being tested against as-needed:

git+https://github.com/dbt-labs/dbt-adapters.git@BRANCH_NAME#subdirectory=dbt-tests-adapter

Preparing an adapter for an upcoming release of dbt

We don't currently have any 1.8.latest or 1.9.latest branches within dbt-adapters, but if we did, then you could also do something like this:

git+https://github.com/dbt-labs/dbt-adapters.git@1.8.latest#subdirectory=dbt-tests-adapter

This approach is especially useful if you are preparing your adapter to be ready for an upcoming release of dbt-adapters or dbt-core before it is released.