Configuring sharding

From AuthP version 6 and above there are four things to setup a sharding multi-tenant application. They are:

1. Set the AuthPermissionsOptions's TenantType
2. Register the DistributedFileStoreCache
3. Add the SetupMultiTenantSharding method to register sharding
4. Select which mode you want to use.

The following sections details the four steps, with longer section at the end to explain about the two modes.

NOTE: There are two examples of sharding multi-tenant applications to help you understanding sharding. Example6 uses the hybrid mode and Example7 uses the sharding-only mode.

1. Set the AuthPermissionsOptions's TenantType

You need set the AuthPermissionsOptions's TenantType with one of the following enums

• TenantTypes.SingleLevel - see this section for details how the tenant's data is stored
• TenantTypes.HierarchicalTenant - see this section for details how the tenant's data is stored

This should be set in the first RegisterAuthPermissions method, e.g.

builder.Services.RegisterAuthPermissions<Example7Permissions>(options =>
{
   options.TenantType = TenantTypes.SingleLevel;
   //... rest of code left out

2. Register the DistributedFileStoreCache

The AuthP version uses the Net.DistributedFileStoreCache to hold the sharding entries which holds the information to select the correct database based on the logged-in user. There is the code for registering

builder.Services.AddDistributedFileStoreCache(options =>
{
    options.WhichVersion = FileStoreCacheVersions.Class;
}, builder.Environment);

NOTE: Go to the Net.DistributedFileStoreCache's documentation for a more detailed on how to register the DistributedFileStoreCache.

3. Add the SetupMultiTenantSharding method to register sharding

You need add the SetupMultiTenantSharding method to the registration of the AuthP features.

   .SetupMultiTenantSharding(.. see mode section below ...)

4. Select which mode you want to use.

Its easy to set the mode but the documentation below is long as it explains what each mode does.

From AuthP version 6 and above you have the opportunity to select how the tenant's data. In the Sharding explained document explains the two modes, hybrid or sharding-only, and information to help you to select the mode that works for your project. This document then tells you:

• a. How to select a mode
• b. The changes the mode makes to your app
• c. What is the result of being this mode?

Here is a list of what they do, and want is the result of being in each mode.

Hybrid mode

a. How to select the hybrid mode?

When you add the SetupMultiTenantSharding method to the AuthP you must provide a new ShardingEntryOptions with its hybridmode ctor parameter to true as shown below.

   .SetupMultiTenantSharding(new ShardingEntryOptions(true))

NOTE: See the Example6's Program for a multi-tenant app using hybrid mode.

b. The changes that hybrid mode makes to your app

• The "DefaultConnection" connection string, which provides the database use by AuthP's to hold its data, is shown in the list of connection strings available to add sharing tenants.
• On the first deployment of your multi-tenant application to a new web server, then a default sharding entry (see the How AuthP handles sharding document on sharding entries are) is added to the sharding entries and linked to the "DefaultConnection" connection string. This default sharding entry allows you immediately add sharing tenants to the database defined by the "DefaultConnection" connection string.

c. What is the result of being in Hybrid mode?

When in hybrid mode the first deployment the application sets up connection strings and a sharding entry that allows a new shared tenant without need to manually set up a sharding entry. This also me to create a example of using sharding in the AuthP repo called Example6, which you can run to try it out, including demo users and tenants via AuthP's Bulk load feature.

Sharding-Only mode

a. How to select the sharding-only mode?

The SetupMultiTenantSharding method will default to sharding-only mode.

   .SetupMultiTenantSharding()

NOTE: See the Example7's Program for a multi-tenant app using sharding-only mode.

b. The changes that sharding-only mode makes to your app

• The "DefaultConnection" connection string is not listed in the connection strings available to add sharing tenants, unless the "DefaultConnection" connection string is the only connection string. This useful because:
  • If you add connection strings linked to different servers, they are shown and the "DefaultConnection" connection string isn't (see Example7's appsettings.json file.
  • But only want one server, found by the "DefaultConnection" connection string, then this will work without providing any other connection strings.
• On the first deployment of your multi-tenant application to a new web server the list of sharding entries is empty.

c. What is the result of being in Sharding-Only mode?

Because you have sharding-only tenants and there is Shard-only tenant service that makes it very easy to create and delete tenants. Therefore its better to NOT have pre-configured like the hybrid mode and on first deployment the application. This means you application starts there will no tenants or sharding entries (see the How AuthP handles sharding document for sharding entries), but it is very simple to add a new tenant.

Additional resources

• Multi tenant explained
• Sharding explained
• How AuthP handles sharding
• Extra help for shading‐only apps