Getting started with a new data transformation tool shouldn't feel like being thrown into the deep end. With SQLMesh v0.196.0, we've reimagined the onboarding experience to guide you through your initial setup. sqlmesh init simplifies a once-daunting process into a conversational, guided experience that gets you from zero to running models in minutes.

At Tobiko, we recognize the importance of the developer experience. That's why we've invested in making SQLMesh's initialization process not just functional, but delightful. The result is an onboarding flow that feels more like a helpful colleague walking you through setup than a cold command-line interface.

The new guided initialization experience

When you run sqlmesh init you're no longer greeted with a wall of options or left to figure things out on your own. Instead, SQLMesh guides you. The very first thing you see is a simple question: 

Rather than assuming you know what you want, SQLMesh guides you through the decision-making process. The three options are clearly explained:

  1. DEFAULT - Create SQLMesh example project models and files
  2. dbt - You have an existing dbt project and want to run it with SQLMesh
  3. EMPTY - Create a SQLMesh configuration file and project directories only

For newcomers, option 1 provides a complete working example to learn from. For teams migrating from dbt, option 2 offers a smooth transition path with the SQLMesh dbt adaptor. And for experienced users who know exactly what they want, option 3 provides a clean slate.

Selecting your SQL engine with confidence

For your first time, I recommend: 

[1]  DEFAULT - Create SQLMesh example project models and files

SQLMesh presents you with a comprehensive list of supported SQL engines. But it doesn't just dump a list of names – each option is numbered and clearly presented. Whether you're choosing DuckDB for local development, Snowflake for your cloud warehouse, or any of the other 14+ supported engines, the choice is straightforward.

What makes this particularly thoughtful is what happens after you make your selection. SQLMesh doesn't just create a generic configuration file – it creates one specifically tailored to your chosen engine, complete with:

  • Engine-specific connection parameters are already structured correctly
  • Helpful comments explaining each configuration option
  • Sensible defaults that work out of the box for common setups
  • Clear placeholders for credentials and connection details

For example, if you choose Snowflake, your configuration file will include all the Snowflake-specific parameters like account, warehouse, and role, not generic database connection strings that you'd need to figure out yourself. In this example, I will use DuckDB.

DEFAULT vs FLOW

Perhaps the most innovative aspect of the new initialization is the introduction of CLI modes. After selecting your engine, SQLMesh asks: "Choose your SQLMesh CLI experience."

This choice shapes how you'll interact with SQLMesh going forward:

DEFAULT mode: See and control every detail

The DEFAULT mode is for users who want complete visibility into what SQLMesh is doing. When you choose this mode, you're opting for:

  • Detailed diffs for every change
  • Explicit confirmations before any action
  • Comprehensive output showing all operations
  • Full control over every step of the process

This mode is perfect for production environments, regulated industries, or simply when you're learning and want to understand every aspect of SQLMesh's behavior.

FLOW mode: Streamlined for productivity

FLOW mode represents a different philosophy. When you choose FLOW, you're saying "I trust SQLMesh to make smart decisions." This mode delivers:

  • Automatic application of non-breaking changes
  • Summarized output that focuses on what happened, not how
  • No interruption for routine operations
  • 5-minute onboarding from start to finish

The beauty of FLOW mode is that it doesn't sacrifice safety for speed. SQLMesh still performs all its validations and checks – it just doesn't interrupt you unless something genuinely requires your attention.

Beyond initialization: Helpful guidance at every step

What happens after you make these three choices is where SQLMesh really shines. Instead of dumping you back at the command prompt with a "good luck!", SQLMesh provides comprehensive guidance:

Direct links to your configuration

SQLMesh shows you the exact path to your configuration file and makes it clickable in modern terminals. No more hunting through directories or wondering where files were created. Just command-click and you're editing your configuration.

Smart configuration templates

The generated config.yaml isn't just a skeleton; it's a valuable resource. Many possible configuration options are included, with optional settings commented out and set to their defaults. Each section includes explanatory comments, and complex configurations include examples. This means you can learn SQLMesh's capabilities just by reading your configuration file.

Contextual next steps

Based on your choices, SQLMesh provides customized next steps. If you choose DuckDB you're ready to run immediately. If you choose Snowflake, it reminds you to add your credentials. These aren't generic messages, but specifically tailored to your setup.

Integrated documentation links

Throughout the initialization output, SQLMesh includes links to relevant documentation. But these aren't just "RTFM" pointers – they're contextual links to exactly the information you need at that moment. Wondering about model defaults? There's a link. Curious about connection configuration? Another link, right where you need it.

The example project: Learning by doing

When you choose to create a DEFAULT project with example files, SQLMesh doesn't just give you a "Hello World" – it provides a complete, production-ready example that demonstrates key concepts:

  • Three different model types (SEED, INCREMENTAL, and FULL) show different transformation patterns
  • A complete data pipeline with dependencies between models
  • Working audits demonstrating data quality checks
  • Unit tests showing how to test your transformations
  • Actual data in a seed CSV file, so you can see real results immediately

This example project is carefully crafted to be simple enough to understand in minutes but sophisticated enough to demonstrate real-world patterns. New users can run it immediately and see results, then gradually understand how each piece works.

Reducing the learning curve, not the ceiling

The genius of SQLMesh's onboarding is that it makes getting started easier without limiting what you can do. FLOW mode gets you productive quickly, but you can switch to DEFAULT mode anytime you need more control. The example project teaches core concepts, but you can delete it and start fresh once you understand the patterns.

This approach softens the learning curve because the hardest part isn't learning the advanced features, but getting past the initial hurdle of making the tool work at all. By focusing on that crucial first experience, SQLMesh removes barriers without removing capabilities.

A demonstration of Tobiko's developer-first philosophy

These onboarding improvements reflect Tobiko's core belief: developer experience isn't a nice-to-have, it's essential. Every decision in the new initialization flow stems from observing real users and addressing real pain points:

  • The guided prompts came from watching new users feel overwhelmed by too many choices at once
  • The CLI modes emerged from recognizing that different users have fundamentally different needs
  • The helpful links and comments address the frustration of not knowing where to go next
  • The working example solves the "blank page problem" that paralyzes many newcomers

We've also added the --explain flag to the sqlmesh plan command, allowing users to see exactly what changes will be applied before executing them. This transparency helps build confidence, especially when learning how SQLMesh manages transformations.

Getting started with the new experience

Ready to experience the new onboarding? Simply install or upgrade to SQLMesh and run:

sqlmesh init

Follow the prompts, make your choices, and within minutes, you'll have a working SQLMesh project tailored to your needs. Whether you choose FLOW mode for rapid development or DEFAULT mode for complete control, you'll find an experience that respects both your time and your intelligence.

Looking forward

The new initialization experience is just the beginning. We're committed to these principles: guided experiences, smart defaults, and respect for user choice. Future releases will continue to lower barriers while raising capabilities.

We believe that powerful tools don't have to be painful to adopt. With SQLMesh, we've proven that enterprise-grade data transformation can start with something as simple as answering three friendly questions. Welcome to SQLMesh, we're excited to guide you on your journey.

‍

Read the CLI Quickstart Guide

Read the blog on SQLMesh Plan --explain

{{cta-talk}}

{{banner-slack}}

‍

‍