Can you migrate vector embeddings without downtime?

Yes. DBX uses shadow migration (VMIGRATE) to stream new embeddings into an off-line target index while the current index continues serving queries. Once populated, DBX performs an atomic pointer swap. Cancel keeps the current index untouched.

How does VMIGRATE handle embedding dimension changes?

VMIGRATE START accepts a new dimension and optional encoding, so you can change from 768-dim to 1536-dim embeddings or switch from float32 to SQ8 encoding during migration. The shadow index is built with the new parameters while the old index continues serving at its original dimension.

What happens if the migration is cancelled?

VMIGRATE CANCEL discards the shadow index and leaves the live index completely untouched. An empty migration (no vectors added to the shadow) is automatically rejected on swap, preventing accidental data loss.

Is VMIGRATE per-tenant or cluster-wide?

VMIGRATE is per-tenant. Each tenant's migration lifecycle is independent — you can migrate one customer's embeddings while all other tenants continue normal operation on their existing indexes.

Operational vector upgrade

Zero-Downtime Vector Migration for Live AI Embeddings

Change embedding models, dimensions, or encodings without taking your tenant offline. VMIGRATE builds a shadow index while the current one keeps serving queries.

The Problem: Re-indexing Kills Availability in Shared Clusters

When you upgrade from text-embedding-ada-002 to text-embedding-3-large, most vector databases require you to either delete the existing index and rebuild from scratch (total downtime) or stand up a parallel database, re-index into it, and cutover at the DNS level.

For per-tenant AI products serving hundreds of customers, neither approach works. You need to migrate each customer's embeddings independently, in place, while their application keeps making queries.

How Shadow Index Migration Works

DBX uses a three-phase migration lifecycle per tenant:

Start — declare a shadow index with the target dimension and encoding
Stream — add re-embedded vectors to the shadow while the live index keeps serving reads
Swap — atomically promote the shadow index and retire the old one

The migration is WAL-durable. Cancel at any point to keep the live index untouched. An empty shadow is rejected on swap — DBX will not let you accidentally blank out a customer's vector memory.

RESP wire protocol

Migrate Live Indexes with VMIGRATE

RESP commands

# 1. Start a shadow index with new dimension (1536-dim, cosine, SQ8)
VMIGRATE START tenant_docs 1536 cosine

# 2. Stream re-embedded vectors into the shadow
VMIGRATE ADD tenant_docs doc_001 0.012 -0.043 0.091 ...
VMIGRATE ADD tenant_docs doc_002 0.008 0.027 -0.055 ...
VMIGRATE ADD tenant_docs doc_003 -0.031 0.064 0.019 ...

# 3. Promote the shadow — live index swaps atomically
VMIGRATE SWAP tenant_docs

# Or cancel — live index stays untouched
VMIGRATE CANCEL tenant_docs

Re-embedding and transfer remain the caller's work. DBX does not run embedding models. The migration lifecycle is not yet a replicated WAL protocol.

Python SDK

Automate Migration with the DBX Python Client

Python

from dbx import DBXClient
import openai

client = DBXClient("http://localhost:8000", token="$DBX_TOKEN")
tenant = "acme-corp"

# Start shadow with new dimensions
client.vmigrate_start(tenant, index="docs", dim=1536, metric="cosine")

# Re-embed and stream each document
for doc in get_all_documents(tenant):
    new_vec = openai.embeddings.create(
        model="text-embedding-3-large",
        input=doc.text
    ).data[0].embedding
    client.vmigrate_add(tenant, index="docs", id=doc.id, vector=new_vec)

# Atomic swap — queries now use the new embeddings
client.vmigrate_swap(tenant, index="docs")

Migration Safety Guarantees

Live reads continue

The current index serves VSEARCH, VSIM, and VFUSE queries throughout the migration. No read downtime, no degraded recall.

Empty swap rejected

Attempting to swap an empty shadow index returns an error. DBX prevents accidentally replacing a populated index with an empty one.

Per-tenant independence

Migration lifecycle is per-tenant. Migrating Tenant A's embeddings has no effect on Tenant B's index or query performance.

Upgrade your embeddings without downtime.

Get started All features