> ## Documentation Index
> Fetch the complete documentation index at: https://honeydew.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

<Info>
  Environments is currently in Beta. Contact [support@honeydew.ai](mailto:support@honeydew.ai) to activate it for your account.
</Info>

Honeydew provides support for managing different settings tailored to specific branches.
This feature is particularly useful, for example, for teams that need to use different
databases and schemas
for various branches (e.g., the published production branch and other development branches)
while maintaining a consistent table naming structure across environments.

The configuration syntax is flexible, allowing you to specify settings for individual branch names or use patterns for broader matches.
For example, you can define settings for a specific branch like `dev1`
or use patterns such as `dev*` to match any branch starting with dev,
or `dev[12]` to match `dev1` or `dev2`.
A wildcard pattern `*` can be used as a default option to catch all unmatched branches.

Branch name matching rules are evaluated sequentially, ensuring precise control
over the settings applied to each branch.

## Configuration

You can configure environments in the Honeydew UI using the "Workspace actions" menu in the Workspace.

For each environment, you can specify the following settings:

1. **Name** - the name of the environment.
2. **Branch pattern** - the pattern to match the branch name.
   1. `*` - matches all branches
   2. `prod` - matches `prod` branch
   3. `dev*` - matches all branches starting with `dev`
   4. `dev_[12]` - matches `dev_1` and `dev_2`
   5. `dev_[!12]` - matches `dev_3`, but not `dev_1` and `dev_2`
3. **Connector** - the data warehouse connector to use (optional). Lets you use
   different credentials per environment. All connectors must be of the same data
   warehouse type.
   See [Separate Credentials per Environment](#separate-credentials-per-environment).
4. **Connection settings** - the data warehouse connection overrides (optional).
   The available settings depend on your data warehouse type. For Snowflake these are
   the **Database**, **Schema**, **Warehouse**, and **Role**.
   For Databricks, these are the **Catalog**, **Schema**, and **Warehouse**.

## Order of Evaluation

There are a few places in Honeydew where you can configure and override data warehouse
connection settings:

1. Global connection settings (lowest precedence)
2. Environment level settings overrides
3. [Domain](/domains) level settings overrides (highest precedence)

For example, with Snowflake:

1. You have global connection settings, defining a ROLE and a WAREHOUSE
2. You have an environment configuration for the `prod` branch, defining a different ROLE
3. You have a domain configuration for domain named `sales`, defining a different WAREHOUSE

When you use the `sales` domain from the `prod` branch, Honeydew will use the ROLE from the `prod` environment configuration and the WAREHOUSE from the `sales` domain configuration.

The following table shows the different options for defining connection settings and their
order of evaluation. The settings shown are for Snowflake; other data warehouse types have
equivalent settings.

| Setting   | Global | Environment | Domain |
| --------- | ------ | ----------- | ------ |
| Database  | -      | ✅           | -      |
| Schema    | -      | ✅           | -      |
| Warehouse | ✅      | ✅           | ✅      |
| Role      | ✅      | ✅           | ✅      |

## Use-cases

### Development and Production Databases / Schemas

When working with multiple environments, it can be important to separate production data from development and testing workflows.
For example, in your data warehouse, you may have separate databases for production
(**PROD**) and development (**DEV**), both sharing the same schema structure.
The **DEV** database is used for testing and development, while PROD is reserved for live, production data.

In Honeydew, you can configure two environments to manage these databases effectively:

One environment for the prod branch, linked to the **PROD** database.
Another environment for all other branches, linked to the **DEV** database.
This setup ensures that production workflows operate on the correct database while development branches have a safe space to test changes in data.

When you switch branches in Honeydew, the connection settings will be automatically adjusted based on the predefined branch name matching rules.
When mapping tables to entities, Honeydew will use the connection settings from the active environment.

When Honeydew determines the [source data](/modeling/source-data) of an entity, it will use the **Database** and **Schema** settings of the environment
to resolve relative table paths in the source data.

<Warning>
  Any entities mapped to source data using absolute paths will not be affected by the Database/Schema environment settings.
</Warning>

<Tip>
  The same approach of using different databases for different environments can also be applied to specific schemas within the same database.
</Tip>

### Warehouse Settings

Environments can help optimize resource allocation by adjusting warehouse settings based on usage needs.
For example, you can configure an environment for the `prod` branch with a larger warehouse to handle higher workloads,
while the dev branch can use a smaller, cost-efficient warehouse.
When switching branches in Honeydew, the warehouse settings will automatically adjust based on predefined branch name rules, ensuring the right resources are used for each environment.

<Tip>
  Another way to manage cost and performance for development purposes is by creating a domain with a filtered view of the data (for example, limiting it to the last two weeks of records).
  For more details, see [domains](/domains).
</Tip>

### Separate Credentials per Environment

You can configure each environment to use a different data warehouse connector.
This is useful when development, QA, and production rely on separate credentials —
for example, when each connects to a distinct account or service user.

Define a connector per environment so that switching branches automatically uses the
matching credentials. For example, the `prod` branch can use a production connector,
while `dev*` and `qa*` branches use development and QA connectors.

All connectors used across a workspace's environments must be of the same data
warehouse type (for example, all Snowflake or all Databricks). The connector is set
with the `dwh_connector_name` environment field (see [YAML Schema](#yaml-schema)).

### Role-based Access Control

Environments can be used to manage role-based access control in Snowflake.
For example, you can create a **DEV** role with access to the **DEV** database and a **PROD** role with access to the **PROD** database,
ensuring that users only have access to the data they need for their specific tasks.
By configuring environments in Honeydew, you can automatically switch roles based on the active branch, simplifying access management and ensuring data security.

## YAML Schema

Environments are defined per-workspace, in each workspace's YAML on the `prod` branch.
For more details on workspaces YAML format, see [workspaces](/governance/workspaces#yaml-schema).

The connection settings are defined under a block named for the data warehouse type:
`snowflake` or `databricks`. All environments in a workspace use the same block type.

For Snowflake:

```yaml theme={null}
...
environments:
  - name: Prod Environment
    branch_pattern: prod
    dwh_connector_name: prod_connector
    snowflake:
      database: PROD
      schema: PROD
      warehouse: PROD_WH
      role: PROD_ROLE
  - name: Dev Environment
    branch_pattern: dev*
    dwh_connector_name: dev_connector
    snowflake:
      database: DEV
      schema: DEV
      warehouse: DEV_WH
      role: DEV_ROLE
```

For Databricks:

```yaml theme={null}
...
environments:
  - name: Prod Environment
    branch_pattern: prod
    dwh_connector_name: prod_connector
    databricks:
      catalog: PROD
      schema: PROD
      http_path: /sql/1.0/warehouses/prod123
  - name: Dev Environment
    branch_pattern: dev*
    dwh_connector_name: dev_connector
    databricks:
      catalog: DEV
      schema: DEV
      http_path: /sql/1.0/warehouses/dev123
```