dbt init Command: Starting New Projects

If you’re just getting started with dbt (Data Build Tool), you’ve probably seen the command dbt init pop up in tutorials or documentation. And wonder, what does it actually do, why is it such a big deal? Today, in this blog, I will break it down for you.

Think of dbt init as the official starting line for any dbt project. It’s like opening a brand-new notebook when you’re about to start a big project, clean, structured, and ready to go.

What Happens When You Run dbt init

So, you’re at your terminal and you type:

dbt init hevo_data_project

After running the above command, you’ve just kicked off your very first dbt project. But what’s really happening behind the scenes? Let’s walk through it together.

1. A New Project Folder is Created

Running dbt init basically creates a folder named after your project, in this case, hevo_data_project. This will be your main project directory. Inside it, dbt sets up all the essential files and folders you’ll need.

2. Core Project Files Are Added

Here’s what you’ll see inside:

• dbt_project.yml
  This file is like your project’s blueprint. It defines your project’s name, where your models live, and other configs.
• models/ directory
  This folder is where all your dbt models live. You’ll find a simple starter model here (example.sql) to help you test that things are working.
  

3. You’ll Be Asked About Your Data Warehouse

As part of dbt init, dbt will prompt you to choose your data warehouse, like BigQuery, Snowflake, Redshift, Postgres, or others. Based on your selection, it generates a connection profile.

This connection info doesn’t live in the project folder. It’s stored separately in a file called profiles.yml.

4. You’re Guided Through Basic Setup

dbt asks you a few basic questions like:

• What’s your target schema or database?
• How should dbt authenticate with your warehouse?
• Which development environment are you using?

Once done, your project is fully bootstrapped and ready for action.

What Next?

Once you’ve initialized your project, configured your connection, and you’re staring at that models/ folder wondering, “Now what?”

Here’s your step-by-step guide to taking action with your fresh dbt project. 

1. Run dbt debug

Before doing anything else, make sure everything is configured correctly:

dbt debug

The dbt debug command checks if:

• Your profiles.yml is set up properly
• dbt can connect to your data warehouse
• Your project structure is valid

If everything’s green, you’re ready to move on!

2. Run Your First Model

In the models/example/ folder, there’s a file named my_first_dbt_model.sql. It looks simple, like:

SELECT 1 AS id

But when you run:

dbt run

dbt will:

• Parse that SQL file
• Run it against your data warehouse
• Create a table (or view, depending on your settings)

You’ve officially deployed your first dbt model.

 3. Explore the Docs Locally

One of dbt’s coolest features is its automatic documentation generator using the dbt docs command.

Run these two commands:

dbt docs generate
dbt docs serve

This will:

• Generate docs for all your models
• Launch a local website where you can click through them

You’ll see:

• Model descriptions
• SQL logic
• Lineage graphs
• Dependencies

It’s like an interactive wiki for your data models.

4. Add a New Model

Ready to try your own transformation?

Create a new SQL file in models/, like this:

touch models/orders_cleaned.sql

Add your transformation logic. For example:

SELECT * FROM raw.orders WHERE status != 'cancelled'

Then run:

dbt run

dbt will build the new model in your warehouse automatically.

5. Clean Your Warehouse (Optional)

Want to remove models you’ve built during testing? Run:

dbt clean

The dbt clean command helps reset your local environment if you’re starting fresh.

And that’s it in just a few minutes, you’ve:

• Set up a project
• Connected to your warehouse
• Built your first dbt model
• Served auto-generated docs
• Written your first transformation

Best Practices When Starting a New dbt Project

When you’re just getting started, it’s tempting to dive right into writing SQL. But trust me, spending a little time upfront setting up good habits will save you hours of cleanup later.

Here are some best practices you should follow after running dbt init.

1. Use Clear and Consistent Naming Conventions

Consistency is king in dbt. Adopt clear naming rules for:

• Model files (stg_customers.sql, int_orders_cleaned.sql, dim_product.sql)
• Filenames and model names should match (e.g., file customers.sql should define select * from customers as customers)
• Stick to prefixes: stg_, int_, dim_, fct_, etc., depending on your modeling layer

This makes it easier to understand the model’s purpose at a glance. For even more organization beyond naming conventions, check out our guide on using dbt tags to organize your project.

2. Organize Models by Layer

Don’t keep all your models in one folder. Use a structure like this:

models/
├── staging/
├── intermediate/
├── marts/
│   ├── core/
│   └── reporting/

Each folder serves a purpose:

• staging/ – Raw data cleaned and renamed
• intermediate/ – Joins, filters, business logic
• marts/ – Final models used in reports or dashboards

This keeps your logic modular and reusable.

3. Use Git from the Beginning

dbt plays well with Git. Version control isn’t just for engineers, it’s your safety net.

Even for small projects:

• Initialize Git with git init
• Use branches for features or bug fixes
• Commit regularly

This lets you track changes, revert mistakes, and collaborate safely.

4. Separate Development and Production Environments

Avoid testing directly in production! Use different schemas (or datasets) for dev and prod.

In your profiles.yml, set up different targets:

target: dev  # for development
outputs:
  dev:
    schema: dbt_jane_dev
  prod:
    schema: analytics

Switch targets with:

dbt run --target prod

This ensures you don’t overwrite critical data during testing.

5. Start Adding Tests and Descriptions Early

dbt makes it easy to add:

• Schema tests (e.g., not null, unique)
• Model descriptions (visible in docs)
• Column-level documentation

Even simple tests can catch data issues before they snowball.

6. Use dbt_project.yml for Configurations

Instead of writing configs inside every SQL file, centralize settings like materializations, folders, and naming rules in dbt_project.yml. It’s cleaner and more scalable.

Conclusion:

dbt init is your essential first step into the world of modern data transformation. It sets up the foundation of your project, connecting your development environment to your data warehouse and preparing you to build scalable, version-controlled SQL models.

By understanding and using it properly, you’re setting yourself up for cleaner workflows and more confident analytics development. It’s simple but incredibly powerful, like turning the key to your data modeling engine.

Easily schedule, manage, and monitor your dbt transformations with Hevo Transformer, built to streamline your workflows and improve efficiency. Start today with Hevo Transformer for free and elevate your data transformation processes. 

FAQs (Frequently Asked Questions)