# Microsoft Fabric

This guide provides detailed instructions for integrating Microsoft Fabric Warehouse with DinMo.

Microsoft Fabric Warehouse is a SQL-based analytics engine within Microsoft Fabric. DinMo connects to Fabric Warehouse through its SQL endpoint using a dedicated Microsoft Entra service principal.

This guide explains how to configure the connection, grant the required permissions, create DinMo’s technical schemas, and troubleshoot the most common issues.

### Prerequisites

Before starting the integration, ensure you have:

* Access to a Microsoft Fabric workspace containing a **Warehouse** item.
* Permissions to manage access to the Fabric workspace and the Warehouse.
* Permissions to create database users, schemas, and grant SQL permissions in the target Warehouse.
* A DinMo workspace with access to add new data sources.

> If your organization enforces network restrictions, make sure DinMo’s IPs are allowlisted. See our Networking section for more details.

### Connecting Microsoft Fabric to DinMo

#### Step 1: Create a dedicated Service Principal for DinMo

To enable DinMo to connect securely to your Microsoft Fabric Warehouse, create a dedicated Microsoft Entra application / service principal.

1. Log in to the **Microsoft Entra admin center**.
2. Go to **Identity > Applications > App registrations**.
3. Click **New registration**.
4. Choose a name such as `DinMo Fabric Integration`.
5. Select **Accounts in this organizational directory only**.
6. Click **Register**.
7. Save the following values:
   * **Application (client) ID**
   * **Directory (tenant) ID**

Then create a credential for this application:

1. Go to **Certificates & secrets**.
2. Create a new **Client secret**.
3. Save the secret value securely.

DinMo will use the following credentials to connect:

* Tenant ID
* Client ID
* Client Secret

> We recommend creating a dedicated service principal for DinMo rather than reusing an existing application identity. This makes auditing, rotation, and permission management much easier.

#### Step 2: Enable Service Principal access in Microsoft Fabric

By default, Microsoft Fabric may block service principal access depending on your tenant configuration.

In Microsoft Fabric:

1. Open the **Admin portal**.
2. Go to **Tenant settings**.
3. Under **Developer settings**, enable:
   * **Service principals can use Fabric APIs**

If your setup later relies on external storage access from Fabric (for example through `COPY INTO` or `OPENROWSET`), you may also need additional Fabric / OneLake settings depending on your environment.

#### Step 3: Grant the Service Principal access to the Warehouse

DinMo connects to the Fabric **Warehouse** (not to the Lakehouse SQL endpoint, for now).

In Microsoft Fabric:

1. Open the workspace containing the target Warehouse.
2. Open the Warehouse permissions page.
3. Add the DinMo service principal.
4. Grant it at least the permission required to connect and read data through SQL.

DinMo also requires SQL-level permissions inside the Warehouse itself.

### Step 4: Create DinMo technical schemas in Fabric Warehouse

Before configuring the source in DinMo, create the schemas DinMo will use to store technical data.

DinMo typically stores technical objects in dedicated schemas such as:

* `dinmo_segments`
* `dinmo_stats`
* `dinmo_delta_storage`
* `dinmo_predictions`
* `dinmo_identity` (if the Identity Resolution module is enabled)

Why create dedicated schemas?

* **Organization**: DinMo’s technical objects stay isolated from your business tables.
* **Security**: Access can be scoped precisely to DinMo-owned schemas.
* **Operations**: Incremental sync state, materializations, and technical outputs remain easy to monitor and maintain.

Run the following SQL commands in your Fabric Warehouse:

```sql
IF NOT EXISTS (SELECT 1 FROM sys.schemas WHERE name = 'dinmo_segments')
BEGIN
    EXEC('CREATE SCHEMA [dinmo_segments]');
END;

IF NOT EXISTS (SELECT 1 FROM sys.schemas WHERE name = 'dinmo_stats')
BEGIN
    EXEC('CREATE SCHEMA [dinmo_stats]');
END;

IF NOT EXISTS (SELECT 1 FROM sys.schemas WHERE name = 'dinmo_delta_storage')
BEGIN
    EXEC('CREATE SCHEMA [dinmo_delta_storage]');
END;

IF NOT EXISTS (SELECT 1 FROM sys.schemas WHERE name = 'dinmo_predictions')
BEGIN
    EXEC('CREATE SCHEMA [dinmo_predictions]');
END;

IF NOT EXISTS (SELECT 1 FROM sys.schemas WHERE name = 'dinmo_identity')
BEGIN
    EXEC('CREATE SCHEMA [dinmo_identity]');
END;
```

#### Step 5: Create a database user mapped to the Service Principal

Create a database user for the DinMo service principal inside the Warehouse.

> Replace `<service_principal_name>` with the display name of your Microsoft Entra application or service principal, according to your organization’s naming convention.

```sql
CREATE USER [<service_principal_name>] FROM EXTERNAL PROVIDER;
```

If your Fabric environment does not allow this exact command pattern for service principals, your data team can create the corresponding user using the Entra object identifier and then grant permissions to that user. The end result must be a SQL user mapped to the DinMo service principal.

#### Step 6: Grant permissions to DinMo

DinMo requires two types of permissions:

1. **Read permissions** on the business schemas, tables, and views that will be used in DinMo
2. **Read and write permissions** on DinMo’s technical schemas

**6.1 Grant read access to business schemas**

Replace `<business_schema>` with the schema(s) containing the data you want to use in DinMo.

```sql
GRANT SELECT ON SCHEMA::[<business_schema>] TO [<service_principal_name>];
```

If you prefer to scope access more tightly, you can grant `SELECT` only on specific tables and views instead of the full schema.

Example:

```sql
GRANT SELECT ON OBJECT::[dbo].[customers] TO [<service_principal_name>];
GRANT SELECT ON OBJECT::[dbo].[orders] TO [<service_principal_name>];
GRANT SELECT ON OBJECT::[dbo].[events] TO [<service_principal_name>];
```

**6.2 Grant control on DinMo technical schemas**

DinMo needs to create and manage objects in its dedicated schemas.

```sql
GRANT CONTROL ON SCHEMA::[dinmo_segments] TO [<service_principal_name>];
GRANT CONTROL ON SCHEMA::[dinmo_stats] TO [<service_principal_name>];
GRANT CONTROL ON SCHEMA::[dinmo_delta_storage] TO [<service_principal_name>];
GRANT CONTROL ON SCHEMA::[dinmo_predictions] TO [<service_principal_name>];
GRANT CONTROL ON SCHEMA::[dinmo_identity] TO [<service_principal_name>];
```

If some DinMo modules are not enabled in your workspace, you may omit the corresponding schemas.

### Step 7: Add Microsoft Fabric as a source in DinMo

Once the Warehouse and permissions are ready, configure the source in DinMo.

1. In your DinMo workspace, go to **Workspace Settings**.
2. Open the **Sources** tab.
3. Click **Add New Source**.
4. Select **Microsoft Fabric**.

#### Required connection details

Fill in the following fields:

* **Host / Server**: the Fabric SQL endpoint hostname
* **Port**: `1433`
* **Database**: the exact name of the target Warehouse
* **Tenant ID**: the Microsoft Entra tenant ID
* **Client ID**: the service principal application ID
* **Client Secret**: the secret generated earlier
* **Source name**: the display name you want in DinMo

> The **Database** field must match the Fabric Warehouse name exactly. This value is required for the SQL connection to succeed.

Then click **Save & Test**.

Before allowing the source to be created, DinMo will validate:

* Network connectivity
* Fabric credentials
* Access to the target Warehouse
* Permission to read business schemas and tables
* Permission to write to DinMo’s technical schemas

If the test succeeds, your Microsoft Fabric source is now connected to DinMo.

### Additional recommendations

* **Use a dedicated Service Principal** for DinMo.
* **Scope read access only to the schemas or tables needed** for DinMo use cases.
* **Keep DinMo technical objects isolated** in dedicated schemas.
* **Use a dedicated Warehouse** for DinMo if you want to isolate performance and administration.
* **Rotate client secrets regularly** and update the DinMo connection before expiration.
* **Document the Warehouse name explicitly** since Fabric requires it in the connection string.

### Troubleshooting common issues

#### 1. Connection test fails

**Problem:** DinMo cannot connect to Fabric.

**Checks:**

* Verify the SQL endpoint hostname
* Verify the port is `1433`
* Verify the Warehouse name is entered exactly in the **Database** field
* Verify the Tenant ID, Client ID, and Client Secret
* Verify the service principal has access to the Warehouse in Fabric

#### 2. Service Principal authentication works but SQL access fails

**Problem:** The service principal exists in Entra, but DinMo cannot query the Warehouse.

**Solution:**

* Ensure the service principal has been granted access to the Warehouse in Fabric
* Ensure a corresponding SQL user exists in the Warehouse
* Ensure SQL permissions were granted to that SQL user

#### 3. Missing permissions on technical schemas

**Problem:** DinMo connects successfully but cannot create tables, views, or technical objects.

**Solution:**

* Verify that `CONTROL` was granted on:
  * `dinmo_segments`
  * `dinmo_stats`
  * `dinmo_delta_storage`
  * `dinmo_predictions`
  * `dinmo_identity` if applicable

#### 4. Missing permissions on business tables

**Problem:** DinMo cannot preview or query the data model.

**Solution:**

* Grant `SELECT` on the required schemas, tables, and views
* If your business data spans multiple schemas, repeat the grants for each relevant schema

#### 5. Newly created Service Principal still fails on some Fabric operations

**Problem:** The service principal appears correctly configured, but some Fabric-related operations still fail unexpectedly.

**Solution:**

* In some Fabric environments, a newly created service principal may require an initial successful Fabric API call before all access paths behave as expected
* Confirm tenant settings and re-test after the service principal has been fully initialized

#### 6. External storage commands fail later

**Problem:** Commands such as `COPY INTO` or `OPENROWSET` fail even though the SQL connection itself works.

**Solution:**

* Validate the Fabric tenant settings related to service principals
* Validate that the service principal has been properly initialized in Fabric
* Validate that any required external storage access policies are in place

***

If you encounter an error or question not listed above and need assistance, do not hesitate to reach out to your account manager.