Implementation:TobikoData Sqlmesh Init Example Project

Knowledge Sources	SQLMesh SQLMesh Docs
Domains	Data_Engineering, Dbt_Migration
Last Updated	2026-02-07 00:00 GMT

Overview

Concrete tool for initializing a SQLMesh project structure with support for dbt project integration provided by SQLMesh.

Description

The init_example_project function creates the necessary SQLMesh configuration and directory structure for a new SQLMesh project. When initialized with template=ProjectTemplate.DBT, it creates a minimal configuration (sqlmesh.yaml) that enables SQLMesh to work with an existing dbt project without disrupting the dbt structure. The function validates that required dbt files exist, configures the appropriate engine adapter, and establishes the foundation for running dbt models through SQLMesh's plan/apply workflow.

For dbt projects, this function intentionally avoids creating the standard SQLMesh directories (models/, seeds/, tests/, audits/, macros/) since these already exist in the dbt project. Instead, it focuses solely on creating the SQLMesh configuration that references the existing dbt assets.

Usage

Use init_example_project when setting up SQLMesh for the first time in a dbt project directory. This is typically invoked through the CLI command `sqlmesh init -t dbt`, but can also be called programmatically to automate project setup. The function should be run from within an existing dbt project directory that contains dbt_project.yml.

Code Reference

Source Location

• Repository: sqlmesh
• File: sqlmesh/cli/project_init.py

Signature

def init_example_project(
    path: t.Union[str, Path],
    engine_type: t.Optional[str],
    dialect: t.Optional[str] = None,
    template: ProjectTemplate = ProjectTemplate.DEFAULT,
    pipeline: t.Optional[str] = None,
    dlt_path: t.Optional[str] = None,
    schema_name: str = "sqlmesh_example",
    cli_mode: InitCliMode = InitCliMode.DEFAULT,
    start: t.Optional[str] = None,
) -> Path

Import

from pathlib import Path
from sqlmesh.cli.project_init import init_example_project, ProjectTemplate

I/O Contract

Inputs

Name	Type	Required	Description
path	str or Path	Yes	Directory path where SQLMesh should be initialized
engine_type	str	No	SQL engine type (not required for dbt template since dbt profile specifies engine)
dialect	str	No	SQL dialect override; inferred from engine_type if not provided
template	ProjectTemplate	No	Project template type; use ProjectTemplate.DBT for dbt projects
pipeline	str	No	DLT pipeline name (only for DLT template)
dlt_path	str	No	Path to DLT project (only for DLT template)
schema_name	str	No	Schema name for example models (not used for dbt template)
cli_mode	InitCliMode	No	CLI interaction mode for configuration prompts
start	str	No	Start date for project (not used for dbt template)

Outputs

Name	Type	Description
config_path	Path	Path to the created configuration file (sqlmesh.yaml for dbt, config.yaml otherwise)

Usage Examples

Basic Usage for dbt Project

from pathlib import Path
from sqlmesh.cli.project_init import init_example_project, ProjectTemplate

# Initialize SQLMesh in existing dbt project
project_dir = Path("/path/to/dbt/project")
config_path = init_example_project(
    path=project_dir,
    engine_type=None,  # Not needed for dbt template
    template=ProjectTemplate.DBT
)

print(f"SQLMesh configuration created at: {config_path}")
# Output: /path/to/dbt/project/sqlmesh.yaml

Programmatic Initialization

from pathlib import Path
from sqlmesh.cli.project_init import init_example_project, ProjectTemplate, InitCliMode

# Initialize with non-interactive mode
try:
    config_path = init_example_project(
        path="/my/dbt/project",
        engine_type=None,
        template=ProjectTemplate.DBT,
        cli_mode=InitCliMode.DEFAULT
    )
    print(f"Successfully initialized SQLMesh at {config_path}")
except SQLMeshError as e:
    print(f"Initialization failed: {e}")
    # Common errors:
    # - dbt_project.yml not found
    # - sqlmesh.yaml already exists

Standard SQLMesh Project (Non-dbt)

from pathlib import Path
from sqlmesh.cli.project_init import init_example_project, ProjectTemplate

# Initialize standard SQLMesh project with DuckDB
config_path = init_example_project(
    path=Path("/new/sqlmesh/project"),
    engine_type="duckdb",
    template=ProjectTemplate.DEFAULT,
    schema_name="my_analytics"
)

# This creates:
# - config.yaml
# - models/ directory with example models
# - seeds/ directory with example data
# - tests/ directory with example tests
# - audits/ directory with example audits
# - macros/ directory with example macros

Error Handling

from pathlib import Path
from sqlmesh.cli.project_init import init_example_project, ProjectTemplate
from sqlmesh.core.config import SQLMeshError

project_path = Path("./my_dbt_project")

try:
    config_path = init_example_project(
        path=project_path,
        template=ProjectTemplate.DBT
    )
except SQLMeshError as e:
    if "dbt_project.yml" in str(e):
        print("Error: Not a dbt project directory")
        print("Make sure dbt_project.yml exists in the target directory")
    elif "existing config" in str(e):
        print("Error: SQLMesh already initialized")
        print("Remove sqlmesh.yaml to reinitialize")
    else:
        print(f"Initialization error: {e}")

Related Pages

Implements Principle

• Principle:TobikoData_Sqlmesh_Sqlmesh_Initialization_For_Dbt

• Environment:TobikoData_Sqlmesh_Dbt_Compatibility