better-convex 0.7.2 → 0.7.3

package/dist/orm/index.js

@@ -1,5 +1,6 @@
 import { A as entityKind, C as text, D as custom, E as id, O as json, S as vectorIndex, T as integer, _ as aggregateIndex, a as deletion, b as searchIndex, c as EnableRLS, d as OrmSchemaOptions, f as RlsPolicies, g as rlsPolicy, h as RlsPolicy, i as convexTable, k as ConvexColumnBuilder, l as OrmContext, m as TableName, o as Brand, p as TableDeleteConfig, s as Columns, t as DirectAggregate, u as OrmSchemaDefinition, v as index, w as createSystemFields, x as uniqueIndex, y as rankIndex } from "../runtime-B9xQFY8W.js";
-import { A as ne, C as inArray, D as like, E as isNull, F as notLike, I as or, L as startsWith, M as notBetween, N as notIlike, O as lt, P as notInArray, S as ilike, T as isNotNull, _ as endsWith, a as mergedStream, b as gt, c as isUnsetToken, d as arrayContained, f as arrayContains, g as contains, h as column, i as getIndexFields, j as not, k as lte, l as unsetToken, m as between, n as EmptyStream, o as stream, p as arrayOverlaps, r as QueryStream, s as streamIndexRange, t as getByIdWithOrmQueryFallback, u as and, v as eq, w as isFieldReference, x as gte, y as fieldRef } from "../query-context-BDSis9rT.js";
+import { a as pretendRequired, i as pretend, n as deprecated } from "../validators-B7oIJCAp.js";
+import { A as ne, C as inArray, D as like, E as isNull, F as notLike, I as or, L as startsWith, M as notBetween, N as notIlike, O as lt, P as notInArray, S as ilike, T as isNotNull, _ as endsWith, a as mergedStream, b as gt, c as isUnsetToken, d as arrayContained, f as arrayContains, g as contains, h as column, i as getIndexFields, j as not, k as lte, l as unsetToken, m as between, n as EmptyStream, o as stream, p as arrayOverlaps, r as QueryStream, s as streamIndexRange, t as getByIdWithOrmQueryFallback, u as and, v as eq, w as isFieldReference, x as gte, y as fieldRef } from "../query-context-yQVARct0.js";
 import { v } from "convex/values";
 import { defineSchema as defineSchema$1, internalActionGeneric, internalMutationGeneric } from "convex/server";
 
@@ -379,6 +380,14 @@ const aggregateStorageTables = {
 	[AGGREGATE_RANK_NODE_TABLE]: rankNodeTable,
 	[AGGREGATE_STATE_TABLE]: countStateTable
 };
+const AGGREGATE_STORAGE_TABLE_NAMES = new Set([
+	AGGREGATE_BUCKET_TABLE,
+	AGGREGATE_MEMBER_TABLE,
+	AGGREGATE_EXTREMA_TABLE,
+	AGGREGATE_RANK_TREE_TABLE,
+	AGGREGATE_RANK_NODE_TABLE,
+	AGGREGATE_STATE_TABLE
+]);
 function injectAggregateStorageTables(schema) {
 	const merged = { ...schema };
 	for (const [tableName, tableDef] of Object.entries(aggregateStorageTables)) {
@@ -8924,6 +8933,671 @@ function isOne(relation) {
 	return relation.relationType === "one";
 }
 
+//#endregion
+//#region src/orm/migrations/definitions.ts
+const MIGRATION_ID_RE = /^[a-zA-Z0-9_:-]+$/;
+const FUNCTION_SOURCE_WHITESPACE_RE = /\s+/g;
+const FUNCTION_SOURCE_PUNCTUATION_SPACE_RE = /\s*([{}();,:])\s*/g;
+function defineMigration(migration) {
+	validateMigrationId(migration.id);
+	validateMigrationStep("up", migration.up);
+	if (migration.down) validateMigrationStep("down", migration.down);
+	return migration;
+}
+function defineMigrationSet(migrations) {
+	const normalized = [...migrations].map((migration) => {
+		const defined = defineMigration(migration);
+		return {
+			...defined,
+			checksum: defined.checksum ?? computeMigrationChecksum(defined)
+		};
+	});
+	normalized.sort((a, b) => a.id.localeCompare(b.id));
+	const byId = {};
+	for (const migration of normalized) {
+		if (byId[migration.id]) throw new Error(`defineMigrationSet received duplicate migration id '${migration.id}'.`);
+		byId[migration.id] = migration;
+	}
+	return {
+		migrations: normalized,
+		ids: normalized.map((migration) => migration.id),
+		byId
+	};
+}
+function detectMigrationDrift(params) {
+	const { migrationSet, appliedState } = params;
+	const issues = [];
+	for (const [migrationId, state] of Object.entries(appliedState)) {
+		if (!state.applied) continue;
+		const migration = migrationSet.byId[migrationId];
+		if (!migration) {
+			issues.push({
+				kind: "missing_from_manifest",
+				migrationId,
+				message: `Applied migration '${migrationId}' is missing from the current migration manifest.`
+			});
+			continue;
+		}
+		if (state.checksum && state.checksum !== migration.checksum) issues.push({
+			kind: "checksum_mismatch",
+			migrationId,
+			expectedChecksum: migration.checksum,
+			actualChecksum: state.checksum,
+			message: `Applied migration '${migrationId}' checksum drift detected.`
+		});
+	}
+	return issues;
+}
+function buildMigrationPlan(params) {
+	const { direction, migrationSet, appliedState, steps, to } = params;
+	if (direction === "up") return {
+		direction,
+		migrations: migrationSet.migrations.filter((migration) => !appliedState[migration.id]?.applied)
+	};
+	if (steps !== void 0 && to !== void 0) throw new Error("Use either down steps or down to, not both.");
+	const appliedInOrder = migrationSet.migrations.filter((migration) => appliedState[migration.id]?.applied);
+	const ensureDownSteps = (selected) => {
+		const missingDown = selected.find((migration) => !migration.down);
+		if (missingDown) throw new Error(`Cannot execute down migration for '${missingDown.id}': missing down migration handler.`);
+		return selected;
+	};
+	if (to) {
+		const targetIndex = migrationSet.ids.indexOf(to);
+		if (targetIndex === -1) throw new Error(`Unknown migration id '${to}' for down --to.`);
+		return {
+			direction,
+			migrations: ensureDownSteps(appliedInOrder.filter((migration) => {
+				return migrationSet.ids.indexOf(migration.id) > targetIndex;
+			})).reverse()
+		};
+	}
+	const resolvedSteps = steps ?? 1;
+	if (!Number.isInteger(resolvedSteps) || resolvedSteps < 1) throw new Error("Down steps must be a positive integer.");
+	return {
+		direction,
+		migrations: ensureDownSteps(appliedInOrder.slice(-resolvedSteps).reverse())
+	};
+}
+function validateMigrationId(id) {
+	if (!id || typeof id !== "string") throw new Error("Migration id must be a non-empty string.");
+	if (!MIGRATION_ID_RE.test(id)) throw new Error(`Migration id '${id}' is invalid. Use alphanumeric characters, '_' ':' or '-'.`);
+}
+function validateMigrationStep(direction, step) {
+	if (!step || typeof step !== "object") throw new Error(`Migration ${direction} step must be an object.`);
+	if (!step.table || typeof step.table !== "string") throw new Error(`Migration ${direction} step.table must be a string.`);
+	if (typeof step.migrateOne !== "function") throw new Error(`Migration ${direction} step.migrateOne must be a function.`);
+	if (step.batchSize !== void 0 && (!Number.isInteger(step.batchSize) || step.batchSize < 1)) throw new Error(`Migration ${direction} step.batchSize must be a positive integer.`);
+	if (step.writeMode !== void 0 && step.writeMode !== "safe_bypass" && step.writeMode !== "normal") throw new Error(`Migration ${direction} step.writeMode must be 'safe_bypass' or 'normal'.`);
+}
+function computeMigrationChecksum(migration) {
+	return simpleStableHash(JSON.stringify({
+		id: migration.id,
+		name: migration.name ?? null,
+		description: migration.description ?? null,
+		up: serializeStep(migration.up),
+		down: migration.down ? serializeStep(migration.down) : null
+	}));
+}
+function serializeStep(step) {
+	return {
+		table: step.table,
+		batchSize: step.batchSize ?? null,
+		writeMode: step.writeMode ?? "safe_bypass",
+		source: normalizeFunctionSource(step.migrateOne)
+	};
+}
+function normalizeFunctionSource(fn) {
+	return fn.toString().replace(FUNCTION_SOURCE_WHITESPACE_RE, " ").replace(FUNCTION_SOURCE_PUNCTUATION_SPACE_RE, "$1").trim();
+}
+function simpleStableHash(value) {
+	let hashA = 2166136261;
+	let hashB = 16777619;
+	for (let i = 0; i < value.length; i += 1) {
+		const code = value.charCodeAt(i);
+		hashA ^= code;
+		hashA = Math.imul(hashA, 16777619);
+		hashB ^= code + i;
+		hashB = Math.imul(hashB, 2246822507);
+	}
+	return `m_${(hashA >>> 0).toString(16).padStart(8, "0")}${(hashB >>> 0).toString(16).padStart(8, "0")}`;
+}
+
+//#endregion
+//#region src/orm/migrations/schema.ts
+const MIGRATION_STATE_TABLE = "migration_state";
+const MIGRATION_RUN_TABLE = "migration_run";
+const migrationStateTable = convexTable(MIGRATION_STATE_TABLE, {
+	migrationId: text().notNull(),
+	checksum: text().notNull(),
+	applied: boolean().notNull(),
+	status: text().notNull(),
+	direction: text(),
+	runId: text(),
+	cursor: text(),
+	processed: integer().notNull(),
+	startedAt: integer(),
+	updatedAt: integer().notNull(),
+	completedAt: integer(),
+	lastError: text(),
+	writeMode: text().notNull()
+}, (t) => [index("by_migration_id").on(t.migrationId), index("by_status").on(t.status)]);
+const migrationRunTable = convexTable(MIGRATION_RUN_TABLE, {
+	runId: text().notNull(),
+	direction: text().notNull(),
+	status: text().notNull(),
+	dryRun: boolean().notNull(),
+	allowDrift: boolean().notNull(),
+	migrationIds: custom(v.array(v.string())).notNull(),
+	currentIndex: integer().notNull(),
+	startedAt: integer().notNull(),
+	updatedAt: integer().notNull(),
+	completedAt: integer(),
+	cancelRequested: boolean().notNull(),
+	lastError: text()
+}, (t) => [index("by_run_id").on(t.runId), index("by_status").on(t.status)]);
+const migrationStorageTables = {
+	[MIGRATION_STATE_TABLE]: migrationStateTable,
+	[MIGRATION_RUN_TABLE]: migrationRunTable
+};
+const MIGRATION_STORAGE_TABLE_NAMES = new Set([MIGRATION_STATE_TABLE, MIGRATION_RUN_TABLE]);
+function injectMigrationStorageTables(schema) {
+	const merged = { ...schema };
+	for (const [tableName, tableDef] of Object.entries(migrationStorageTables)) {
+		if (tableName in schema && schema[tableName] !== tableDef) throw new Error(`defineSchema cannot inject internal table '${tableName}' because the name is already in use.`);
+		merged[tableName] = tableDef;
+	}
+	return merged;
+}
+
+//#endregion
+//#region src/orm/migrations/runtime.ts
+const DEFAULT_BATCH_SIZE = 128;
+function createMigrationHandlers(params) {
+	const { schema, migrations, getOrm, getChunkRef } = params;
+	const knownTables = new Set(Object.values(schema).map((tableConfig) => tableConfig.name));
+	const run = async (ctx, args = {}) => {
+		if (!migrations || migrations.migrations.length === 0) return {
+			status: "noop",
+			reason: "no_migrations_registered"
+		};
+		const direction = parseDirection(args.direction);
+		const dryRun = args.dryRun === true;
+		const allowDrift = args.allowDrift === true;
+		const restart = args.restart === true;
+		const batchSize = parseOptionalPositiveInteger(args.batchSize, "batchSize");
+		const steps = parseOptionalPositiveInteger(args.steps, "steps");
+		const to = parseOptionalString(args.to, "to");
+		const stateRows = await getAllStateRows(ctx.db);
+		const appliedState = toAppliedStateMap(stateRows);
+		const drift = detectMigrationDrift({
+			migrationSet: migrations,
+			appliedState
+		});
+		if (drift.length > 0 && !allowDrift) return {
+			status: "drift_blocked",
+			direction,
+			drift
+		};
+		const plan = buildMigrationPlan({
+			direction,
+			migrationSet: migrations,
+			appliedState,
+			steps,
+			to
+		});
+		if (plan.migrations.length === 0) return {
+			status: "noop",
+			direction,
+			drift,
+			plan: []
+		};
+		for (const migration of plan.migrations) {
+			const step = getStepForDirection(migration, direction);
+			if (!knownTables.has(step.table)) throw new Error(`Migration '${migration.id}' references unknown table '${step.table}'.`);
+		}
+		if (dryRun) return {
+			status: "dry_run",
+			direction,
+			drift,
+			plan: plan.migrations.map((migration) => migration.id)
+		};
+		const activeRun = await getActiveRun(ctx.db);
+		if (activeRun) return {
+			status: "running",
+			runId: activeRun.runId
+		};
+		const now = Date.now();
+		const runId = createRunId(now);
+		await ctx.db.insert(MIGRATION_RUN_TABLE, {
+			runId,
+			direction,
+			status: "running",
+			dryRun: false,
+			allowDrift,
+			migrationIds: plan.migrations.map((migration) => migration.id),
+			currentIndex: 0,
+			startedAt: now,
+			updatedAt: now,
+			cancelRequested: false
+		});
+		const stateById = new Map(stateRows.map((row) => [row.migrationId, row]));
+		for (const migration of plan.migrations) {
+			const writeMode = getStepForDirection(migration, direction).writeMode ?? "safe_bypass";
+			const existing = stateById.get(migration.id);
+			const resetProgress = restart || existing?.direction !== direction;
+			if (existing) await ctx.db.patch(existing._id, cleanUndefined({
+				checksum: migration.checksum,
+				status: "pending",
+				direction,
+				runId,
+				cursor: resetProgress ? null : existing.cursor ?? null,
+				processed: resetProgress ? 0 : existing.processed ?? 0,
+				startedAt: now,
+				updatedAt: now,
+				completedAt: null,
+				lastError: null,
+				writeMode
+			}));
+			else await ctx.db.insert(MIGRATION_STATE_TABLE, {
+				migrationId: migration.id,
+				checksum: migration.checksum,
+				applied: direction === "down",
+				status: "pending",
+				direction,
+				runId,
+				cursor: null,
+				processed: 0,
+				startedAt: now,
+				updatedAt: now,
+				completedAt: null,
+				lastError: null,
+				writeMode
+			});
+		}
+		if (ctx.scheduler) {
+			const chunkRef = getChunkRef();
+			if (chunkRef) {
+				const chunkArgs = { runId };
+				if (batchSize !== void 0) chunkArgs.batchSize = batchSize;
+				await ctx.scheduler.runAfter(0, chunkRef, chunkArgs);
+				return {
+					status: "running",
+					direction,
+					runId,
+					plan: plan.migrations.map((migration) => migration.id)
+				};
+			}
+		}
+		const inlineResult = await chunk(ctx, {
+			runId,
+			batchSize
+		});
+		return {
+			status: "running",
+			direction,
+			runId,
+			plan: plan.migrations.map((migration) => migration.id),
+			inlineResult
+		};
+	};
+	const chunk = async (ctx, args) => {
+		const runId = parseRequiredString(args.runId, "runId");
+		const batchSize = parseOptionalPositiveInteger(args.batchSize, "batchSize");
+		const runRow = await getRunById(ctx.db, runId);
+		if (!runRow) return {
+			status: "missing",
+			runId
+		};
+		if (runRow.status !== "running") return {
+			status: runRow.status,
+			runId
+		};
+		if (runRow.cancelRequested) {
+			await markRunCanceled(ctx.db, runRow);
+			return {
+				status: "canceled",
+				runId
+			};
+		}
+		const migrationId = runRow.migrationIds[runRow.currentIndex];
+		if (!migrationId) {
+			await markRunCompleted(ctx.db, runRow);
+			return {
+				status: "completed",
+				runId
+			};
+		}
+		const migration = migrations?.byId[migrationId];
+		if (!migration) {
+			await markRunFailed(ctx.db, runRow, `Migration '${migrationId}' is missing from registry.`);
+			return {
+				status: "failed",
+				runId
+			};
+		}
+		const direction = parseDirection(runRow.direction);
+		const step = getStepForDirection(migration, direction);
+		const resolvedBatchSize = batchSize ?? step.batchSize ?? DEFAULT_BATCH_SIZE;
+		const stateRow = await getOrCreateStateRow(ctx.db, migration, direction, step);
+		const cursor = stateRow.cursor ?? null;
+		try {
+			const page = await ctx.db.query(step.table).paginate({
+				cursor,
+				numItems: resolvedBatchSize
+			});
+			const docs = Array.isArray(page?.page) ? page.page : [];
+			const orm = getOrm(ctx);
+			const writeMode = step.writeMode ?? "safe_bypass";
+			let processedInBatch = 0;
+			for (const doc of docs) {
+				const migrationCtxBase = {
+					db: ctx.db,
+					migrationId,
+					runId,
+					direction,
+					dryRun: false,
+					writeMode
+				};
+				const result = await runWithWriteMode(orm, writeMode, (resolvedOrm) => step.migrateOne({
+					...migrationCtxBase,
+					orm: resolvedOrm
+				}, doc));
+				if (isPatchPayload(result) && hasDocId(doc)) await ctx.db.patch(doc._id, result);
+				processedInBatch += 1;
+			}
+			const now = Date.now();
+			const isDone = Boolean(page?.isDone);
+			const nextCursor = isDone ? null : page?.continueCursor ?? null;
+			const nextProcessed = (stateRow.processed ?? 0) + processedInBatch;
+			if (isDone) {
+				await ctx.db.patch(stateRow._id, cleanUndefined({
+					status: "completed",
+					applied: direction === "up",
+					cursor: null,
+					processed: nextProcessed,
+					completedAt: now,
+					updatedAt: now,
+					lastError: null,
+					runId,
+					direction,
+					writeMode
+				}));
+				const nextIndex = runRow.currentIndex + 1;
+				const done = nextIndex >= runRow.migrationIds.length;
+				await ctx.db.patch(runRow._id, cleanUndefined({
+					currentIndex: nextIndex,
+					status: done ? "completed" : "running",
+					updatedAt: now,
+					completedAt: done ? now : null,
+					lastError: null
+				}));
+				if (!done && ctx.scheduler) {
+					const chunkRef = getChunkRef();
+					if (chunkRef) await ctx.scheduler.runAfter(0, chunkRef, {
+						runId,
+						batchSize: resolvedBatchSize
+					});
+				}
+				return {
+					status: done ? "completed" : "running",
+					runId,
+					migrationId,
+					processedInBatch,
+					processed: nextProcessed,
+					currentIndex: nextIndex,
+					total: runRow.migrationIds.length
+				};
+			}
+			await ctx.db.patch(stateRow._id, cleanUndefined({
+				status: "running",
+				cursor: nextCursor,
+				processed: nextProcessed,
+				updatedAt: now,
+				runId,
+				direction,
+				writeMode
+			}));
+			await ctx.db.patch(runRow._id, cleanUndefined({
+				status: "running",
+				updatedAt: now
+			}));
+			if (ctx.scheduler) {
+				const chunkRef = getChunkRef();
+				if (chunkRef) await ctx.scheduler.runAfter(0, chunkRef, {
+					runId,
+					batchSize: resolvedBatchSize
+				});
+			}
+			return {
+				status: "running",
+				runId,
+				migrationId,
+				processedInBatch,
+				processed: nextProcessed,
+				cursor: nextCursor
+			};
+		} catch (error) {
+			const message = error.message || String(error);
+			await ctx.db.patch(stateRow._id, cleanUndefined({
+				status: "failed",
+				lastError: message,
+				updatedAt: Date.now()
+			}));
+			await markRunFailed(ctx.db, runRow, message);
+			return {
+				status: "failed",
+				runId,
+				migrationId,
+				error: message
+			};
+		}
+	};
+	const status = async (ctx, args = {}) => {
+		if (!migrations) return {
+			status: "noop",
+			reason: "no_migrations_registered"
+		};
+		const limit = parseOptionalPositiveInteger(args.limit, "limit") ?? 25;
+		const runId = parseOptionalString(args.runId, "runId");
+		const stateRows = await getAllStateRows(ctx.db);
+		const sortedRuns = [...await getAllRunRows(ctx.db)].sort((left, right) => right.startedAt - left.startedAt);
+		const selectedRuns = runId ? sortedRuns.filter((entry) => entry.runId === runId).slice(0, 1) : sortedRuns.slice(0, limit);
+		const activeRun = sortedRuns.find((entry) => entry.status === "running") ?? null;
+		const appliedState = toAppliedStateMap(stateRows);
+		const drift = detectMigrationDrift({
+			migrationSet: migrations,
+			appliedState
+		});
+		const pendingUp = buildMigrationPlan({
+			direction: "up",
+			migrationSet: migrations,
+			appliedState
+		});
+		return {
+			status: activeRun ? "running" : "idle",
+			activeRun,
+			runs: selectedRuns,
+			migrations: stateRows.map((row) => ({
+				migrationId: row.migrationId,
+				checksum: row.checksum,
+				applied: row.applied,
+				status: row.status,
+				direction: row.direction ?? null,
+				runId: row.runId ?? null,
+				cursor: row.cursor ?? null,
+				processed: row.processed,
+				updatedAt: row.updatedAt,
+				startedAt: row.startedAt ?? null,
+				completedAt: row.completedAt ?? null,
+				lastError: row.lastError ?? null,
+				writeMode: row.writeMode
+			})),
+			pending: pendingUp.migrations.map((migration) => migration.id),
+			drift
+		};
+	};
+	const cancel = async (ctx, args = {}) => {
+		if (!migrations) return {
+			status: "noop",
+			reason: "no_migrations_registered"
+		};
+		const runId = parseOptionalString(args.runId, "runId");
+		const runRow = runId ? await getRunById(ctx.db, runId) : await getActiveRun(ctx.db);
+		if (!runRow) return {
+			status: "noop",
+			reason: "no_active_run"
+		};
+		if (runRow.status !== "running") return {
+			status: "noop",
+			reason: "run_not_running",
+			runId: runRow.runId,
+			runStatus: runRow.status
+		};
+		const now = Date.now();
+		await ctx.db.patch(runRow._id, cleanUndefined({
+			cancelRequested: true,
+			updatedAt: now
+		}));
+		if (!(ctx.scheduler ? getChunkRef() : void 0)) {
+			await markRunCanceled(ctx.db, runRow);
+			return {
+				status: "canceled",
+				runId: runRow.runId
+			};
+		}
+		return {
+			status: "cancel_requested",
+			runId: runRow.runId
+		};
+	};
+	return {
+		run,
+		chunk,
+		status,
+		cancel
+	};
+}
+function getStepForDirection(migration, direction) {
+	if (direction === "up") return migration.up;
+	if (!migration.down) throw new Error(`Migration '${migration.id}' is missing down migration.`);
+	return migration.down;
+}
+function createRunId(now) {
+	return `mr_${now}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function parseDirection(value) {
+	if (value === void 0 || value === null) return "up";
+	if (value === "up" || value === "down") return value;
+	throw new Error("Migration direction must be either 'up' or 'down'.");
+}
+function parseOptionalPositiveInteger(value, fieldName) {
+	if (value === void 0 || value === null) return;
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 1) throw new Error(`Migration ${fieldName} must be a positive integer.`);
+	return value;
+}
+function parseOptionalString(value, fieldName) {
+	if (value === void 0 || value === null) return;
+	if (typeof value !== "string" || value.length === 0) throw new Error(`Migration ${fieldName} must be a non-empty string.`);
+	return value;
+}
+function parseRequiredString(value, fieldName) {
+	const parsed = parseOptionalString(value, fieldName);
+	if (!parsed) throw new Error(`Migration ${fieldName} is required.`);
+	return parsed;
+}
+function toAppliedStateMap(stateRows) {
+	const entries = {};
+	for (const row of stateRows) entries[row.migrationId] = {
+		applied: row.applied,
+		checksum: row.checksum,
+		cursor: row.cursor ?? null,
+		processed: row.processed
+	};
+	return entries;
+}
+async function getAllStateRows(db) {
+	return await db.query(MIGRATION_STATE_TABLE).collect();
+}
+async function getAllRunRows(db) {
+	return await db.query(MIGRATION_RUN_TABLE).collect();
+}
+async function getRunById(db, runId) {
+	return await db.query(MIGRATION_RUN_TABLE).withIndex("by_run_id", (query) => query.eq("runId", runId)).first() ?? null;
+}
+async function getActiveRun(db) {
+	return await db.query(MIGRATION_RUN_TABLE).withIndex("by_status", (query) => query.eq("status", "running")).first() ?? null;
+}
+async function getOrCreateStateRow(db, migration, direction, step) {
+	const existing = await db.query(MIGRATION_STATE_TABLE).withIndex("by_migration_id", (query) => query.eq("migrationId", migration.id)).first();
+	if (existing) return existing;
+	const now = Date.now();
+	const stateId = await db.insert(MIGRATION_STATE_TABLE, {
+		migrationId: migration.id,
+		checksum: migration.checksum,
+		applied: direction === "down",
+		status: "pending",
+		direction,
+		runId: null,
+		cursor: null,
+		processed: 0,
+		startedAt: now,
+		updatedAt: now,
+		completedAt: null,
+		lastError: null,
+		writeMode: step.writeMode ?? "safe_bypass"
+	});
+	const created = await db.get(stateId);
+	if (!created) throw new Error(`Failed to create migration state row for '${migration.id}'.`);
+	return created;
+}
+async function markRunCompleted(db, runRow) {
+	const now = Date.now();
+	await db.patch(runRow._id, cleanUndefined({
+		status: "completed",
+		updatedAt: now,
+		completedAt: now,
+		cancelRequested: false,
+		lastError: null
+	}));
+}
+async function markRunCanceled(db, runRow) {
+	const now = Date.now();
+	await db.patch(runRow._id, cleanUndefined({
+		status: "canceled",
+		updatedAt: now,
+		completedAt: now,
+		cancelRequested: true
+	}));
+	for (const stateRow of await getAllStateRows(db)) if (stateRow.runId === runRow.runId && (stateRow.status === "running" || stateRow.status === "pending")) await db.patch(stateRow._id, cleanUndefined({
+		status: "canceled",
+		updatedAt: now
+	}));
+}
+async function markRunFailed(db, runRow, message) {
+	const now = Date.now();
+	await db.patch(runRow._id, cleanUndefined({
+		status: "failed",
+		updatedAt: now,
+		completedAt: now,
+		lastError: message
+	}));
+}
+async function runWithWriteMode(orm, writeMode, callback) {
+	if (writeMode === "normal") return await callback(orm);
+	return await orm.skipRules.withoutTriggers(async (noTriggersOrm) => {
+		return await callback(noTriggersOrm);
+	});
+}
+function isPatchPayload(value) {
+	return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function hasDocId(doc) {
+	return "_id" in doc && doc._id !== void 0 && doc._id !== null;
+}
+function cleanUndefined(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, candidate]) => candidate !== void 0));
+}
+
 //#endregion
 //#region src/orm/scheduled-delete.ts
 function scheduledDeleteFactory(schema, edgeMetadata, scheduledMutationBatch) {
@@ -9093,6 +9767,10 @@ function scheduledMutationBatchFactory(schema, edgeMetadata, scheduledMutationBa
 
 //#endregion
 //#region src/orm/create-orm.ts
+const RESET_INTERNAL_TABLE_NAMES = [...AGGREGATE_STORAGE_TABLE_NAMES, ...MIGRATION_STORAGE_TABLE_NAMES];
+function getResetTableNames(schema) {
+	return [...new Set([...Object.values(schema).map((tableConfig) => tableConfig.name), ...RESET_INTERNAL_TABLE_NAMES])];
+}
 function isOrmCtx(source) {
 	return !!source && typeof source === "object" && "db" in source;
 }
@@ -9143,13 +9821,25 @@ function createOrm(config) {
 		with: withContext,
 		api: () => {
 			let aggregateBackfillChunkRef = config.ormFunctions.aggregateBackfillChunk;
+			let migrationRunChunkRef = config.ormFunctions.migrationRunChunk;
 			let resetChunkRef = config.ormFunctions.resetChunk;
 			const countBackfillHandlers = createCountBackfillHandlers(config.schema, () => aggregateBackfillChunkRef);
+			const migrationHandlers = createMigrationHandlers({
+				schema: config.schema,
+				migrations: config.migrations,
+				getOrm: (ctx) => db(ctx),
+				getChunkRef: () => migrationRunChunkRef
+			});
 			const aggregateBackfillChunk = mutationBuilder({
 				args: v.any(),
 				handler: countBackfillHandlers.chunk
 			});
 			if (!aggregateBackfillChunkRef) aggregateBackfillChunkRef = aggregateBackfillChunk;
+			const migrationRunChunk = mutationBuilder({
+				args: v.any(),
+				handler: migrationHandlers.chunk
+			});
+			if (!migrationRunChunkRef) migrationRunChunkRef = migrationRunChunk;
 			const resetChunk = mutationBuilder({
 				args: v.object({
 					tableName: v.string(),
@@ -9193,11 +9883,24 @@ function createOrm(config) {
 					args: v.any(),
 					handler: countBackfillHandlers.status
 				}),
+				migrationRun: mutationBuilder({
+					args: v.any(),
+					handler: migrationHandlers.run
+				}),
+				migrationRunChunk,
+				migrationStatus: mutationBuilder({
+					args: v.any(),
+					handler: migrationHandlers.status
+				}),
+				migrationCancel: mutationBuilder({
+					args: v.any(),
+					handler: migrationHandlers.cancel
+				}),
 				resetChunk,
 				reset: internalActionGeneric({
 					args: v.any(),
 					handler: async (ctx) => {
-						const tableNames = [...new Set(Object.values(config.schema).map((tableConfig) => tableConfig.name))];
+						const tableNames = getResetTableNames(config.schema);
 						let deleted = 0;
 						for (const tableName of tableNames) {
 							let cursor = null;
@@ -9589,7 +10292,7 @@ const normalizeDefaults = (defaults) => {
 function defineSchema(schema, options) {
 	const strict = options?.strict ?? true;
 	const defaults = normalizeDefaults(options?.defaults);
-	const schemaWithInternals = injectAggregateStorageTables(schema);
+	const schemaWithInternals = injectMigrationStorageTables(injectAggregateStorageTables(schema));
 	Object.defineProperty(schema, OrmSchemaOptions, {
 		value: {
 			strict,
@@ -9629,4 +10332,4 @@ function defineSchema(schema, options) {
 }
 
 //#endregion
-export { Brand, Columns, OrmNotFoundError, RlsPolicy, RlsRole, TableName, aggregateIndex, and, asc, between, bigint, boolean, bytes, check, contains, convexTable, createOrm, custom, date, defineRelations, defineRelationsPart, defineSchema, defineTriggers, deletion, desc, endsWith, eq, extractRelationsConfig, fieldRef, foreignKey, getByIdWithOrmQueryFallback, getTableColumns, getTableConfig, gt, gte, id, ilike, inArray, index, integer, isFieldReference, isNotNull, isNull, json, like, lt, lte, ne, not, notBetween, notInArray, or, rankIndex, rlsPolicy, rlsRole, scheduledDeleteFactory, scheduledMutationBatchFactory, searchIndex, startsWith, text, textEnum, timestamp, unique, uniqueIndex, unsetToken, vector, vectorIndex };
+export { Brand, Columns, OrmNotFoundError, RlsPolicy, RlsRole, TableName, aggregateIndex, and, asc, between, bigint, boolean, buildMigrationPlan, bytes, check, contains, convexTable, createOrm, custom, date, defineMigration, defineMigrationSet, defineRelations, defineRelationsPart, defineSchema, defineTriggers, deletion, deprecated, desc, detectMigrationDrift, endsWith, eq, extractRelationsConfig, fieldRef, foreignKey, getByIdWithOrmQueryFallback, getTableColumns, getTableConfig, gt, gte, id, ilike, inArray, index, integer, isFieldReference, isNotNull, isNull, json, like, lt, lte, ne, not, notBetween, notInArray, or, pretend, pretendRequired, rankIndex, rlsPolicy, rlsRole, scheduledDeleteFactory, scheduledMutationBatchFactory, searchIndex, startsWith, text, textEnum, timestamp, unique, uniqueIndex, unsetToken, vector, vectorIndex };