Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🛗 fix: Add Tenant Index Upgrade Migration (#15767)
Danny Aviladad20b115e1f
diff --git a/UPGRADING.md b/UPGRADING.mdnew file mode 100644index 0000000000..51eab7cc67--- /dev/null+++ b/UPGRADING.md@@ -0,0 +1,62 @@+# Upgrading LibreChat++## Tenant index migration (v0.8.7 and earlier databases)++Upgrading an existing database can log `Index build failed` for User, Role,+Preset, AccessRole, MCPServer, AgentCategory, Message, or Conversation. Older+unique indexes (for example `email_1` or `name_1`) conflict with current non-unique+indexes of the same name. Tenant-scoped compound indexes now enforce uniqueness.+This also affects single-tenant deployments. See #15759 (successor to #14826).++The tenant-index migration is an explicit maintenance command; startup does not+run it automatically. Use the updated code/image containing this command. For a+source checkout, install dependencies and build the packages first (`npm run+build:packages`).++1. Back up MongoDB and stop all LibreChat API replicas and workers that write to+ the database. Keep MongoDB available throughout the migration.+2. Preview known legacy unique indexes using the deployment's `MONGO_URI` and+ connection settings from `.env`:++ ```sh+ npm run migrate:tenant-indexes:dry-run+ ```++3. Apply the migration:++ ```sh+ npm run migrate:tenant-indexes+ ```++ With Docker Compose, stop the API and run a one-off container from the updated+ image while MongoDB remains running. Use the same Compose file flags as your+ deployment (for example, `docker compose -f deploy-compose.yml`). Set the+ working directory to `/app`, where the root npm scripts live; the production+ API image otherwise defaults to `/app/api`:++ ```sh+ docker compose stop api+ docker compose run --rm --no-deps -w /app api npm run migrate:tenant-indexes:dry-run+ docker compose run --rm --no-deps -w /app api npm run migrate:tenant-indexes+ docker compose up -d api+ ```++4. Restart writers only after the command exits successfully (status 0). Verify+ that startup no longer reports these index conflicts.++The command first builds tenant-scoped unique indexes, then drops only known+superseded unique indexes, and explicitly creates current schema indexes for the+affected collections. It preserves custom indexes and current non-unique indexes;+it does not delete documents or use `syncIndexes`/`dropIndexes`. Automatic index+creation is disabled in the maintenance process to prevent races, even when the+server normally enables it. Current indexes are explicitly built even if the+server uses `MONGO_AUTO_INDEX=false`.++The dry run only lists removals: it does not validate replacement builds, database+permissions, or duplicate data. Any listing, dropping, or building error makes+the apply command fail. If replacement creation fails (for example due to+existing duplicates or unsupported database index options), no old constraints+have been dropped. Keep writers stopped, correct the reported problem, and rerun.+A later failure can leave a partial migration; rerunning safely completes it.+Index builds may take time on large collections. Do not drop all indexes to+resolve a failure.diff --git a/config/migrate-tenant-indexes.js b/config/migrate-tenant-indexes.jsnew file mode 100644index 0000000000..99ccf1ff46--- /dev/null+++ b/config/migrate-tenant-indexes.js@@ -0,0 +1,21 @@+require('dotenv').config();+process.env.MONGO_AUTO_INDEX = 'false';+process.env.MONGO_AUTO_CREATE = 'false';+const mongoose = require('mongoose');+const { migrateTenantIndexes } = require('@librechat/data-schemas');+const connect = require('./connect');++(async () => {+ try {+ await connect();+ const result = await migrateTenantIndexes(mongoose.connection, {+ dryRun: process.argv.includes('--dry-run'),+ });+ process.exitCode = result.errors.length > 0 ? 1 : 0;+ } catch (error) {+ console.error('Tenant index migration failed:', error);+ process.exitCode = 1;+ } finally {+ await mongoose.disconnect();+ }+})();diff --git a/package.json b/package.jsonindex 8812b86275..a18405175d 100644--- a/package.json+++ b/package.json@@ -125,6 +125,8 @@"b:balance": "bun config/add-balance.js","b:list-balances": "bun config/list-balances.js","reset-terms": "node config/reset-terms.js",+ "migrate:tenant-indexes": "node config/migrate-tenant-indexes.js",+ "migrate:tenant-indexes:dry-run": "node config/migrate-tenant-indexes.js --dry-run","migrate:terms-timestamp": "node config/migrate-terms-timestamp.js","flush-cache": "node config/flush-cache.js","migrate:agent-permissions:dry-run": "node config/migrate-agent-permissions.js --dry-run",diff --git a/packages/data-schemas/src/index.ts b/packages/data-schemas/src/index.tsindex 798af371e8..0e9299b970 100644--- a/packages/data-schemas/src/index.ts+++ b/packages/data-schemas/src/index.ts@@ -99,6 +99,7 @@ export {MCPServerNameMigrationError,createMCPAuthorityLookupIndexes,dropSupersededTenantIndexes,+ migrateTenantIndexes,dropSupersededPromptGroupIndexes,backfillMCPServerNormalizedNames,} from './migrations';diff --git a/packages/data-schemas/src/migrations/index.ts b/packages/data-schemas/src/migrations/index.tsindex e26cb521c7..c3ba619181 100644--- a/packages/data-schemas/src/migrations/index.ts+++ b/packages/data-schemas/src/migrations/index.ts@@ -1,4 +1,4 @@-export { dropSupersededTenantIndexes } from './tenantIndexes';+export { dropSupersededTenantIndexes, migrateTenantIndexes } from './tenantIndexes';export { dropSupersededPromptGroupIndexes } from './promptGroupIndexes';export { createMCPAuthorityLookupIndexes } from './mcpAuthorityIndexes';export { MCPServerNameMigrationError, backfillMCPServerNormalizedNames } from './mcpServerNames';diff --git a/packages/data-schemas/src/migrations/tenantIndexes.spec.ts b/packages/data-schemas/src/migrations/tenantIndexes.spec.tsindex 986adb5ab8..48ed97a91a 100644--- a/packages/data-schemas/src/migrations/tenantIndexes.spec.ts+++ b/packages/data-schemas/src/migrations/tenantIndexes.spec.ts@@ -1,6 +1,10 @@import mongoose from 'mongoose';import { MongoMemoryServer } from 'mongodb-memory-server';-import { dropSupersededTenantIndexes, SUPERSEDED_INDEXES } from './tenantIndexes';+import {+ dropSupersededTenantIndexes,+ migrateTenantIndexes,+ SUPERSEDED_INDEXES,+} from './tenantIndexes';jest.mock('~/config/winston', () => ({error: jest.fn(),@@ -317,3 +321,79 @@ describe('dropSupersededTenantIndexes', () => {});});});++describe('operator migration', () => {+ let instance: mongoose.Mongoose;++ beforeEach(async () => {+ instance = new mongoose.Mongoose();+ await instance.connect(mongoServer.getUri(), {+ dbName: 'operator',+ autoIndex: false,+ autoCreate: false,+ });+ await instance.connection.dropDatabase();+ });++ afterEach(async () => {+ await instance.disconnect();+ });++ it('previews without changing indexes or creating collections', async () => {+ const roles = instance.connection.db!.collection('roles');+ await roles.createIndex({ name: 1 }, { unique: true });+ const before = await roles.indexes();+ const result = await migrateTenantIndexes(instance.connection, { dryRun: true });+ expect(result.planned).toEqual(['roles.name_1']);+ expect(result.dropped).toEqual([]);+ expect(await roles.indexes()).toEqual(before);+ expect(await instance.connection.db!.listCollections().toArray()).toHaveLength(1);+ });++ it('upgrades legacy indexes, preserves custom indexes, and can be rerun', async () => {+ const roles = instance.connection.db!.collection('roles');+ await roles.insertOne({ name: 'USER' });+ await roles.createIndex({ name: 1 }, { unique: true });+ await roles.createIndex({ custom: 1 }, { name: 'operator_custom' });+ for (const [name, indexNames] of Object.entries(SUPERSEDED_INDEXES)) {+ for (const indexName of indexNames) {+ const fields = indexName.split('_').filter((field) => field !== '1');+ const keys = Object.fromEntries(fields.map((field) => [field, 1 as const]));+ await instance.connection.db!.collection(name).createIndex(keys, { unique: true });+ }+ }+ const result = await migrateTenantIndexes(instance.connection);+ expect(result.errors).toEqual([]);+ expect(result.dropped).toHaveLength(Object.values(SUPERSEDED_INDEXES).flat().length);+ const indexes = await roles.indexes();+ expect(indexes.find((index) => index.name === 'name_1')?.unique).toBeUndefined();+ expect(indexes.find((index) => index.name === 'name_1_tenantId_1')?.unique).toBe(true);+ expect(indexes.some((index) => index.name === 'operator_custom')).toBe(true);+ await expect(roles.insertOne({ name: 'USER' })).rejects.toThrow(/E11000/);+ await roles.insertOne({ name: 'USER', tenantId: 'another-tenant' });+ const rerun = await migrateTenantIndexes(instance.connection);+ expect(rerun.errors).toEqual([]);+ expect(rerun.dropped).toEqual([]);+ expect(await roles.indexes()).toEqual(indexes);+ });++ it('retains legacy constraints when replacement creation fails', async () => {+ const users = instance.connection.db!.collection('users');+ await users.insertMany([{ email: '[email protected]' }, { email: '[email protected]' }]);+ const roles = instance.connection.db!.collection('roles');+ await roles.createIndex({ name: 1 }, { unique: true });+ await expect(migrateTenantIndexes(instance.connection)).rejects.toThrow(/E11000/);+ expect((await roles.indexes()).find((index) => index.name === 'name_1')?.unique).toBe(true);+ });++ it('reports index-listing failures instead of treating them as missing collections', async () => {+ const roles = instance.connection.db!.collection('roles');+ const collection = jest.spyOn(instance.connection.db!, 'collection');+ collection.mockReturnValue(roles);+ jest.spyOn(roles, 'indexes').mockRejectedValue(new Error('not authorized'));+ const result = await dropSupersededTenantIndexes(instance.connection);+ expect(result.errors).toHaveLength(Object.keys(SUPERSEDED_INDEXES).length);+ expect(result.skipped).toEqual([]);+ expect(result.dropped).toEqual([]);+ });+});diff --git a/packages/data-schemas/src/migrations/tenantIndexes.ts b/packages/data-schemas/src/migrations/tenantIndexes.tsindex 9a84997c5c..b68a2b32d1 100644--- a/packages/data-schemas/src/migrations/tenantIndexes.ts+++ b/packages/data-schemas/src/migrations/tenantIndexes.ts@@ -1,6 +1,37 @@+import type { IndexSpecification } from 'mongodb';import type { Connection } from 'mongoose';+import conversationTagSchema from '~/schema/conversationTag';+import skillSyncStatusSchema from '~/schema/skillSyncStatus';+import agentCategorySchema from '~/schema/agentCategory';+import { buildIndexWithRetry } from '~/utils/retry';+import accessRoleSchema from '~/schema/accessRole';+import mcpServerSchema from '~/schema/mcpServer';+import messageSchema from '~/schema/message';+import presetSchema from '~/schema/preset';+import agentSchema from '~/schema/agent';+import convoSchema from '~/schema/convo';+import groupSchema from '~/schema/group';+import userSchema from '~/schema/user';+import roleSchema from '~/schema/role';+import fileSchema from '~/schema/file';import logger from '~/config/winston';+const TENANT_SCHEMAS = {+ users: userSchema,+ roles: roleSchema,+ agents: agentSchema,+ conversations: convoSchema,+ messages: messageSchema,+ presets: presetSchema,+ agentcategories: agentCategorySchema,+ accessroles: accessRoleSchema,+ conversationtags: conversationTagSchema,+ mcpservers: mcpServerSchema,+ files: fileSchema,+ groups: groupSchema,+ skillsyncstatuses: skillSyncStatusSchema,+};+/*** Indexes that were superseded by compound tenant-scoped indexes.* Each entry maps a collection name to the old index names that must be dropped@@ -39,6 +70,7 @@ const SUPERSEDED_INDEXES: Record<string, string[]> = {};interface MigrationResult {+ planned: string[];dropped: string[];skipped: string[];errors: string[];@@ -53,23 +85,32 @@ interface MigrationResult {*/export async function dropSupersededTenantIndexes(connection: Connection,+ { dryRun = false }: { dryRun?: boolean } = {},): Promise<MigrationResult> {- const result: MigrationResult = { dropped: [], skipped: [], errors: [] };+ const result: MigrationResult = { planned: [], dropped: [], skipped: [], errors: [] };for (const [collectionName, indexNames] of Object.entries(SUPERSEDED_INDEXES)) {const collection = connection.db!.collection(collectionName);- let existingIndexes: Array<{ name?: string }>;+ let existingIndexes: Array<{ name?: string; unique?: boolean }>;try {existingIndexes = await collection.indexes();- } catch {- result.skipped.push(- ...indexNames.map((idx) => `${collectionName}.${idx} (collection does not exist)`),- );+ } catch (err) {+ if (err instanceof Error && 'code' in err && err.code === 26) {+ result.skipped.push(+ ...indexNames.map((idx) => `${collectionName}.${idx} (collection does not exist)`),+ );+ continue;+ }+ const msg = `${collectionName}: ${(err as Error).message}`;+ result.errors.push(msg);+ logger.error(`[TenantMigration] Failed to list indexes: ${msg}`);continue;}- const existingNames = new Set(existingIndexes.map((idx) => idx.name));+ const existingNames = new Set(+ existingIndexes.filter((idx) => idx.unique).map((idx) => idx.name),+ );for (const indexName of indexNames) {if (!existingNames.has(indexName)) {@@ -77,6 +118,12 @@ export async function dropSupersededTenantIndexes(continue;}+ result.planned.push(`${collectionName}.${indexName}`);+ if (dryRun) {+ logger.info(`[TenantMigration] Would drop: ${collectionName}.${indexName}`);+ continue;+ }+try {await collection.dropIndex(indexName);result.dropped.push(`${collectionName}.${indexName}`);@@ -89,18 +136,62 @@ export async function dropSupersededTenantIndexes(}}- if (result.dropped.length > 0) {- logger.info(- `[TenantMigration] Migration complete. Dropped ${result.dropped.length} superseded indexes.`,- );- } else {- logger.info(- '[TenantMigration] No superseded indexes found — database is already migrated or fresh.',- );- }+ logger.info(+ `[TenantMigration] ${dryRun ? 'Dry run' : 'Index cleanup'} complete: ` ++ `${result.planned.length} planned, ${result.dropped.length} dropped, ${result.errors.length} errors.`,+ );return result;}/** Exported for testing — the raw index map */export { SUPERSEDED_INDEXES };++/**+ * Offline upgrade: build tenant constraints before removing global constraints,+ * then explicitly create current indexes even when MONGO_AUTO_INDEX is disabled.+ * The caller must connect with autoIndex and autoCreate disabled and stop writers.+ */+export async function migrateTenantIndexes(+ connection: Connection,+ { dryRun = false }: { dryRun?: boolean } = {},+): Promise<MigrationResult> {+ if (dryRun) {+ return dropSupersededTenantIndexes(connection, { dryRun });+ }++ const indexes = Object.entries(TENANT_SCHEMAS).flatMap(([name, schema]) =>+ schema.indexes().map(([keys, options]) => ({+ collection: connection.db!.collection(name),+ tenantScoped: 'tenantId' in keys,+ keys: keys as IndexSpecification,+ options: {+ ...options,+ unique: Boolean(options.unique),+ },+ })),+ );+ logger.info('[TenantMigration] Building tenant-scoped unique indexes before cleanup.');+ for (const { collection, keys, options, tenantScoped } of indexes) {+ if (options.unique && tenantScoped) {+ await buildIndexWithRetry(+ () => collection.createIndex(keys, options),+ `createIndex(${collection.collectionName}.${JSON.stringify(keys)})`,+ );+ }+ }++ const result = await dropSupersededTenantIndexes(connection);+ if (result.errors.length > 0) {+ return result;+ }+ logger.info('[TenantMigration] Creating current schema indexes.');+ for (const { collection, keys, options } of indexes) {+ await buildIndexWithRetry(+ () => collection.createIndex(keys, options),+ `createIndex(${collection.collectionName}.${JSON.stringify(keys)})`,+ );+ }+ logger.info('[TenantMigration] Migration complete.');+ return result;+}