dbt-codegen prints the YAML and SQL you would have hand typed

A macro package that writes to stdout instead of to files

dbt-codegen is a dbt package whose whole job is generating dbt code and printing it. The README states it plainly: macros that generate dbt code, and log it to the command line. There is no file writing, no scaffolding of directories, and no state kept between runs. The output is text you read, copy and paste into a schema file or a model.

That constraint shapes everything else. It means the package composes with the tools you already use for review. Generated YAML lands in a pull request like any other change, and the person who pastes it can adjust the descriptions, the formatting and the column names before anyone sees it. It also means there is no regeneration step, so a source definition that was hand corrected does not get overwritten by a later run, and it does not get updated when the upstream table changes either.

The package is hosted on the dbt Hub at hub.getdbt.com, under the dbt-labs organization, and the repository carries the standard dbt package layout: a dbt_project.yml, a macros directory, a packages.yml, integration tests, a tox.ini, a CHANGELOG.md and a RELEASE.md. The licence is Apache-2.0.

The people who benefit are analytics engineers and data teams that are tired of typing YAML skeletons for a warehouse they have just landed data into, and who would rather describe a schema than format it by hand.

generate_source covers fifteen arguments and a case sensitivity story

The generate_source macro is the entry point, and it takes a long argument list. Only schema_name is required, the name of the schema holding the source data. database_name defaults to target.database, so it inherits the target from your project. table_names is optional, and when you leave it out the macro works across the schema and relies on table_pattern, which defaults to the percent wildcard, to select tables. The exclude argument takes a string to filter the selection, and name defaults to the schema name so the generated source inherits it.

The boolean flags control the detail level. generate_columns defaults to False, so column names are not added unless asked for. include_descriptions defaults to False and adds description placeholders, and include_data_types defaults to True, which means the column detail includes types unless you turn it off. include_database and include_schema default to False, so the generated source is lean unless you ask it to be explicit.

The most interesting group is the case sensitivity set. case_sensitive_databases, case_sensitive_schemas, case_sensitive_tables and case_sensitive_cols all default to False, which lowercases the names. Setting one of them to True keeps the case as it appears in the source table, and the documentation notes that the database, schema and table variants are not compatible with Redshift. That is a concrete adapter boundary rather than a vague caution.

Note the history embedded in the arguments. The README explains that to include column names without data types, which is the behavior of dbt-codegen at version 0.9.0 or earlier, you set generate_columns to true and include_data_types to false. The flag defaults have changed across versions, which matters when you compare an old run with a new one.

Two ways to call it: compile in a file or run it as an operation

The macro can be invoked in two ways, and the choice is about where the output goes.

The first is to paste the macro into a statement tab in the dbt Cloud IDE, or into an analysis file, and compile the code. That gives you the generated output inside the IDE, in a context where you can read it before you commit to it:

{{ codegen.generate_source('raw_jaffle_shop') }}

or with named arguments:

{{ codegen.generate_source(schema_name= 'jaffle_shop', database_name= 'raw') }}

The second is to call it as an operation from the command line, which is the form you want in scripts and in CI:

$ dbt run-operation generate_source --args 'schema_name: raw_jaffle_shop'

With multiple arguments, the dict syntax is the form to use:

$ dbt run-operation generate_source --args '{"schema_name": "jaffle_shop", "database_name": "raw", "table_names":["table_1", "table_2"]}'

The single-argument form shown earlier uses the YAML style args syntax, which is worth remembering because the two are not interchangeable, and the error you get from mixing them up is a parse error rather than a helpful message.

Both forms end the same way. The YAML is logged to the command line, and you paste it into a schema yml file and refactor as required. The generated shape for a raw jaffle shop schema looks like this:

version: 2

sources:
  - name: raw_jaffle_shop
    database: raw
    schema: raw_jaffle_shop
    tables:
      - name: customers
        description: ""

The empty description strings are the default, which is exactly why the refactoring step is part of the documented flow rather than an optional extra.

Piping the log into a file with the --quiet flag

The one piece of automation the package documents is a piping trick that turns the command line output into a real file. Because the macro logs the YAML rather than printing it as the only output, redirecting stdout alone leaves the log noise mixed in, so the README pairs the redirect with the --quiet CLI flag:

dbt --quiet run-operation generate_source --args '{"table_names": ["orders"]}' > models/staging/jaffle_shop/_sources.yml

The result is a schema file written to the path you choose, in the staging directory of the project, named _sources.yml with the leading underscore, a convention that keeps dbt from treating the file as a model. This is what makes the package usable in a scaffolding script: one command produces a file you can then edit, commit and review.

It is still a manual step in the sense that nothing in the package tracks the file afterwards. Re-running the command overwrites whatever is at that path, including any descriptions or column edits you made by hand, so the safe pattern is to treat the file as generated scratch output that you then copy and edit, not as a file that lives under regeneration.

If you need the file to stay accurate as the warehouse changes, that is where this approach ends and a maintenance script of your own begins.

Base models, import CTEs and a unit test template

Beyond sources, the package covers the next steps of a dbt project. generate_base_model writes the SQL for a base model over an existing source, and it takes source_name and table_name as required arguments. leading_commas toggles between leading and trailing comma style, case_sensitive_cols keeps the source column casing, and materialized sets the materialization, for example table, view or incremental, inside the model's config block. If you leave it unset, the materialization is controlled by dbt_project.yml instead.

Calling it in a statement tab or analysis file looks like this:

{{ codegen.generate_base_model(
    source_name='raw_jaffle_shop',
    table_name='customers',
    materialized='table'
) }}

The operation form is the same shape as the source one:

$ dbt run-operation generate_base_model --args '{"source_name": "raw_jaffle_shop", "table_name": "customers"}'

The generated SQL follows the staged CTE pattern, selecting from a source relation inside a with clause and then renaming in a following stage.

The package also lists create_base_models, base_model_creation, generate_model_yaml, generate_model_import_ctes and generate_unit_test_template in its contents. The last of these is the one to look at if you are moving a project onto dbt unit tests, since a template gives you a starting shape for a test file. The README excerpt that was available here covers the source and base model macros in full argument detail, so treat the remaining ones as present but check the package documentation on dbt Hub for their parameters before you rely on a specific flag.

Packaging, tests and the adapters the project targets

Installing the package is a two step operation in any dbt project. You add it to packages.yml, pinning the version you want, and the README shows the shape:

packages:
  - package: dbt-labs/codegen
    version: X.X.X ## update to latest version here

Then you run dbt deps to fetch it. The README points newcomers to the dbt package management documentation for the wider picture, which is the right place to read about what a package can override in your project.

The repository is set up for multi adapter testing. The Makefile exposes a help target that greps its own comments, a test target that runs the run_test.sh script, a tox based variant, a dev target that installs dbt-core and the adapter for the target you name, and a setup-db target that brings up Postgres with docker-compose for system testing. The compose file pins cimg/postgres:17.0 and publishes port 5432, and the file supported_adapters.env at the root records which adapters the test matrix covers. Integration tests live in integration_tests, and tox.ini drives the matrix.

The primary language recorded for the repository is Makefile, which is a sign of how much of the automation here is shell and make driven rather than Python.

Release cadence is steady without being fast. Version 0.14.0 was published on 2025-11-13, 0.14.1 on 2026-05-07, and 0.13.1 on 2024-12-04. The last push was on 2026-10-01, so the repository is being worked on even when a release is months old.

The alternative is a schema file you write and keep

The obvious alternative to dbt-codegen is the thing it replaces: a hand maintained schema file. You write the YAML, you describe the columns, you commit it, and when the warehouse changes you edit it. There is no generation step, no pasted draft and no empty description fields to clean up, and the file in version control is a complete description rather than a starting point.

The difference in approach is where the effort goes. Codegen moves typing into a one-off command that reads the warehouse and prints structure, so the human effort shifts to reviewing and enriching what comes out. Hand writing keeps the human effort in the authoring and pays it again on every change.

For a single stable source table, hand writing wins on effort and on clarity. For twenty tables in a landing zone that a team just created, where every column needs listing and nobody has written a word of documentation, generating the skeleton and then editing it is less total work.

The other alternative worth naming is doing the generation yourself, in a Python script that queries the warehouse and writes YAML directly with a YAML library. That gives you exactly the files you want, on a schedule, without a dbt dependency in the loop, and it also gives you the responsibility for connection handling, credential management and adapter quirks that the macro handles for you. For a team that already has a Python job runner and a house style for generated files, that is a reasonable trade. For a team that only wants dbt to work, adding a second language to the pipeline is a cost the package avoids.

Editorial conclusion

Adopt dbt-codegen if you stand up many dbt projects, keep landing zones in a warehouse you do not want to hand document column by column, and are willing to treat the generated YAML as a first draft that a human refactors. Do not adopt it if your team wants generated files to be the source of truth, since the package logs to the command line and leaves the pasting and refactoring to you, and do not rely on it for Redshift projects that need case sensitive naming, which the case_sensitive arguments are documented as incompatible with. Before running it, pin the package version in packages.yml, confirm your adapter works with the generate_columns and include_data_types defaults, and review the empty description fields the macro emits by default.

Frequently asked questions

Official sources

1. dbt-labs/dbt-codegen on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases