> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Environments
export const m_runner = "Maia runner";
export const Projects = () => <>the Projects icon 
;
export const designer = "Designer";
An environment defines the connection between a project and your chosen cloud data warehouse. Environments include useful defaults—such as a default warehouse, database, and schema—that can be used to pre-populate component configurations in {designer}. Haven't added a project yet? Read [Add project](/docs/guides/projects).
We recommend using environments to separate your development and production environments:
* Use **development environments** for building, testing, and iterating on pipelines before they are deployed.
* Use **production environments** to run pipelines that are fully deployed to work on live data. Only stable and thoroughly tested pipelines should be deployed here.
* You can also use **intermediate environments**, such as `staging`, `test`, or `preprod`, to validate pipelines before they are deployed to production. These can also be used for performance testing.
For more information, read our [Unlocking Data Productivity](https://www.matillion.com/whitePaper/unlocking-data-productivity-data-ops-guide) DataOps guide.
***
## Add an environment
Creating an environment for Google BigQuery? Read [Google BigQuery environments](/docs/guides/bigquery-environments).
1. In your project, click the **Environments** tab.
This tab lists all environments currently created.
2. Click **Add environment**.
| Parameter | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Environment name | A unique name for the environment. Max 255 characters. |
| Runner | A working {m_runner}. This is only required if you are using a [Hybrid SaaS solution](/docs/guides/runner-overview#matillion-hosted-and-customer-hosted-agents). To learn how to create a {m_runner}, read [Create a {m_runner}](/docs/guides/create-a-runner). |
| Default environment access | Use the drop-down to select the default access for all new and existing users added to the project. For more information, read [Environment roles](/docs/administration/environment-roles). |
{m_runner}s can be restricted to specific projects and environments. If a {m_runner} is not allowed for your project or environment, it will not appear in the **Runner** drop-down. For more information, read [Restricting {m_runner}s](/docs/guides/restrict-a-runner).
Click **Continue**.
Depending on the data platform that you selected when [creating your project](/docs/guides/projects#add-a-new-project), follow the corresponding instructions below to specify your cloud data warehouse credentials and select your data warehouse defaults for this environment.
***
## Snowflake
### Prerequisites
Before configuring a Snowflake connection, you will need:
* A Snowflake role with the privileges required to set up this connection. For more information, read [Snowflake role privileges](/docs/administration/snowflake-role-privileges).
* For key-pair authentication, the private key of a key pair. For more information, read [Using Snowflake key-pair authentication](/docs/administration/snowflake-key-pair-authentication).
* A Snowflake programmatic access token (PAT) for PAT authentication. For more information, read [Snowflake programmatic access token authentication](/docs/administration/snowflake-pat-authentication).
* For Hybrid SaaS solutions, permission to create and edit secrets in AWS Secrets Manager or Azure Key Vault. For more information, read [Using Snowflake key-pair authentication](/docs/administration/snowflake-key-pair-authentication).
For details about Snowflake key-pair authentication, read the Snowflake guide to [Configuring key-pair authentication](https://docs.snowflake.com/en/user-guide/key-pair-auth#configuring-key-pair-authentication).
### Specify credentials
Use the reference tables below to set up your environment connection to your cloud data platform. If you're using a Full SaaS deployment, credentials such as passwords and private keys are stored directly as strings. However, if you're using a Hybrid SaaS deployment with your own Maia runner via AWS or Azure, credentials such as passwords and private keys are only retrieved via references to secrets created in either AWS Secrets Manager or Azure Key Vault.
#### Key-pair
We recommend using key-pair authentication to set up your connection to Snowflake, because [Snowflake has announced plans to block single-factor password authentication by November 2025](https://www.snowflake.com/en/blog/blocking-single-factor-password-authentification/). For more information, read our [Tech note](/docs/tech-notes/tech-note-snowflake-to-block-single-factor-password-authentication).
Refer to this table if you're using [Snowflake key-pair authentication](/docs/administration/snowflake-key-pair-authentication).
| Parameter | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Account | Enter your Snowflake account name and region. In the URL you use to log in to Snowflake, this is the part between `https` and `snowflakecomputing.com`. |
| Credentials type | Select **Key pair**. |
| Username | Your Snowflake username. |
| Private key | Your Snowflake private key. To generate a key, read the Snowflake documentation for [Generate the private key](https://docs.snowflake.com/en/user-guide/key-pair-auth#generate-the-private-key). The full content of the generated Snowflake private key file must be copied into this field, including the header and footer lines. Field only available if **Credentials type** is **Key pair** when using a Full SaaS deployment model. |
| Passphrase | An optional passphrase to use with your private key. Field only available if **Credentials type** is **Key pair** and when using a Full SaaS deployment model. |
| Vault name | For **Hybrid SaaS** on **Azure** deployment models only. Select the [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview) instance that this project will use to store secrets. Select \[Default] to use the default key vault specified in the Maia runner environment variables. |
| Private key secret name | A named entry created in [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) or [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview) denoting the secret that holds your Snowflake private key. Read [Using Snowflake key-pair authentication](/docs/administration/snowflake-key-pair-authentication) to learn how to store the key as a secret. Field only available if using a Hybrid SaaS deployment model. |
| Passphrase secret name (optional) | A named entry created in [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) or [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview) denoting the secret that holds your Snowflake key pair passphrase. Field only available if using a Hybrid SaaS deployment model. |
| Passphrase secret key (optional) | The secret key tied to your passphrase secret name. Field only available if using a Hybrid SaaS deployment model. |
If your private key has been shared, the format may have been altered. To correct this, run the following command to validate and convert the key to the correct format:
```
openssl rsa -in key.pem -check
```
#### Password
Refer to this table if you're using your Snowflake password to authenticate to Snowflake.
| Parameter | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Account | Enter your Snowflake account name and region. In the URL you use to log in to Snowflake, this is the part between `https` and `snowflakecomputing.com`. |
| Credentials type | Select **Username and password**. |
| Username | Your Snowflake username. |
| Password | Your Snowflake password. This field is only available if using a Full SaaS deployment; otherwise, you will specify your password as a secret. |
| Vault name | For Hybrid SaaS on Azure deployment models only. Select the [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview) instance that this project will use to store secrets. Select \[Default] to use the default key vault specified in the Maia runner environment variables. |
| Secret name | A named entry created in [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) or [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview) for holding your Snowflake password. Field only available if using a Hybrid SaaS deployment model. |
| Secret key | A named secret key tied to your secret name. Field only available if using a Hybrid SaaS on AWS deployment model. |
#### Programmatic access token
An alternative authentication option is to use a Snowflake programmatic access token (PAT). To use this option, follow the instructions for [Password](#password) authentication, above, using your PAT as the password. For more details of this authentication option, read [Snowflake programmatic access token authentication](/docs/administration/snowflake-pat-authentication).
### Select defaults
| Parameter | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Default role | The default Snowflake role for this environment connection. Read [Overview of Access Control](https://docs.snowflake.com/en/user-guide/security-access-control-overview.html) to learn more. |
| Default warehouse | The default Snowflake warehouse for this environment connection. Read [Overview of Warehouses](https://docs.snowflake.com/en/user-guide/warehouses-overview.html) to learn more. |
| Default database | The default Snowflake database for this environment connection. Read [Database, Schema, and Share DDL](https://docs.snowflake.com/en/sql-reference/ddl-database.html) to learn more. |
| Default schema | The default Snowflake schema for this environment connection. Read [Database, Schema, and Share DDL](https://docs.snowflake.com/en/sql-reference/ddl-database.html) to learn more. |
| Default session parameters | Any session parameters you want to set as the default for this environment connection. Click the cog icon to open the **Configure Session Parameters** dialog, and enter a name and value for each required parameter. See below for more details. |
| Allow inherit project defaults | Use this toggle to manage how the environment handles variable values. When enabled (default), the environment inherits project-level default values. If disabled, you must manually provide values for each variable to ensure pipelines function successfully across environments. |
#### Default session parameters
You can set session parameters to change the behavior of the Snowflake connection. An example of this would be setting the `QUOTED_IDENTIFIERS_IGNORE_CASE` parameter to determine whether the case of letters in double-quoted object identifiers is preserved.
Setting default session parameters when you create an environment is optional, and should only be done if you need to change the default behavior of the Snowflake connection.
To set default session parameters for the environment:
1. In the **Default session parameters** field, click the cog icon to open the **Configure Session Parameters** dialog.
2. Enter a name and value for each required parameter.
3. Click **Save** to close the dialog.
For a description of the available session parameters, read the [Snowflake documentation](https://docs.snowflake.com/en/sql-reference/parameters). Note that for security reasons we don't allow all parameters on that page to be set, only the session-level parameters.
***
## Databricks
### Specify credentials
Use the reference tables below to set up your environment connection to your cloud data platform. If you're using a Full SaaS deployment, credentials such as passwords and private keys are stored directly as strings. However, if you're using a Hybrid SaaS deployment with your own Maia runner via AWS or Azure, credentials such as passwords and private keys are only retrieved via references to secrets created in either AWS Secrets Manager or Azure Key Vault.
| Parameter | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Instance name | Your Databricks instance name. Read the [Databricks documentation](https://docs.databricks.com/en/workspace/workspace-details.html) to learn how to determine your instance name. |
| Personal Access Token | Your Databricks personal access token. Read the [Databricks documentation](https://docs.databricks.com/en/dev-tools/auth/pat.html) to learn how to create a personal access token. |
| Vault name | For **Hybrid SaaS** on **Azure** deployment models only. Select the [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview) instance that this project will use to store secrets. Select \[Default] to use the default key vault specified in the Maia runner environment variables. |
| Secret name | A named entry created in [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) or [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview). |
| Secret key | For **Hybrid SaaS** on **AWS** deployment model only. A named secret key tied to your secret name. |
### Select defaults
| Parameter | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Endpoint/Cluster | The Databricks cluster that Maia will connect to. |
| Catalog | Choose a [Databricks Unity Catalog](https://docs.databricks.com/data-governance/unity-catalog/index.html) to connect to. |
| Schema | Choose a Databricks schema to connect to. |
| Allow inherit project defaults | Use this toggle to manage how the environment handles variable values. When enabled (default), the environment inherits project-level default values. If disabled, you must manually provide values for each variable to ensure pipelines function successfully across environments. |
***
## Amazon Redshift
### Specify credentials
Use the reference tables below to set up your environment connection to your cloud data platform. If you're using a Full SaaS deployment, credentials such as passwords and private keys are stored directly as strings. However, if you're using a Hybrid SaaS deployment with your own Maia runner via AWS or Azure, credentials such as passwords and private keys are only retrieved via references to secrets created in either AWS Secrets Manager or Azure Key Vault.
| Parameter | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Endpoint | The physical address of the leader node. This will be either a name or an IP address. |
| Port | This is usually 5439 or 5432, but it can be configured differently when setting up your Amazon Redshift cluster. |
| Use SSL | Select this to encrypt communications between Maia and Amazon Redshift. Some Amazon Redshift clusters may be configured to require this. |
| Username | The username for the environment connection. |
| Password | For **Full SaaS** deployment model only. Your Redshift password. |
| Vault name | For **Hybrid SaaS** on **Azure** deployment models only. Select the [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview) instance that this project will use to store secrets. Select \[Default] to use the default key vault specified in the Maia runner environment variables. |
| Secret name | For **Hybrid SaaS** deployment model only. A named entry created in [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) or [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview). |
| Secret key | For **Hybrid SaaS** on **AWS** deployment model only. A named secret key tied to your secret name. |
Ensure the IAM user has appropriate permissions to read from and write to the specified S3 bucket. At a minimum, the user should have:
* `s3:GetObject`
* `s3:PutObject`
* `s3:ListBucket`
Next, in the **Specify AWS cloud credentials** dialog, in the drop-down, select one of the following options:
* Use the cloud credentials assigned to the {m_runner} you specified when creating this environment.
* Enter different cloud credentials. This will override the IAM role belonging to the {m_runner} you specified.
If you choose to enter different cloud credentials, use the fields to enter the cloud credential name, access key ID, and secret access key. For details about access keys, read the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
### Select defaults
| Parameter | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Default database | The database you created when setting up your Amazon Redshift cluster. You may run with multiple database names—in which case, choose the one you want to use for this environment. |
| Default schema | This is public by default, but if you have configured multiple schemas within your Amazon Redshift database, you should specify the schema you want to use. |
| Default S3 bucket | The S3 bucket that this environment will use for staging data by default, unless specifically overridden within a component. |
| Allow inherit project defaults | Use this toggle to manage how the environment handles variable values. When enabled (default), the environment inherits project-level default values. If disabled, you must manually provide values for each variable to ensure pipelines function successfully across environments. |
If you use a [Matillion Full SaaS](/docs/guides/runner-overview#matillion-full-saas) solution, the [cloud credentials](/docs/guides/cloud-credentials) associated with your environment will be used to access the S3 bucket.
If you use a [Hybrid SaaS](/docs/guides/runner-overview#hybrid-saas) solution, your new environment will inherit the Maia runner's execution role (service account role) to access the default S3 bucket specified here.
To overwrite this role, [associate different cloud credentials](/docs/guides/cloud-credentials#associate-cloud-provider-credentials-with-an-environment) with this environment after you have finished creating it. You can create these credentials before or after creating the environment.
***
## Associate cloud provider credentials with an environment
Each environment in your project should have at least one set of cloud credentials associated with it. This allows you to access account resources on different platforms other than that hosting your project. For example, if your project is on AWS and you want to access resources in Azure, you need to associate your Azure cloud credentials with the environment.
Credentials are configured at the project level and apply to selected environments within the project. They can then be used by any pipelines that use those environments. To create and associate cloud credentials, read [Cloud provider credentials](/docs/guides/cloud-credentials#creating-a-cloud-provider-credential).
***
## Manage environments
To view your environments:
1. From the **Your projects** menu, select your project.
2. Navigate to the **Environments** tab.
Click the column headers to sort your environments by name, default {m_runner}, cloud data warehouse account name, or credential type.
### Edit an environment
1. Click the three dots **...** in the row of the environment you want to edit.
2. Click **Edit environment**.
3. On the second screen, use the **Allow inherit project defaults** toggle to manage how the environment handles variable values. By default, this setting is enabled, and the environment will inherit the project-level default values.
If you disable this toggle, the environment will not inherit project-level defaults. You must manually provide a default value for each variable within the environment to ensure pipelines function successfully across different environments.
### Delete an environment
Deleting an environment permanently removes the environment from your project. All artifacts and schedules in the deleted environment will be inaccessible. This action cannot be undone.
Before you delete an environment, you must:
* Disable any active schedules that run pipelines in this environment.
* Change the default environment of any branches that currently use this environment as their default. For more information, read [Branches](/docs/guides/branches).
To delete an environment:
1. Click the three dots **...** in the row of the environment you want to delete.
2. Click **Delete environment**.
3. In the confirmation dialog, enter the name of the environment you want to delete.
4. Click **Delete environment**.