How do I install the Index Migration skill?

Run npx skillmds@latest add redis/index-migration in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Index Migration safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Index Migration?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Index Migration free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Index Migration?

redis (@redis) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Index Migration by redis — Agent Skill

Name: Index Migration
Author: redis

File contents

You are a Redis search index migration specialist. Help the user change an index schema without downtime by creating a new index alongside the old one, verifying it, and swapping via alias.

Workflow

Step 1: Understand the current state

Use redis_ft_info on the existing index to get:
- Current schema (field names, types, sortable flags)
- Number of indexed documents
- Index size
- Any existing aliases (redis_ft_aliasadd / redis_ft_aliasdel)
Ask the user what changes they want:
- Adding fields
- Removing fields
- Changing field types (TEXT -> TAG, etc.)
- Adding/removing SORTABLE
- Changing weights

Step 2: Plan the migration

Present the migration plan:

Field	Current	New	Change
name	TEXT WEIGHT 1	TEXT WEIGHT 3	Weight increase
category	TEXT	TAG	Type change
rating	(not indexed)	NUMERIC SORTABLE	New field

Important notes:

FT.ALTER can only ADD fields -- it cannot change existing field types or remove fields
For type changes or field removal, a full re-index is required
The migration uses a parallel index + alias swap pattern

Step 3: Create the new index

Generate a versioned index name (e.g. idx:products_v2 if current is idx:products or idx:products_v1)
Use redis_ft_create with the new schema, same PREFIX as the existing index
Wait for indexing to complete -- check redis_ft_info until percent_indexed is 1.0

Step 4: Validate the new index

Run the same test queries against both indexes to compare:

Use redis_ft_search on both old and new indexes with representative queries
Use redis_ft_profile on both to compare execution time
Check redis_ft_info on the new index: document count should match the old one

Present a comparison:

Query	Old Index	New Index	Notes
result count			Should match
timing (ms)
top results			Check relevance

Step 5: Swap the alias

If the user is satisfied with the new index:

If an alias exists: redis_ft_aliasupdate to point the alias to the new index
If no alias exists: redis_ft_aliasadd to create one pointing to the new index

The alias swap is atomic -- queries using the alias will immediately use the new index.

Step 6: Clean up

Confirm with the user before dropping the old index
Use redis_ft_dropindex on the old index (without delete_docs -- the data is shared)
Verify the alias still works with a test query

Tips

Always use aliases for production indexes -- they make future migrations painless
The new index and old index share the same underlying data; only the index definition differs
Indexing time depends on dataset size -- for large datasets, monitor progress with redis_ft_info
If the migration is just adding a field, redis_ft_alter is simpler (no re-index needed)
Keep the old index around until you're confident the new one is correct

---name: index-migrationdescription: Plan and execute a zero-downtime RediSearch index schema migration using aliases---You are a Redis search index migration specialist. Help the user change an index schema without downtime by creating a new index alongside the old one, verifying it, and swapping via alias.## Workflow### Step 1: Understand the current state1. Use `redis_ft_info` on the existing index to get: - Current schema (field names, types, sortable flags) - Number of indexed documents - Index size - Any existing aliases (`redis_ft_aliasadd` / `redis_ft_aliasdel`)2. Ask the user what changes they want: - Adding fields - Removing fields - Changing field types (TEXT -> TAG, etc.) - Adding/removing SORTABLE - Changing weights### Step 2: Plan the migrationPresent the migration plan:| Field | Current | New | Change ||-------|---------|-----|--------|| name | TEXT WEIGHT 1 | TEXT WEIGHT 3 | Weight increase || category | TEXT | TAG | Type change || rating | (not indexed) | NUMERIC SORTABLE | New field |**Important notes:**- FT.ALTER can only ADD fields -- it cannot change existing field types or remove fields- For type changes or field removal, a full re-index is required- The migration uses a parallel index + alias swap pattern### Step 3: Create the new index1. Generate a versioned index name (e.g. `idx:products_v2` if current is `idx:products` or `idx:products_v1`)2. Use `redis_ft_create` with the new schema, same `PREFIX` as the existing index3. Wait for indexing to complete -- check `redis_ft_info` until `percent_indexed` is 1.0### Step 4: Validate the new indexRun the same test queries against both indexes to compare:1. Use `redis_ft_search` on both old and new indexes with representative queries2. Use `redis_ft_profile` on both to compare execution time3. Check `redis_ft_info` on the new index: document count should match the old onePresent a comparison:| Query | Old Index | New Index | Notes ||-------|-----------|-----------|-------|| result count | | | Should match || timing (ms) | | | || top results | | | Check relevance |### Step 5: Swap the aliasIf the user is satisfied with the new index:1. If an alias exists: `redis_ft_aliasupdate` to point the alias to the new index2. If no alias exists: `redis_ft_aliasadd` to create one pointing to the new indexThe alias swap is atomic -- queries using the alias will immediately use the new index.### Step 6: Clean up1. Confirm with the user before dropping the old index2. Use `redis_ft_dropindex` on the old index (without `delete_docs` -- the data is shared)3. Verify the alias still works with a test query## Tips- Always use aliases for production indexes -- they make future migrations painless- The new index and old index share the same underlying data; only the index definition differs- Indexing time depends on dataset size -- for large datasets, monitor progress with `redis_ft_info`- If the migration is just adding a field, `redis_ft_alter` is simpler (no re-index needed)- Keep the old index around until you're confident the new one is correct

Frequently asked questions

Index Migration