Follower commands

Management commands for managing your follower configuration. These commands run synchronously but are applied on the next periodic schema refresh, which may result in a short delay until the new configuration is applied.

The follower commands include database level commands and table level commands.

Permissions

You must have at least Database Admin permissions to run this command.

Database policy overrides

A leader database can override the following database-level policies in the follower cluster: Caching policy and Authorized principals.

Caching policy

The default caching policy for the follower cluster uses the leader cluster database and table-level caching policies.

Authorized principals

Table and materialized views policy overrides

By default, tables and materialized views in a database that is being followed by a follower cluster keep the source entity’s caching policy. However, table and materialized view caching policies can be overridden in the follower cluster. Use the replace option to override the source entity’s caching policy.

Database level commands

.show follower database

Shows a database (or databases) followed from other leader cluster, which have one or more database-level overrides configured.

Syntax

.show follower database DatabaseName

.show follower databases (DatabaseName1,…,DatabaseNameN)

Output

.alter follower database policy caching

Alters a follower database caching policy, to override the one set on the source database in the leader cluster.

Notes

• The default modification kind for caching policies is union. To change the modification kind, use the .alter follower database caching-policies-modification-kind command.
• Viewing the policy or effective policies after the change can be done using the .show commands:
  • .show database policy retention
  • .show database details
  • .show table details
• Viewing the override settings on the follower database after the change is made can be done using .show follower database

Syntax

.alter follower database DatabaseName policy caching hot = HotDataSpan

Example

.alter follower database MyDb policy caching hot = 7d

.delete follower database policy caching

Deletes a follower database override caching policy. This deletion causes the policy set on the source database in the leader cluster the effective one.

Notes

• Viewing the policy or effective policies after the change can be done using the .show commands:
  • .show database policy retention
  • .show database details
  • .show table details
• Viewing the override settings on the follower database after the change can be done using .show follower database

Syntax

.delete follower database DatabaseName policy caching

Example

.delete follower database MyDB policy caching

.add follower database principals

Adds authorized principal(s) to the follower database collection of override authorized principals. Notes

• The default modification kind for such authorized principals is none. To change the modification kind use alter follower database principals-modification-kind.
• Viewing the effective collection of principals after the change can be done using the .show commands:
  • .show database principals
  • .show database details
• Viewing the override settings on the follower database after the change can be done using .show follower database

Syntax

.add follower database DatabaseName (admins | users | viewers | monitors) Role (principal1,…,principalN) ['notes']

Example

.add follower database MyDB viewers ('aadgroup=mygroup@microsoft.com') 'My Group'

.drop follower database principals

Drops authorized principal(s) from the follower database collection of override authorized principals.

Syntax

.drop follower database DatabaseName (admins | users | viewers | monitors) (principal1,…,principalN)

Example

.drop follower database MyDB viewers ('aadgroup=mygroup@microsoft.com')

.alter follower database principals-modification-kind

Alters the follower database authorized principals modification kind.

Syntax

.alter follower database DatabaseName principals-modification-kind = (none | union | replace)

Example

.alter follower database MyDB principals-modification-kind = union

.alter follower database caching-policies-modification-kind

Alters the caching policies modification kind for the follower database, table, and materialized views.

Syntax

.alter follower database DatabaseName caching-policies-modification-kind = (none | union | replace)

Example

.alter follower database MyDB caching-policies-modification-kind = union

.alter follower database prefetch-extents

The follower cluster can wait for new data to be fetched from the underlying storage to the nodes’ SSD (cache) before making this data queryable.

The following command alters the follower database configuration of pre-fetching new extents upon each schema refresh.

Syntax

.alter follower database DatabaseName prefetch-extents = (true | false)

Example

.alter follower database MyDB prefetch-extents = false

Tables and materialized views commands

Alter follower table or materialized view caching policy

Alters a table’s or a materialized view’s caching policy on the follower database, to override the policy set on the source database in the leader cluster.

Syntax

.alter follower database DatabaseName table TableName policy caching hot = HotDataSpan

.alter follower database DatabaseName tables (TableName1,…,TableNameN) policy caching hot = HotDataSpan

.alter follower database DatabaseName materialized-view ViewName policy caching hot = HotDataSpan

.alter follower database DatabaseName materialized-views (ViewName1,…,ViewNameN) policy caching hot = HotDataSpan

Examples

.alter follower database MyDb tables (Table1, Table2) policy caching hot = 7d

.alter follower database MyDb materialized-views (View1, View2) policy caching hot = 7d

Delete follower table or materialized view caching policy

Deletes an override for a table’s or a materialized-view’s caching policy on the follower database. The policy set on the source database in the leader cluster will now be the effective policy.

Syntax

.delete follower database DatabaseName table TableName policy caching

.delete follower database DatabaseName tables (TableName1,…,TableNameN) policy caching

.delete follower database DatabaseName materialized-view ViewName policy caching

.delete follower database DatabaseName materialized-views (ViewName1,…,ViewNameN) policy caching

Example

.delete follower database MyDB tables (Table1, Table2) policy caching

.delete follower database MyDB materialized-views (View1, View2) policy caching

Sample configuration

The following are sample steps to configure a follower database.

In this example:

• Our follower cluster, MyFollowerCluster will be following database MyDatabase from the leader cluster, MyLeaderCluster.

  • MyDatabase has N tables: MyTable1, MyTable2, MyTable3, … MyTableN (N > 3).
  • On MyLeaderCluster:

  MyTable1 caching policy	MyTable2 caching policy	MyTable3…MyTableN caching policy	MyDatabase Authorized principals
  hot data span = 7d	hot data span = 30d	hot data span = 365d	Viewers = aadgroup=scubadivers@contoso.com; Admins = aaduser=jack@contoso.com

  • On MyFollowerCluster we want:

  MyTable1 caching policy	MyTable2 caching policy	MyTable3…MyTableN caching policy	MyDatabase Authorized principals
  hot data span = 1d	hot data span = 3d	hot data span = 0d (nothing is cached)	Admins = aaduser=jack@contoso.com, Viewers = aaduser=jill@contoso.com

Steps to execute

Prerequisite: Set up cluster MyFollowerCluster to follow database MyDatabase from cluster MyLeaderCluster.

Show the current configuration

See the current configuration according to which MyDatabase is being followed on MyFollowerCluster:

.show follower database MyDatabase
| evaluate narrow() // just for presentation purposes

Override authorized principals

Replace the collection of authorized principals for MyDatabase on MyFollowerCluster with a collection that includes only one Microsoft Entra user as the database admin, and one Microsoft Entra user as a database viewer:

.add follower database MyDatabase admins ('aaduser=jack@contoso.com')

.add follower database MyDatabase viewers ('aaduser=jill@contoso.com')

.alter follower database MyDatabase principals-modification-kind = replace

Only those two specific principals are authorized to access MyDatabase on MyFollowerCluster

.show database MyDatabase principals

.show follower database MyDatabase
| mv-expand parse_json(AuthorizedPrincipalsOverride)
| project AuthorizedPrincipalsOverride.Principal.FullyQualifiedName

Override Caching policies

Replace the collection of database and table-level caching policies for MyDatabase on MyFollowerCluster by setting all tables to not have their data cached, excluding two specific tables - MyTable1, MyTable2 - that will have their data cached for periods of 1d and 3d, respectively:

.alter follower database MyDatabase policy caching hot = 0d

.alter follower database MyDatabase table MyTable1 policy caching hot = 1d

.alter follower database MyDatabase table MyTable2 policy caching hot = 3d

.alter follower database MyDatabase caching-policies-modification-kind = replace

Only those two specific tables have data cached, and the rest of the tables have a hot data period of 0d:

.show tables details
| summarize TableNames = make_list(TableName) by CachingPolicy

.show follower database MyDatabase
| mv-expand parse_json(TableMetadataOverrides)
| project TableMetadataOverrides

Summary

See the current configuration where MyDatabase is being followed on MyFollowerCluster:

.show follower database MyDatabase
| evaluate narrow() // just for presentation purposes