Implementation:Astronomer Astronomer cosmos ProfileConfig Init

Metadata

Field	Value
Page Type	Implementation
Repository	astronomer-cosmos
Source File	`cosmos/config.py`, Lines L279-400
Implements	Principle:Astronomer_Astronomer_cosmos_Profile_Configuration
Import	`from cosmos.config import ProfileConfig`

Overview

ProfileConfig is the concrete tool provided by the astronomer-cosmos library for configuring dbt database connection profiles within an Airflow orchestration context. It supports two modes of operation: file-based profile configuration (pointing to an existing profiles.yml) and mapping-based profile configuration (dynamically generating a profile from an Airflow connection).

This dataclass encapsulates the profile name, target name, and the mechanism for profile resolution, providing a unified interface regardless of which strategy is used.

Source Location

Property	Value
Repository	astronomer-cosmos
File	`cosmos/config.py`
Lines	L279-400
Class	`ProfileConfig` (decorated with `@dataclass`)

Code Reference

Signature

@dataclass
class ProfileConfig:
    profile_name: str
    target_name: str
    profiles_yml_filepath: str | Path | None = None
    profile_mapping: BaseProfileMapping | None = None

Import Statements

from cosmos.config import ProfileConfig

# For mapping-based profiles, import the appropriate profile mapping class
from cosmos.profiles.postgres.user_pass import PostgresUserPasswordProfileMapping
from cosmos.profiles.bigquery.service_account import GoogleCloudServiceAccountProfileMapping
from cosmos.profiles.snowflake.user_pass import SnowflakeUserPasswordProfileMapping

Parameters

Parameter	Type	Default	Description
`profile_name`	`str`	(required)	The dbt profile name. Must match the profile referenced in `dbt_project.yml`.
`target_name`	`str`	(required)	The target name within the profile (e.g., `"dev"`, `"prod"`).
`profiles_yml_filepath`	Path \| None	`None`	Path to a pre-existing `profiles.yml` file. Used for file-based profile mode.
`profile_mapping`	None	`None`	A profile mapping instance that generates the profile from an Airflow connection. Used for mapping-based mode.

Key Methods

ensure_profile()

A context manager that ensures a valid profiles.yml file is available on the filesystem during dbt execution.

In file-based mode, it validates the file exists and yields the path.
In mapping-based mode, it generates a temporary profiles.yml from the mapping, writes it to a temporary location, yields the path, and cleans up afterward.

with profile_config.ensure_profile() as profile_path:
    # profile_path points to a valid profiles.yml file
    run_dbt_command(profiles_dir=profile_path.parent)

get_profile_type()

Returns the dbt adapter type string (e.g., "postgres", "bigquery") based on the configured profile mapping or file contents.

validate_profile()

Validates the profile configuration during initialization:

Ensures that exactly one of profiles_yml_filepath or profile_mapping is provided.
If profiles_yml_filepath is provided, validates the file exists.
If profile_mapping is provided, validates it is a valid BaseProfileMapping subclass instance.

I/O Contract

Inputs

Required: profile_name (str) and target_name (str).
Required (one of): Either profiles_yml_filepath OR profile_mapping must be provided. Providing both or neither raises a validation error.

Outputs

A ProfileConfig instance that provides:

The ensure_profile() context manager for obtaining a filesystem path to a valid profiles.yml.
The get_profile_type() method for adapter type introspection.
Direct attribute access to profile_name and target_name.

Usage Examples

File-Based Profile Configuration

from cosmos.config import ProfileConfig
from pathlib import Path

# Point to an existing profiles.yml file
profile_config = ProfileConfig(
    profile_name="my_dbt_project",
    target_name="dev",
    profiles_yml_filepath=Path("/usr/local/airflow/dags/dbt/profiles.yml"),
)

This approach is suitable when the profiles.yml is managed externally, such as being mounted as a Kubernetes secret or checked into a secure repository.

Mapping-Based Profile Configuration (Postgres)

from cosmos.config import ProfileConfig
from cosmos.profiles.postgres.user_pass import PostgresUserPasswordProfileMapping

# Dynamically generate profile from an Airflow connection
profile_config = ProfileConfig(
    profile_name="my_dbt_project",
    target_name="dev",
    profile_mapping=PostgresUserPasswordProfileMapping(
        conn_id="my_postgres_connection",
        profile_args={
            "schema": "analytics",
            "threads": 4,
        },
    ),
)

In this mode, cosmos reads the connection details from the Airflow connection identified by conn_id and dynamically generates the profiles.yml content at runtime.

Mapping-Based Profile Configuration (Snowflake)

from cosmos.config import ProfileConfig
from cosmos.profiles.snowflake.user_pass import SnowflakeUserPasswordProfileMapping

profile_config = ProfileConfig(
    profile_name="snowflake_project",
    target_name="prod",
    profile_mapping=SnowflakeUserPasswordProfileMapping(
        conn_id="snowflake_default",
        profile_args={
            "database": "ANALYTICS",
            "warehouse": "TRANSFORM_WH",
            "schema": "PUBLIC",
        },
    ),
)

Complete DAG Example

from cosmos import DbtTaskGroup, ProjectConfig, ProfileConfig, RenderConfig
from cosmos.profiles.postgres.user_pass import PostgresUserPasswordProfileMapping

profile_config = ProfileConfig(
    profile_name="jaffle_shop",
    target_name="dev",
    profile_mapping=PostgresUserPasswordProfileMapping(
        conn_id="postgres_default",
        profile_args={"schema": "public"},
    ),
)

project_config = ProjectConfig(
    dbt_project_path="/usr/local/airflow/dags/dbt/jaffle_shop",
)

dbt_tasks = DbtTaskGroup(
    project_config=project_config,
    profile_config=profile_config,
    render_config=RenderConfig(),
)

Related Pages

Implements Principle

Principle:Astronomer_Astronomer_cosmos_Profile_Configuration — The principle this implementation realizes.

Complementary Implementations

Implementation:Astronomer_Astronomer_cosmos_ProjectConfig_Init — Complementary implementation for project path configuration.
Implementation:Astronomer_Astronomer_cosmos_RenderConfig_Init — Complementary implementation for graph rendering configuration.
Implementation:Astronomer_Astronomer_cosmos_ExecutionConfig_Init — Complementary implementation for runtime execution configuration.

Requires Environment

Environment:Astronomer_Astronomer_cosmos_Python_Airflow_Runtime

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment