> ## 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.

# Installing a Maia runner for Snowflake

export const m_runner = "Maia runner";

export const maia = "Maia";

export const RunnerMetadata = ({runnerType, platforms = []}) => {
  return <div style={{
    background: 'var(--colors-background-light, #f9fafb)',
    border: '1px solid var(--colors-border-default, #e5e7eb)',
    borderRadius: '12px',
    padding: '20px 28px',
    marginBottom: '28px'
  }}>
      <table style={{
    width: '100%',
    borderCollapse: 'collapse'
  }}>
        <tbody>
          <tr>
            <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    paddingBottom: '14px',
    whiteSpace: 'nowrap',
    verticalAlign: 'middle',
    width: '180px'
  }}>Runner type</td>
            <td style={{
    paddingBottom: '14px',
    verticalAlign: 'middle'
  }}>{runnerType}</td>
          </tr>
          <tr>
            <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    whiteSpace: 'nowrap',
    verticalAlign: 'middle'
  }}>Runner platform</td>
            <td style={{
    verticalAlign: 'middle'
  }}>
              <div style={{
    display: 'flex',
    flexWrap: 'wrap',
    gap: '8px'
  }}>
                {platforms.map((platform, i) => <span key={i} style={{
    background: '#dcfce7',
    color: '#15803d',
    border: '1px solid #bbf7d0',
    borderRadius: '9999px',
    padding: '3px 12px',
    fontSize: '0.85rem',
    fontWeight: '500',
    whiteSpace: 'nowrap'
  }}>
                    {platform} ✅
                  </span>)}
              </div>
            </td>
          </tr>
        </tbody>
      </table>
    </div>;
};

<RunnerMetadata runnerType={`${maia} Hybrid`} platforms={["Snowflake"]} />

A {m_runner} can be installed directly into your Snowflake account's [Snowpark Container Services](https://docs.snowflake.com/en/developer-guide/snowpark-container-services/overview), using a [Snowflake Native App](https://docs.snowflake.com/en/developer-guide/native-apps/native-apps-about).

The compute pool for the {m_runner} will consume Snowflake credits. For more details of credit consumption, read [Compute pool cost](https://docs.snowflake.com/en/developer-guide/snowpark-container-services/accounts-orgs-usage-views#label-compute-pool-cost) in the Snowflake documentation.

Snowflake is used to store [secrets](/docs/guides/secrets-and-secret-definitions) used by {maia}. For details of how to configure Matillion {m_runner} for Snowflake to use these secrets, read [Secrets in Matillion {m_runner} for Snowflake](/docs/guides/snowflake-runner-secrets).

***

## Prerequisites

To deploy the {m_runner} to your Snowflake account, the Snowflake environment must be prepared. This requires the following actions in your Snowflake account. A user with the **ACCOUNTADMIN** system role will be required to perform these steps.

### Create a new role

This is the role that the Container will run as, and is the role needed to perform all subsequent deployment and configuration for the {m_runner}.

1. Create the role, using the following commands.

   ```sql theme={null}
   USE ROLE ACCOUNTADMIN;
   CREATE ROLE <native_app_role>;
   ```

   Where `<native_app_role>` is the name you want the role to have.

2. Grant permissions to the role.

   ```sql theme={null}
   GRANT ROLE <native_app_role> TO USER <user_name>;
   GRANT CREATE INTEGRATION ON ACCOUNT TO ROLE <native_app_role>;
   GRANT CREATE DATABASE ON ACCOUNT TO ROLE <native_app_role>;
   GRANT CREATE APPLICATION ON ACCOUNT TO ROLE <native_app_role>;
   GRANT CREATE COMPUTE POOL ON ACCOUNT TO ROLE <native_app_role> WITH GRANT OPTION;
   ```

   Where `<native_app_role>` is the name you gave to the role in step 1, and `<user_name>` is the user you want to grant the role to.

### Set up a warehouse

A warehouse is required when activating the application and creating the {m_runner}, and will be used by the {m_runner} when completing tasks such as running pipelines. You may use an existing warehouse if a suitable one exists, or create a new warehouse for the {m_runner} to use.

#### Use an existing warehouse

To use an existing warehouse, you must give the new role **USAGE** permissions for the warehouse, as follows:

```sql theme={null}
GRANT USAGE ON WAREHOUSE <warehouse_name> TO ROLE <native_app_role>;
```

Where `<warehouse_name>` is the warehouse you wish to use, and `<native_app_role>` is the role you created [previously](#create-a-new-role).

<Note>
  As this warehouse will be used by the {m_runner}, it should have the appropriate suspend configuration and sizing.
</Note>

#### Create and use a new warehouse

If you choose to create a new warehouse, it must be created by the role created earlier. The role will require the following additional permission to allow this:

```sql theme={null}
GRANT CREATE WAREHOUSE ON ACCOUNT TO ROLE <native_app_role>;
```

Where `<native_app_role>` is the role you created [previously](#create-a-new-role).

You can then create the new warehouse as follows:

```sql theme={null}
CREATE OR REPLACE WAREHOUSE <native_app_wh> WITH
  WAREHOUSE_SIZE = 'X-SMALL'
  AUTO_SUSPEND = 180
  AUTO_RESUME = true
  INITIALLY_SUSPENDED = false;
```

Where `<native_app_wh>` is the name of the warehouse.

<Note>
  Warehouses consume Snowflake credits, so you should size the warehouse appropriately. For guidance, read [CREATE WAREHOUSE](https://docs.snowflake.com/en/sql-reference/sql/create-warehouse) in the Snowflake documentation.
</Note>

***

## Install the application

Once you have configured the appropriate [prerequisites](#prerequisites) in your Snowflake environment, you can proceed to install and configure the Matillion {m_runner} for Snowflake.

### Create a Maia runner

1. Create a {m_runner} in {maia} as described in [Create a {m_runner} in your infrastructure](/docs/guides/create-a-runner).
2. In the **Cloud provider** drop-down, select **Snowflake**.
3. The **Deployment** drop-down will display **Native App**. This can't be changed.
4. On clicking **Create runner**, you will see the **Runner details** screen that shows you the parameters you will need for installing into Snowflake:

   * **ACCOUNT\_ID**
   * **AGENT\_ID**
   * **MATILLION\_REGION**
   * **Client ID**
   * **Client Secret**

### Install into Snowflake

1. Ensure you are using the role created [previously](#create-a-new-role).

2. Open the [Snowflake Marketplace](https://app.snowflake.com/marketplace).

3. Click **Private Sharing** in the left-hand menu.

4. Locate **Matillion Data Productivity Cloud** in the list of apps, and click to select it.

   <Note>
     If the app is not listed, contact your Matillion representative for advice.
   </Note>

5. Click **Request**.

6. In the **Request this Data Product** dialog, enter your **Name**, **Title** and **Company Name**.

7. Click **Request** to submit the request. The button status will change to **Requested**.

8. A Matillion representative will contact you to confirm the request. Once access is granted, return to this page and click **Get** to access the listing.

9. If required, expand the **Options** panel in order to change:

   * The application name. This is optional, and you can keep the default name if you wish.
   * The warehouse to use for the installation. The warehouse should be the one created or selected [previously](#set-up-a-warehouse).

10. Click **Get**.

11. Click **Open** to view the app, or **Done** to finish.

<Warning>
  If the role you're using to install and set up the application does not have the appropriate permissions (**OWNERSHIP** or **USAGE**) to the selected warehouse, the {m_runner} will **not** start.
</Warning>

### Configure the application

1. Open the application.

2. You will be prompted to grant access to allow the application to create a compute pool and a network rule allowing all access to ports `80` and `443`. You must grant this access. Once the permissions have been granted, you will be able to activate the application.

   <Note>
     These are the minimum ports required by the {m_runner}s. If you need to open additional ports for any reason, follow the instructions in [How to open more ports](/docs/guides/snowflake-runner-troubleshooting#how-to-open-more-ports).
   </Note>

3. Under **Privileges to objects**, add the Snowflake warehouse that the {m_runner} will use to run queries within the account.

4. Click **Launch App**. On the initial configuration screen, enter the details you [previously obtained](#create-a-maia-runner) from the **Runner details** screen in {maia}:

   * Matillion Region
   * Account ID
   * {m_runner} ID
   * Client ID
   * Client Secret

5. Leave the **Environment** property unchanged.

6. You can leave the **Default Secrets Schema** unchanged (recommended), or change it to another schema of your choice. Read [Secrets in Matillion {m_runner} for Snowflake](/docs/guides/snowflake-runner-secrets) for further details.

   <Note>
     If you uninstall the application, any secrets created within the listed schema will be deleted.
   </Note>

7. Click **Submit**. This will start the {m_runner}.

The {m_runner} status will initially show **PENDING**. This should eventually move to a **READY** state, meaning the {m_runner} is connected and available to run pipelines. If the {m_runner} doesn't change to a **READY** state, follow the guidance in the [troubleshooting](/docs/guides/snowflake-runner-troubleshooting#maia-runner-status-hasnt-changed-to-ready) document.

When the {m_runner} is in a **READY** state, you can begin creating {maia} [projects](/docs/guides/projects) or [environments](/docs/guides/environments) that use the new {m_runner}.

### Connecting an environment

When creating a {maia} [environment](/docs/guides/environments#add-an-environment) using Matillion {m_runner} for Snowflake, you must use the Snowflake "Format 1" account identifier as the environment's **Account** property.

To get the correct Format 1 identifier, run the following query within the account:

```sql theme={null}
SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME();
```

For further details of Format 1, read [Format 1 (preferred): Account name in your organization](https://docs.snowflake.com/en/user-guide/admin-account-identifier#format-1-preferred-account-name-in-your-organization) in the Snowflake documentation.

***

## Installing multiple Maia runner instances

You can run multiple {m_runner}s, which may be a requirement for the level of performance and concurrency you need. You can do this by installing multiple Native App instances, with each instance running a single {m_runner} instance.

For a given Snowflake account, up to 10 Native App instances can be installed.

To increase the number of instances, open the installed app and click **Add instance**. Configure the new instance as described in the sections above.

You can use the same role and warehouse for each app instance, or you can create new roles and warehouses for each.

***

## Refreshing Maia runner credentials

### Client secret

You can change the client secret after deploying the {m_runner}.

You refresh the credentials from the **Control Panel** of the Native App within Snowflake:

1. Open the Native App and click the **Control Panel** tab.
2. Click **Apply** to generate a new client secret.
3. Click **Apply** again when prompted to confirm the change.

<Warning>
  * Changing the client secret will restart the {m_runner}, so any in-flight pipelines will be at risk.
  * If the client secret is incorrect, the {m_runner} status will show as **Unknown** on the **{m_runner}s** page, and the {m_runner} can't be used to run pipelines.
</Warning>

### Client ID

To change the client ID, delete the {m_runner} and re-create it with the new client ID.

***

## Uninstalling the application

You can uninstall the application from the Apps area within Snowflake. From your Snowflake **Home** screen, click **Data Products** → **Apps**. You must be using the role that originally installed the application.

Following an uninstall, some artifacts are left behind and must be manually removed. These are:

* The `<APPLICATION_NAME>_APP_DATA` database.
* The `<APPLICATION_NAME>_ALL_EXTERNAL_ACCESS_EXTERNAL_ACCESS` external integration.

To remove these, run the following commands:

```sql theme={null}
DROP DATABASE <APPLICATION_NAME>_APP_DATA CASCADE;
DROP INTEGRATION <APPLICATION_NAME>_ALL_EXTERNAL_ACCESS_EXTERNAL_ACCESS;
```

Where `<APPLICATION_NAME>` is the name of the application set during installation. By default, this is `MATILLION_DATA_PRODUCTIVITY_CLOUD`.

***

## Updating a Maia runner

Matillion provides regular updates to both the Native App and the {m_runner} for Snowflake. Updates are released on the second Tuesday of every month, starting at 12:00 UTC and ending at 11:59 UTC on the second Wednesday. During this update window, Snowflake updates the {m_runner}. Any pipelines running during this time may fail if the update is in progress.

The Matillion {m_runner} for Snowflake is only available on the [Stable version track](/docs/guides/runner-overview#maia-runner-version-tracks), and is updated once per month on the second Tuesday of the month. New {m_runner} releases may include new features, bug fixes, and security patches.