Skip to main content

Documenting a new adapter

If you've already built, and tested your adapter, it's time to document it so the dbt community will know that it exists and how to use it!

General Guidelines​

To best inform the dbt community of the new adapter, you should contribute to the dbt's open-source documentation site, which uses the Docusaurus project. This is the site you're currently on!

Conventions​

Each .md file you create needs a header as shown below. The document id will also need to be added to the config file: website/sidebars.js.

---
title: "Documenting a new adapter"
id: "documenting-a-new-adapter"
---

Single Source of Truth​

We ask our adapter maintainers to use the docs.getdbt.com repo (i.e. this site) as the single-source-of-truth for documentation rather than having to maintain the same set of information in three different places. The adapter repo's README.md and the data platform's documentation pages should simply link to the corresponding page on this docs site. Keep reading for more information on what should and shouldn't be included on the dbt docs site.

Assumed Knowledge​

To simplify things, assume the reader of this documentation already knows how both dbt and your data platform works. There's already great material for how to learn dbt and the data platform out there. The documentation we're asking you to add should be what a user who is already profiecient in both dbt and your data platform would need to know in order to use both. Effectively that boils down to two things: how to connect, and how to configure.

Topics and Pages to Cover​

The following subjects need to be addressed across three pages of this docs site to have your data platform be listed on our documentation. After the corresponding pull request is merged, we ask that you link to these pages from your adapter repo's REAMDE as well as from your product documentation.

To contribute, all you will have to do make the changes listed in the table below.

How To...File to change within /website/docs/ActionInfo to Include
Connectreference/warehouse-profiles/{MY-DATA-PLATOFRM}-profile.mdCreateGive all information needed to define a target in ~/.dbt/profiles.yml and get dbt debug to connect to the database successfully. All possible configurations should be mentioned.
Configurereference/resource-configs/{MY-DATA-PLATOFRM}-configs.mdCreateWhat options and configuration specific to your data platform do users need to know? e.g. table distribution and indexing options, column_quoting policy, which incremental strategies are supported
Discover and Installdocs/available-adapters.mdModifyIs it a vendor- or community- supported adapter? How to install Python adapter package? Ideally with pip and PyPI hosted package, but can also use git+ link to GitHub Repo
Add link to sidebarwebsite/sidebars.jsModifyAdd the document id to the correct location in the sidebar menu

For example say I want to document my new adapter: dbt-ders. For the "Connect" page, I will make a new Markdown file, ders-profile.md and add it to the website/docs/reference/warehouse-profiles/ directory.

Example PRs to add new adapter documentation​

Below are some recent pull requests made by partners to document their data platform's adapter: