How to use Hot Swapping for datasets

Use a dataset alias to switch the dataset your applications read from, for recovery or breaking content migrations

Dataset Hot Swapping allows a codebase to reference a single, named entity, which can then point to different datasets depending on the need of the project.

Your applications query an alias instead of a dataset name, so you can switch the dataset behind the alias without copying or migrating data. Hot swapping fits two cases:

• Recovery: point the alias back at a known-good dataset after a bad change.
• Breaking schema or content migrations: restructure content in a copy, validate it, then link the alias to the copy.

For other content changes, you don't need a second dataset. Editors can stage and preview changes in the production dataset with content releases, then publish them together. See Development, staging, and production environments.

Aliases are read-only. GROQ queries and document lookups work through an alias. Everything else needs the real dataset name:

• Studios and writes: mutations, actions, listeners, history, and export requests through an alias fail with an error such as You can't perform a mutate operation through an alias. A studio writes and listens, so configure each studio with the real dataset name.
• Live Content API: a live connection through an alias opens, but no updates arrive. Use the real dataset name for live queries.
• Webhooks: a webhook's dataset must be a real dataset name or *.
• Functions: deploying a function whose event.resource names an alias fails with event.resource.id references a dataset that either does not exist or you do not have access to. A deployed function keeps listening to the dataset it was deployed with.
• Roles and tokens: dataset-scoped roles and grants name a real dataset. You can't scope a permission to an alias.
• Caching: sync tags include the real dataset name. After a swap, queries return new sync tags, so caches keyed on them start empty.

Treat each swap as a deployment. Point your studios at the new dataset, update webhooks and redeploy functions that name the old one, and check that the roles and tokens your applications use have access to the new dataset.

This enterprise feature is included in the Sanity CLI. By running a series of commands, an alias can be created, linked, unlinked, or deleted.

# List all aliases and datasets
sanity dataset list

# Create a new alias
sanity dataset alias create <new-alias> <dataset-to-alias>

# Change what dataset an alias points to
sanity dataset alias link <alias-to-point> <dataset-to-point-to>

# Unlink an alias
sanity dataset alias unlink <alias-to-unlink>

# Delete an Alias
sanity dataset alias delete <alias-to-delete>

# List all aliases and datasets
sanity dataset list

Before a dataset can be swapped, a new alias must be created and referenced by code. To create a new alias for use as a production alias run the following code:

# Creates a dataset alias and prompts for an alias name
sanity dataset alias create

# Creates an unlinked dataset alias named "production"
sanity dataset alias create production

# Creates a dataset alias named "production" linked to "productionDataset"
sanity dataset alias create production productionDataset

Anywhere the code references the productionDataset it can now be swapped for ~production.

In order to identify incoming alias requests from a client, an alias should be prefixed with the special character ~. In this example, even though the create command was given an alias name of production, when referencing it in requests, the string ~production should be used.

// Example from sanity.js file
// This code creates a connection to the datastore
// and connects to productionDataset through the production alias

import {createClient} from '@sanity/client'

const client = createClient({
  projectId: 'abc123',
  dataset: '~production',
  apiVersion: '2021-03-25',
  useCdn: false,
})

Once an alias is created, the dataset behind it can be hot-swapped at any time. In this example, the codebase references the ~production alias. When a new release is ready, a dataset of featureDataset can be created via Cloud Clone from the current dataset behind the production alias. Any data changes can be made, then the production alias can be Hot Swapped to the new featureDataset.

# Hot swap the production Alias to point to the featureDataset
sanity dataset alias link production featureDataset

When an alias is not currently being used, but should be included in the alias list, it can be unlinked from a dataset.

# Unlinks the development alias.
# The development alias will still appear 
# in the sanity dataset alias link command
sanity dataset alias unlink development

When an alias is no longer needed, it can be deleted from the alias list. The delete command only deletes the alias and not any datasets associated with it.

# Deletes the outdated alias
sanity dataset alias delete outdated

The list command provides a list of all Datasets and aliases associated with the current project and shows the linked dataset for each alias.

# Returns a list of datasets and aliases with their associated datasets
sanity dataset list