Skip to main content
Version: v1.7.5-1 🚧

VEX Migration

The VEX Migration page gives administrators a live view of a backend-to-backend vector index migration. Use it to track progress, identify failed collections, and retry individual failures — all without restarting the deployment.

The page is only relevant while a migration is configured. If no migration is running, the page still opens but shows zero activity.

Administrator Guide

This page is intended for administrators who are running or have recently run a vector index migration. For configuration instructions and a full explanation of the blocking migration strategy, see Migrating between backends.

How to open it​

  1. Sign in as a user with the admin role.
  2. In Enterprise h2oGPTe, click Account Circle.
  3. Select System Dashboard.
  4. Under System overview, click VEX Migration.

Vex Migration Dashboard

Migration Configuration​

The top section shows the settings currently active on the running deployment.

FieldWhat it shows
Source backendThe backend collections are being read from (for example, internal for embedded HNSW/SQLite).
Destination backendThe backend collections are being written to (for example, postgres).
StatusEnabled when a migration is configured; Disabled when mux.config.vexMigration.enabled is false.
ModeBlocking — mux halts startup until the migration completes. Live — migration runs as a background loop while the deployment serves traffic normally.
ActivityPulses while the background sweep is running or while any collection cluster-wide is actively copying. A steady (non-pulsing) indicator means the sweep is idle.
note

Live mode configuration is not yet published in this release's docs — see Vector database for what's currently documented.

Summary stats​

Five cards below the configuration panel count collections by their current migration state. When the migration is disabled, the Pending and In progress cards are hidden.

CardWhat it counts
TotalAll collections in the deployment.
MigratedCollections successfully moved to the destination backend.
PendingCollections still on the source backend, waiting to be copied.
In progressCollections actively being copied at this moment.
FailedCollections whose most recent migration attempt ended in an error. These also appear in the failed-collections table below.

A progress bar shows the percentage of collections that have been migrated (Migrated ÷ Total). It only appears when a migration is enabled and at least one collection exists.

Collections with errors​

This table lists every collection whose most recent migration attempt failed. Use it to diagnose and retry failures.

Columns:

  • Collection — name of the collection (or the collection ID if no name is set).
  • Owner — username of the collection's owner.
  • Error — the error message recorded when the migration attempt failed.
  • Failed at — timestamp of the failure.
  • Actions — a Retry button that queues the collection for an immediate re-migration attempt.

Filtering and pagination: Use the search box to filter by collection name or owner. Results are paginated.

Retrying a failed collection: Click Retry on a row to queue that collection for re-migration. The retry runs asynchronously — the row clears from the table once the retry succeeds. If the retry fails again, the row reappears with an updated error and timestamp.

tip

A failed collection usually means the migration worker hit a timeout or encountered a transient error. Check the mux service logs for details before retrying, especially if many collections failed at the same time.

Auto-refresh​

The page refreshes automatically every 30 seconds:

  • Stats cards and progress bar refresh on every tick.
  • Failed-collections table refreshes only when you are on page 1 with no active search filter, so an ongoing search is not interrupted by an automatic reload.
Feedback