dbt-checkpoint moves dbt project hygiene into the pre-commit hook

The problem is not broken SQL, it is incomplete project files

dbt-checkpoint is a collection of pre-commit hooks for dbt projects, written in Python and distributed as a pre-commit hook repository. The project documentation is clear about the failure mode it targets. As the number of models, sources and macros in a project grows, keeping the same quality level across developers becomes hard. People forget to update columns in property yml files, or forget to add table and column descriptions. Reviewer workload grows and unintended errors slip through.

The remedy is to run the same validation on every developer's machine, at commit time, rather than discovering the omission during review. Every hook is a single named check, listed in HOOKS.md, and the naming pattern makes the coverage easy to read: check-model-has-description, check-model-columns-have-desc, check-model-has-properties-file, check-model-has-contract.

This is a static check on project files, not a test of your data. That distinction decides where the tool belongs. It catches a model that has no description, a column that is missing from a properties file, or a model whose contract or constraints were never defined. It does not tell you whether a transformation returns the right numbers.

Hooks read the dbt manifest and catalog, which is why the project root matters

The hooks work from the artifacts dbt produces. When you point the tool at a dbt project, it looks for the required manifest and catalog inside that project folder, and reads from there to decide what a model contains and what its property file declares.

That is the mechanism behind several of the checks. A hook that verifies every column of a model has a description can only do that by comparing the model columns from the catalog with the descriptions in the yml files. A hook that checks a model has all the columns listed in its properties file is comparing the same two sources. The same pattern covers meta keys, labels, constraints, generic constraints, and tests by name or by type.

The manifest and catalog are not committed, they are generated. So the hooks depend on a dbt project that has been parsed, and the tool needs to know where that project lives. The configuration file at the repository root, .dbt-checkpoint.yaml, carries a dbt-project-dir key for exactly this situation, and the documentation gives a concrete example for a project that lives in a sub-directory of the repository rather than at its root.

The exclude rules that pre-commit and dbt-checkpoint handle differently

One behaviour is worth understanding before you configure anything. Since dbt-checkpoint 1.1.0, certain hooks implement an implicit logic that discovers the sql or yml file related to what is being checked, so you do not have to list every related file in your pre-commit configuration yourself.

The catch is how that interacts with pre-commit's own exclude handling. The root-level exclude statement is handled by pre-commit, and when the hooks discover their related sql and yml files, that root exclusion is omitted, meaning dbt-checkpoint re-includes files that pre-commit had excluded. To stop that, the exclude path or regex has to be provided inside each hook rather than only at the root. The project documentation points at issue 118 for the background and pull request 119 for the per-hook form.

For a team that excludes generated models or vendored paths at the root of the pre-commit config, this is the kind of detail that produces a confusing first run: a file that looks excluded reappears in a hook failure. The fix is local, but it is per hook and per path.

Telemetry ships enabled and the opt-out is a single config key

Some of the hooks include telemetry, and the project documentation explains why: the maintainers at Datacoves want to know which hooks are used and which are not, so that they can prioritise future development of dbt-checkpoint. Datacoves is the company behind the project and the sponsor named in the README.

The scope is narrow and worth reading carefully before deciding. Credentials are not tracked, and neither are details of dbt execution such as model names. The dbt hooks that generate documentation are not tracked either. The one dbt related detail used is the anonymous user_id that dbt generates, which is used to tell distinct projects apart.

Tracking is on by default, and turning it off means adding one key to the .dbt-checkpoint.yaml file:

version: 1
disable-tracking: true

That is the whole opt-out. No environment variable, no second file, no restart. The default matters for a project with a strict policy on what leaves a developer machine, and the choice is easy to make now that it is written down in the same file that carries the rest of the configuration.

Configuring the project directory and running the first hook

The configuration file is .dbt-checkpoint.yaml, and it starts with a version key. When the dbt project sits in a sub-directory, the dbt-project-dir key tells every hook where to look, which removes the need to repeat a manifest flag on each hook:

version: 1
dbt-project-dir: my_dbt_project

With that in place, the tool looks for the manifest and catalog inside the my_dbt_project folder automatically. The alternative, as the documentation puts it, is passing a manifest flag to every hook individually.

The hooks themselves are installed the standard pre-commit way. The repository root contains .pre-commit-hooks.yaml, the manifest pre-commit reads to learn which hooks a repository provides, alongside a .pre-commit-config.yaml for the project's own development, and a .dbt-checkpoint.yaml with a default configuration. The README section on hooks links each hook name to its entry in HOOKS.md, where the details of that specific check live.

A sensible first run is one hook, on the model you most often forget to document. The check-model-has-description hook is the smallest useful example, and check-model-columns-have-desc is the stricter version of the same idea once descriptions exist but are missing on individual columns. The hook list is long enough that adding all of them at once is a good way to get a wall of failures on the first commit.

Where the checks stop, and how dbt's own tests differ

The boundary of the tool is clear once you see what a hook can know. It reads files and artifacts. It can tell you that a column is missing from a properties file, that a model has no description, or that a contract was never defined. It cannot tell you that a model is slow, that a test fails against warehouse data, or that a transformation is wrong, because the hooks do not query your database.

That is the difference from the alternative that already lives in a dbt project. dbt itself has a test layer that runs against the warehouse, and several of the dbt-checkpoint hooks exist precisely to verify that you have used it: check-model-has-tests-by-name and check-model-has-tests-by-type check the tests a model declares, and check-model-has-contract and the constraint hooks check the enforcement metadata. The dbt-checkpoint approach is a file-level gate that runs before the commit, on every machine, with no warehouse connection. The dbt test approach runs later, against real data, in CI.

The two are complements rather than rivals, and the ordering matters. Hooks fail fast on structure, tests fail on behaviour. If your team wants dbt tests to be the standard, check-model-has-tests-by-type is the hook to enforce it, and the warehouse run is where the actual assertions live.

On upkeep, the project is released under the MIT licence, the last push to the repository was on 2026-08-17, and recent releases include v2.0.10 on 2026-06-18, v2.0.9 on 2026-05-01 and v2.0.8 on 2026-02-06. The repository carries a CHANGELOG.md, and the Python packaging is minimal, with setup.py calling setup and the details in setup.cfg.

Editorial conclusion

dbt-checkpoint fits a dbt team that keeps property files, contracts and tests in version control and wants those checks to run before review, and it is the wrong tool for a team that wants validation against real data in the warehouse. Verify first that the hooks run against the manifest and catalog your dbt version produces, decide on the disable-tracking key in .dbt-checkpoint.yaml, and set dbt-project-dir if the dbt project is not at the repository root.

Frequently asked questions

Official sources

1. dbt-checkpoint/dbt-checkpoint on GitHub
2. Issues
3. License: MIT
4. README
5. Releases