Tutorial 1: Your First dbt Project

Time: 30 minutes Difficulty: Beginner Prerequisites: Basic SQL knowledge

---

What You'll Build

A complete dbt project that:

• Connects to a PostgreSQL database
• Transforms raw customer and order data
• Creates tested analytical models
• Generates documentation

By the end, you'll have a working dbt project deployed locally.

---

What You'll Learn

• How to initialize a dbt project
• Project structure and configuration
• Writing your first models
• Running transformations
• Testing data quality
• Generating documentation

---

Prerequisites

Required

• Python 3.7+ installed
• PostgreSQL database (or Docker to run one)
• Git installed
• Code editor (VS Code recommended)

Setup PostgreSQL with Docker (Optional)

If you don't have PostgreSQL, use Docker:

---

Step 1: Install dbt

Install dbt Core for PostgreSQL

You should see output like:

---

Step 2: Initialize Your Project

Create a New dbt Project

This creates the following structure:

Navigate to Your Project

---

Step 3: Test Your Connection

Look for this output:

If you see errors:

• Check your database is running: docker ps
• Verify credentials in ~/.dbt/profiles.yml
• Ensure database exists: psql -h localhost -U dbt_user -d dbt_tutorial

---

Step 4: Create Sample Source Data

Load Seed Data

Create seed files (CSV data that dbt will load):

seeds/raw_customers.csv:

seeds/raw_orders.csv:

seeds/raw_payments.csv:

Load Seeds into Database

Output:

Your data is now loaded as tables: raw_customers, raw_orders, raw_payments

---

Step 5: Create Staging Models

Delete the example models:

Define Sources

Create models/staging/sources.yml:

Create Staging Model: Customers

Create models/staging/stg_customers.sql:

Create Staging Model: Orders

Create models/staging/stg_orders.sql:

Create Staging Model: Payments

Create models/staging/stg_payments.sql:

---

Step 6: Create Mart Models

Create Customer Dimension

Create models/marts/dim_customers.sql:

Create Order Fact Table

Create models/marts/fct_orders.sql:

---

Step 7: Configure Models

Update dbt_project.yml:

---

Step 8: Run Your Models

Output:

What just happened?

• dbt created 3 views (staging models)
• dbt created 2 tables (mart models)
• All models built in the correct dependency order

Verify in Database

---

Step 9: Add Tests

Create Schema Tests

Create models/staging/staging_models.yml:

Create models/marts/mart_models.yml:

Run Tests

Output:

All tests passed!

---

Step 10: Generate Documentation

This opens http://localhost:8080 with:

• Lineage graph showing model dependencies
• Model documentation with descriptions
• Column details with tests
• Source information

Click on models to explore the DAG (Directed Acyclic Graph).

---

Checkpoint: What You've Built

You now have a complete dbt project with:

✅ 5 models:

• 3 staging models (views)
• 2 mart models (tables)

✅ 10 passing tests:

• Unique and not null checks
• Referential integrity

✅ Full documentation:

• Model descriptions
• Column definitions
• Data lineage graph

✅ Version controlled:

---

Challenge Exercises

Try these on your own:

Challenge 1: Add a New Metric

Add lifetime_value to dim_customers by summing total_amount from fct_orders.

Show Solution

Run: dbt run --select dim_customers

Challenge 2: Create a Custom Test

Write a test that ensures total_amount in fct_orders is never negative.

Show Solution

Create tests/assert_positive_total_amount.sql:

Run: dbt test

Challenge 3: Add Documentation

Add descriptions to all columns in dim_customers.

Show Solution

Update models/marts/mart_models.yml:

Run: dbt docs generate && dbt docs serve

---

Common Issues & Solutions

Error: "Database not found"

Error: "Compilation Error: depends on a node named 'model.jaffle_shop.xxx' which was not found"

• Check model file names match what you're referencing
• Run dbt clean then dbt run

Tests Failing?

---

Next Steps

Congratulations! You've built your first dbt project. Continue learning:

1. Tutorial 2: Customer Analytics Pipeline - Build a more complex project with real patterns
2. Best Practices Guide - Learn professional patterns
3. dbt Official Docs - Deep dive into features

---

Get Help

• Stuck on this tutorial? Drop a question in dbt Community Slack
• Want 1-on-1 help? Book a coaching session
• Need team training? Custom workshops available

---

Ready for more? Continue to Tutorial 2: Customer Analytics Pipeline