Edit

Share via

Microsoft Fabric mirroring public REST API

The public APIs for Fabric mirroring consist of two categories: (1) CRUD operations for Fabric mirrored database item and (2) Start/stop and monitoring operations. The primary online reference documentation for Microsoft Fabric REST APIs can be found in Microsoft Fabric REST API references.

Note

These REST APIs don't apply to mirrored database from Azure Databricks.

Create mirrored database

REST API - Items - Create mirrored database

Before you create mirrored database, the corresponding data source connection is needed. If you don't have a connection yet, refer to create new connection using portal and use that connection ID in the following definition. You can also refer to create new connection REST API to create new connection using Fabric REST APIs.

Example:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases

Body:

{
    "displayName": "Mirrored database 1",
    "description": "A mirrored database description",
    "definition": {
        "parts": [
            {
                "path": "mirroring.json",
                "payload": "eyAicHJvcGVydGllcy..WJsZSIgfSB9IH0gXSB9IH0",
                "payloadType": "InlineBase64"
            }
        ]
    }
}

The payload property in previous JSON body is Base64 encoded. You can use Base64 Encode and Decode to encode.

The original JSON definition examples are as follows. For more information about the mirrored database item definition, including a breakdown of the definition structure, see Mirrored database item definition.

Important

To mirror data from Azure SQL Database, Azure SQL Managed Instance, Azure Database for PostgreSQL or SQL Server 2025, you need to also do the following before start mirroring:

  1. Enable System Assigned Managed Identity (SAMI) of your Azure SQL logical server, Azure SQL Managed Instance, Azure Database for PostgreSQL or SQL Server.
  2. Grant the SAMI Read and Write permission to the mirrored database. Currently you need to do this on the Fabric portal. Alternatively, you can grant SAMI workspace role using Add Workspace Role Assignment API.

Note

defaultSchema property indicates whether to replicate the schema hierarchy from the source database.

JSON definition example of replicating entire database

To mirror all the tables from the source database:

{
    "properties": {
        "source": {
            "type": "<your source type>",
            "typeProperties": {
                "connection": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
                "database": "xxxx"
            }
        },
        "target": {
            "type": "MountedRelationalDatabase",
            "typeProperties": {
                "defaultSchema": "xxxx",
                "format": "Delta"
            }
        }
    }
}

JSON definition example of replicating specified tables

To mirror selective tables from the source database, you can specify the mountedTables property as in the following example.

{
    "properties": {
        "source": {
            "type": "<your source type>",
            "typeProperties": {
                "connection": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
                "database": "xxxx"
            }
        },
        "target": {
            "type": "MountedRelationalDatabase",
            "typeProperties": {
                "defaultSchema": "xxxx",
                "format": "Delta"
            }
        },
        "mountedTables": [
            {
                "source": {
                    "typeProperties": {
                        "schemaName": "xxxx",
                        "tableName": "xxxx"
                    }
                }
            }
        ]
    }
}

Response 201:

{ 
    "id": "<mirrored database ID>", 
    "type": "MirroredDatabase", 
    "displayName": "Mirrored database 1", 
    "description": "A mirrored database description", 
    "workspaceId": "<your workspace ID>" 
}

Delete mirrored database

REST API - Items - Delete mirrored database

Example:

DELETE https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>

Response 200: (No body)

Get mirrored database

REST API - Items - Get mirrored database

Example:

GET https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>

Response 200:

{
    "displayName": "Mirrored database 1",
    "description": "A mirrored database description.",
    "type": "MirroredDatabase",
    "workspaceId": "<your workspace ID>",
    "id": "<mirrored database ID>",
    "properties": {
        "oneLakeTablesPath": "https://onelake.dfs.fabric.microsoft.com/<your workspace ID>/<mirrored database ID>/Tables",
        "sqlEndpointProperties": {
            "connectionString": "xxxx.xxxx.fabric.microsoft.com",
            "id": "b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2",
            "provisioningStatus": "Success"
        },
        "defaultSchema": "xxxx"
    }
}

Get mirrored database definition

REST API - Items - Get mirrored database definition

Example:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/getDefinition

Response 200:

{ 
    "definition": { 
        "parts":[ 
            { 
                "path": "mirroring.json", 
                "payload": "eyAicHJvcGVydGllcy..WJsZSIgfSB9IH0gXSB9IH0", 
                "payloadType": "InlineBase64" 
            } 
        ] 
    } 
}

List mirrored databases

REST API - Items - List mirrored databases

Example:

GET https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases

Response 200:

{ 
    "value": [ 
        {
            "displayName": "Mirrored database 1",
            "description": "A mirrored database description.",
            "type": "MirroredDatabase",
            "workspaceId": "<your workspace ID>",
            "id": "<mirrored database ID>",
            "properties": {
                "oneLakeTablesPath": "https://onelake.dfs.fabric.microsoft.com/<your workspace ID>/<mirrored database ID>/Tables",
                "sqlEndpointProperties": {
                    "connectionString": "xxxx.xxxx.fabric.microsoft.com",
                    "id": "b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2",
                    "provisioningStatus": "Success"
                },
                "defaultSchema": "xxxx"
            }
        }
    ] 
}

Update mirrored database

REST API - Items - Update mirrored database

Example:

PATCH https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>

Body:

{
    "displayName": "MirroredDatabase's New name",
    "description": "A new description for mirrored database."
}

Response 200:

{
    "displayName": "MirroredDatabase's New name",
    "description": "A new description for mirrored database.",
    "type": "MirroredDatabase",
    "workspaceId": "<your workspace ID>",
    "id": "<mirrored database ID>"
}

Update mirrored database definition

REST API - Items - Update mirrored database definition

Example:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/updateDefinition

Body:

{ 
  "definition": { 
    "parts": [ 
      { 
        "path": "mirroring.json", 
        "payload": "eyAicHJvcGVydGllcy..WJsZSIgfSB9IH0gXSB9IH0", 
        "payloadType": "InlineBase64" 
      } 
    ] 
  } 
}

Response 200: (No body)

The payload property in previous JSON body is Base64 encoded. You can use Base64 Encode and Decode to encode.

Note

This API supports adding/removing tables by refreshing the mountedTables property. It also supports updating the source connection ID, database name, and default schema (these three properties can only be updated when Get mirroring status API returns Initialized/Stopped).

Configure data retention

You can set the retention period for mirrored data using the retentionInDays property. The default value is seven days. The allowed values are integer between 1 and 30.

JSON definition example before Base64 encoding:

{
    "properties": {
        "source": {...},
        "target": {
            "type": "MountedRelationalDatabase",
            "typeProperties": {
                "defaultSchema": "xxxx",
                "format": "Delta",
                "retentionInDays": 1
            }
        }
    }
}

Get mirroring status

REST API - Mirroring - Get mirroring status

This API returns the status of mirrored database instance. The list of available statuses are provided at values of MirroringStatus.

Example:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/getMirroringStatus

Response 200:

{
    "status": "Running"
}

Start mirroring

REST API - Mirroring - Start mirroring

Example:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/startMirroring

Response 200: (No body)

Note

Mirroring can't be started when above Get mirroring status API returns Initializing status.

Get tables mirroring status

REST API - Mirroring - Get tables mirroring status

If mirroring is started and Get mirroring status API returns Running status, this API returns the status and metrics of tables replication.

Example:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/getTablesMirroringStatus

Response 200:

{
    "continuationToken": null,
    "continuationUri": null,
    "data": [
        {
            "sourceSchemaName": "dbo",
            "sourceTableName": "test",
            "status": "Replicating",
            "metrics": {
                "processedBytes": 1247,
                "processedRows": 6,
                "lastSyncDateTime": "2024-10-08T05:07:11.0663362Z"
            }
        }
    ]
}

Stop mirroring

REST API - Mirroring - Stop mirroring

Example:

POST https://api.fabric.microsoft.com/v1/workspaces/<your workspace ID>/mirroredDatabases/<mirrored database ID>/stopMirroring

Response 200: (No body)

Note

After stopping mirroring, you can call Get mirroring status API to query the mirroring status.

Microsoft Fabric .NET SDK

The .NET SDK that supports Fabric mirroring is available at Microsoft Fabric .NET SDK. The version needs to be >= 1.0.0-beta.11.

Related content