@contember/schema-migrations 2.1.0-beta.2 → 2.2.0-alpha.1

package/src/modifications/differs/UpdateViewDiffer.ts

@@ -0,0 +1,58 @@
+import { Differ } from '../ModificationHandler.js'
+import { Model, Schema } from '@contember/schema'
+import deepEqual from 'fast-deep-equal'
+import { Migration } from '../../Migration.js'
+import { isReplaceableViewChange } from '../utils/viewDependencies.js'
+import { updateViewModification } from '../entities/UpdateViewModification.js'
+
+/**
+ * Update a view in-place via `CREATE OR REPLACE VIEW` when only its definition
+ * (sql/dependencies/idSource) changed and its output columns stayed the same.
+ *
+ * This avoids dropping & recreating the whole dependant-view cascade (and the
+ * associated ACL / inverse-relation churn) that {@link RemoveViewDiffer} would
+ * otherwise produce. Views that had to be recreated structurally are already
+ * up to date in the running schema by the time this differ runs, so they are
+ * naturally skipped here.
+ */
+export class UpdateViewDiffer implements Differ {
+	createDiff(originalSchema: Schema, updatedSchema: Schema) {
+		const candidates = Object.values(updatedSchema.model.entities).filter(updated => {
+			const original = originalSchema.model.entities[updated.name]
+			if (!original?.view || !updated.view) {
+				return false
+			}
+			if (deepEqual(original.view, updated.view)) {
+				return false // view unchanged
+			}
+			return isReplaceableViewChange(original, updated)
+		})
+
+		// emit dependencies before dependants so a (future) appended column is available to dependants
+		const candidateNames = new Set(candidates.map(it => it.name))
+		const visited = new Set<string>()
+		const ordered: Model.Entity[] = []
+		const visit = (entity: Model.Entity) => {
+			if (visited.has(entity.name)) {
+				return
+			}
+			visited.add(entity.name)
+			for (const dependency of entity.view?.dependencies ?? []) {
+				if (candidateNames.has(dependency)) {
+					visit(updatedSchema.model.entities[dependency])
+				}
+			}
+			ordered.push(entity)
+		}
+		for (const candidate of candidates) {
+			visit(candidate)
+		}
+
+		return ordered.map((entity): Migration.Modification =>
+			updateViewModification.createModification({
+				entityName: entity.name,
+				view: entity.view!,
+			})
+		)
+	}
+}

package/src/modifications/differs/index.ts

@@ -1,2 +1,3 @@
-export * from './RemoveChangedFieldDiffer'
-export * from './RemoveViewDiffer'
+export * from './RemoveChangedFieldDiffer.js'
+export * from './RemoveViewDiffer.js'
+export * from './UpdateViewDiffer.js'

package/src/modifications/entities/CreateEntityModification.ts

@@ -1,17 +1,17 @@
 import { MigrationBuilder } from '@contember/database-migrations'
 import { Model, Schema } from '@contember/schema'
-import { SchemaUpdater, updateModel } from '../utils/schemaUpdateUtils'
+import { SchemaUpdater, updateModel } from '../utils/schemaUpdateUtils.js'
 import {
 	createModificationType,
 	Differ,
 	ModificationHandler,
 	ModificationHandlerCreateSqlOptions,
 	ModificationHandlerOptions,
-} from '../ModificationHandler'
-import { createEventTrigger, createEventTrxTrigger } from '../utils/sqlUpdateUtils'
+} from '../ModificationHandler.js'
+import { createEventTrigger, createEventTrxTrigger } from '../utils/sqlUpdateUtils.js'
 import { PossibleEntityShapeInMigrations } from '../../utils/PartialEntity.js'
-import { getColumnSqlType } from '../utils/columnUtils'
-import { VERSION_CORRECT_PRIMARY_COLUMN_NAME } from '../ModificationVersions'
+import { getColumnSqlType } from '../utils/columnUtils.js'
+import { VERSION_CORRECT_PRIMARY_COLUMN_NAME } from '../ModificationVersions.js'
 
 export class CreateEntityModificationHandler implements ModificationHandler<CreateEntityModificationData> {
 	constructor(

package/src/modifications/entities/CreateViewModification.ts

@@ -1,8 +1,8 @@
 import { MigrationBuilder } from '@contember/database-migrations'
 import { Model, Schema } from '@contember/schema'
-import { SchemaUpdater, updateModel } from '../utils/schemaUpdateUtils'
-import { createModificationType, Differ, ModificationHandler } from '../ModificationHandler'
-import { Migration } from '../../Migration'
+import { SchemaUpdater, updateModel } from '../utils/schemaUpdateUtils.js'
+import { createModificationType, Differ, ModificationHandler } from '../ModificationHandler.js'
+import { Migration } from '../../Migration.js'
 import { PossibleEntityShapeInMigrations } from '../../utils/PartialEntity.js'
 
 export class CreateViewModificationHandler implements ModificationHandler<CreateViewModificationData> {

package/src/modifications/entities/RemoveEntityModification.ts

@@ -10,17 +10,17 @@ import {
 	updateAclEveryRole,
 	updateModel,
 	updateSchema,
-} from '../utils/schemaUpdateUtils'
+} from '../utils/schemaUpdateUtils.js'
 import {
 	createModificationType,
 	Differ,
 	ModificationHandler,
 	ModificationHandlerCreateSqlOptions,
 	ModificationHandlerOptions,
-} from '../ModificationHandler'
-import { VERSION_ACL_PATCH, VERSION_REMOVE_REFERENCING_RELATIONS } from '../ModificationVersions'
+} from '../ModificationHandler.js'
+import { VERSION_ACL_PATCH, VERSION_REMOVE_REFERENCING_RELATIONS } from '../ModificationVersions.js'
 import { acceptEveryFieldVisitor, isInverseRelation, isRelation, PredicateDefinitionProcessor } from '@contember/schema-utils'
-import { removeFieldModification } from '../fields'
+import { removeFieldModification } from '../fields/index.js'
 
 export class RemoveEntityModificationHandler implements ModificationHandler<RemoveEntityModificationData> {
 	constructor(

package/src/modifications/entities/ToggleEventLogModification.ts

@@ -1,14 +1,14 @@
 import { MigrationBuilder } from '@contember/database-migrations'
 import { Schema } from '@contember/schema'
-import { SchemaUpdater, updateEntity, updateModel } from '../utils/schemaUpdateUtils'
+import { SchemaUpdater, updateEntity, updateModel } from '../utils/schemaUpdateUtils.js'
 import {
 	createModificationType,
 	Differ,
 	ModificationHandler,
 	ModificationHandlerCreateSqlOptions,
 	ModificationHandlerOptions,
-} from '../ModificationHandler'
-import { createEventTrigger, createEventTrxTrigger, dropEventTrigger, dropEventTrxTrigger } from '../utils/sqlUpdateUtils'
+} from '../ModificationHandler.js'
+import { createEventTrigger, createEventTrxTrigger, dropEventTrigger, dropEventTrxTrigger } from '../utils/sqlUpdateUtils.js'
 
 export class ToggleEventLogModificationHandler implements ModificationHandler<ToggleEventLogModificationData> {
 	constructor(

package/src/modifications/entities/UpdateEntityNameModification.ts

@@ -9,13 +9,18 @@ import {
 	updateEveryField,
 	updateModel,
 	updateSchema,
-} from '../utils/schemaUpdateUtils'
-import { createModificationType, ModificationHandler, ModificationHandlerCreateSqlOptions, ModificationHandlerOptions } from '../ModificationHandler'
-import { isIt } from '../../utils/isIt'
-import { VERSION_ACL_PATCH } from '../ModificationVersions'
-import { NoopModification } from '../NoopModification'
-import { changeValue } from '../utils/valueUtils'
-import { updateEntityTableNameModification } from './UpdateEntityTableNameModification'
+} from '../utils/schemaUpdateUtils.js'
+import {
+	createModificationType,
+	ModificationHandler,
+	ModificationHandlerCreateSqlOptions,
+	ModificationHandlerOptions,
+} from '../ModificationHandler.js'
+import { isIt } from '../../utils/isIt.js'
+import { VERSION_ACL_PATCH } from '../ModificationVersions.js'
+import { NoopModification } from '../NoopModification.js'
+import { changeValue } from '../utils/valueUtils.js'
+import { updateEntityTableNameModification } from './UpdateEntityTableNameModification.js'
 
 export class UpdateEntityNameModificationHandler implements ModificationHandler<UpdateEntityNameModificationData> {
 	private subModification: ModificationHandler<any>

package/src/modifications/entities/UpdateEntityOrderByModification.ts

@@ -1,7 +1,7 @@
 import { MigrationBuilder } from '@contember/database-migrations'
 import { Model, Schema } from '@contember/schema'
-import { SchemaUpdater, updateEntity, updateModel } from '../utils/schemaUpdateUtils'
-import { createModificationType, Differ, ModificationHandler } from '../ModificationHandler'
+import { SchemaUpdater, updateEntity, updateModel } from '../utils/schemaUpdateUtils.js'
+import { createModificationType, Differ, ModificationHandler } from '../ModificationHandler.js'
 import deepEqual from 'fast-deep-equal'
 
 export class UpdateEntityOrderByModificationHandler implements ModificationHandler<UpdateEntityOrderByModificationData> {

package/src/modifications/entities/UpdateEntityTableNameModification.ts

@@ -1,7 +1,7 @@
 import { MigrationBuilder } from '@contember/database-migrations'
 import { Schema } from '@contember/schema'
-import { SchemaUpdater, updateEntity, updateModel } from '../utils/schemaUpdateUtils'
-import { createModificationType, Differ, ModificationHandler } from '../ModificationHandler'
+import { SchemaUpdater, updateEntity, updateModel } from '../utils/schemaUpdateUtils.js'
+import { createModificationType, Differ, ModificationHandler } from '../ModificationHandler.js'
 
 export class UpdateEntityTableNameModificationHandler implements ModificationHandler<UpdateEntityTableNameModificationData> {
 	constructor(private readonly data: UpdateEntityTableNameModificationData, private readonly schema: Schema) {}

package/src/modifications/entities/UpdateViewModification.ts

@@ -1,7 +1,7 @@
 import { MigrationBuilder } from '@contember/database-migrations'
 import { Model, Schema } from '@contember/schema'
-import { createModificationType, ModificationHandler } from '../ModificationHandler'
-import { SchemaUpdater, updateEntity, updateModel } from '../utils/schemaUpdateUtils'
+import { createModificationType, ModificationHandler } from '../ModificationHandler.js'
+import { SchemaUpdater, updateEntity, updateModel } from '../utils/schemaUpdateUtils.js'
 
 export class UpdateViewModificationHandler implements ModificationHandler<UpdateViewModificationData> {
 	constructor(private readonly data: UpdateViewModificationData, private readonly schema: Schema) {}

package/src/modifications/entities/index.ts

@@ -1,7 +1,7 @@
-export * from './CreateEntityModification'
-export * from './CreateViewModification'
-export * from './RemoveEntityModification'
-export * from './ToggleEventLogModification'
-export * from './UpdateEntityNameModification'
-export * from './UpdateEntityTableNameModification'
-export * from './UpdateEntityOrderByModification'
+export * from './CreateEntityModification.js'
+export * from './CreateViewModification.js'
+export * from './RemoveEntityModification.js'
+export * from './ToggleEventLogModification.js'
+export * from './UpdateEntityNameModification.js'
+export * from './UpdateEntityTableNameModification.js'
+export * from './UpdateEntityOrderByModification.js'

package/src/modifications/enums/CreateEnumModification.ts

@@ -1,8 +1,8 @@
 import { MigrationBuilder } from '@contember/database-migrations'
 import { Schema } from '@contember/schema'
-import { SchemaUpdater, updateModel } from '../utils/schemaUpdateUtils'
-import { createModificationType, Differ, ModificationHandler } from '../ModificationHandler'
-import { createCheck, getConstraintName } from './enumUtils'
+import { SchemaUpdater, updateModel } from '../utils/schemaUpdateUtils.js'
+import { createModificationType, Differ, ModificationHandler } from '../ModificationHandler.js'
+import { createCheck, getConstraintName } from './enumUtils.js'
 
 export class CreateEnumModificationHandler implements ModificationHandler<CreateEnumModificationData> {
 	constructor(private readonly data: CreateEnumModificationData, private readonly schema: Schema) {}

package/src/modifications/enums/RemoveEnumModification.ts

@@ -1,7 +1,7 @@
 import { MigrationBuilder } from '@contember/database-migrations'
 import { Schema } from '@contember/schema'
-import { SchemaUpdater, updateModel } from '../utils/schemaUpdateUtils'
-import { createModificationType, Differ, ModificationHandler } from '../ModificationHandler'
+import { SchemaUpdater, updateModel } from '../utils/schemaUpdateUtils.js'
+import { createModificationType, Differ, ModificationHandler } from '../ModificationHandler.js'
 
 export class RemoveEnumModificationHandler implements ModificationHandler<RemoveEnumModificationData> {
 	constructor(private readonly data: RemoveEnumModificationData, private readonly schema: Schema) {}

package/src/modifications/enums/UpdateEnumModification.ts

@@ -1,10 +1,10 @@
 import { MigrationBuilder } from '@contember/database-migrations'
 import { Model, Schema } from '@contember/schema'
-import { SchemaUpdater, updateModel } from '../utils/schemaUpdateUtils'
-import { createModificationType, Differ, ModificationHandler } from '../ModificationHandler'
+import { SchemaUpdater, updateModel } from '../utils/schemaUpdateUtils.js'
+import { createModificationType, Differ, ModificationHandler } from '../ModificationHandler.js'
 import deepEqual from 'fast-deep-equal'
-import { createCheck, getConstraintName } from './enumUtils'
-import { getColumnSqlType } from '../utils/columnUtils'
+import { createCheck, getConstraintName } from './enumUtils.js'
+import { getColumnSqlType } from '../utils/columnUtils.js'
 
 export class UpdateEnumModificationHandler implements ModificationHandler<UpdateEnumModificationData> {
 	constructor(private readonly data: UpdateEnumModificationData, private readonly schema: Schema) {}

package/src/modifications/enums/enumUtils.ts

@@ -1,4 +1,4 @@
-import { escapeSqlString } from '../../utils/escapeSqlString'
+import { escapeSqlString } from '../../utils/escapeSqlString.js'
 
 export const createCheck = (values: readonly string[]) => {
 	const joinedValues = values.map(it => `'${escapeSqlString(it)}'`).join(',')

package/src/modifications/enums/index.ts

@@ -1,3 +1,3 @@
-export * from './CreateEnumModification'
-export * from './RemoveEnumModification'
-export * from './UpdateEnumModification'
+export * from './CreateEnumModification.js'
+export * from './RemoveEnumModification.js'
+export * from './UpdateEnumModification.js'

package/src/modifications/fields/RemoveFieldModification.ts

@@ -1,9 +1,9 @@
 import { acceptFieldVisitor, isInverseRelation, isRelation } from '@contember/schema-utils'
 import { MigrationBuilder } from '@contember/database-migrations'
 import { Schema } from '@contember/schema'
-import { removeField, SchemaUpdater } from '../utils/schemaUpdateUtils'
-import { createModificationType, Differ, ModificationHandler, ModificationHandlerOptions } from '../ModificationHandler'
-import { isDefined } from '../../utils/isDefined'
+import { removeField, SchemaUpdater } from '../utils/schemaUpdateUtils.js'
+import { createModificationType, Differ, ModificationHandler, ModificationHandlerOptions } from '../ModificationHandler.js'
+import { isDefined } from '../../utils/isDefined.js'
 
 export class RemoveFieldModificationHandler implements ModificationHandler<RemoveFieldModificationData> {
 	constructor(

package/src/modifications/fields/UpdateFieldNameModification.ts

@@ -12,13 +12,18 @@ import {
 	updateEveryField,
 	updateModel,
 	updateSchema,
-} from '../utils/schemaUpdateUtils'
-import { createModificationType, ModificationHandler, ModificationHandlerCreateSqlOptions, ModificationHandlerOptions } from '../ModificationHandler'
+} from '../utils/schemaUpdateUtils.js'
+import {
+	createModificationType,
+	ModificationHandler,
+	ModificationHandlerCreateSqlOptions,
+	ModificationHandlerOptions,
+} from '../ModificationHandler.js'
 import { acceptFieldVisitor, PredicateDefinitionProcessor } from '@contember/schema-utils'
-import { VERSION_ACL_PATCH, VERSION_UPDATE_CONSTRAINT_FIELDS, VERSION_UPDATE_INDEX_FIELDS } from '../ModificationVersions'
-import { changeValue } from '../utils/valueUtils'
-import { updateColumnNameModification } from '../columns'
-import { NoopModification } from '../NoopModification'
+import { VERSION_ACL_PATCH, VERSION_UPDATE_CONSTRAINT_FIELDS, VERSION_UPDATE_INDEX_FIELDS } from '../ModificationVersions.js'
+import { changeValue } from '../utils/valueUtils.js'
+import { updateColumnNameModification } from '../columns/index.js'
+import { NoopModification } from '../NoopModification.js'
 
 export class UpdateFieldNameModificationHandler implements ModificationHandler<UpdateFieldNameModificationData> {
 	private renameColumnSubModification: ModificationHandler<any> = new NoopModification()
@@ -65,10 +70,21 @@ export class UpdateFieldNameModificationHandler implements ModificationHandler<U
 			? updateEntity(this.data.entityName, ({ entity }) => {
 				return {
 					...entity,
-					indexes: entity.indexes.map(unique => ({
-						...unique,
-						fields: unique.fields.map(changeValue(this.data.fieldName, this.data.newFieldName)),
-					})),
+					indexes: entity.indexes.map(index => {
+						// columnOptions is keyed by field name, so a rename must move its entry too —
+						// otherwise the options are dropped on regenerate and the (now stale-keyed) entry
+						// fails model validation ("Column options reference field <old>, not a key column").
+						const columnOptions = index.columnOptions && this.data.fieldName in index.columnOptions
+							? Object.fromEntries(
+								Object.entries(index.columnOptions).map(([field, options]) => [field === this.data.fieldName ? this.data.newFieldName : field, options]),
+							)
+							: index.columnOptions
+						return {
+							...index,
+							fields: index.fields.map(changeValue(this.data.fieldName, this.data.newFieldName)),
+							...(columnOptions !== undefined ? { columnOptions } : {}),
+						}
+					}),
 				}
 			})
 			: undefined

package/src/modifications/fields/index.ts

@@ -1,2 +1,2 @@
-export * from './RemoveFieldModification'
-export * from './UpdateFieldNameModification'
+export * from './RemoveFieldModification.js'
+export * from './UpdateFieldNameModification.js'

package/src/modifications/index.ts

@@ -1,13 +1,13 @@
-export * from './acl'
-export * from './columns'
-export * from './constraints'
-export * from './entities'
-export * from './enums'
-export * from './fields'
-export * from './relations'
-export * from './validation'
-export * from './ModificationHandlerFactory'
-export * from './ModificationVersions'
-export * from './ModificationHandler'
-export { SchemaUpdateError } from './exceptions'
-export * from './utils/sqlUpdateUtils'
+export * from './acl/index.js'
+export * from './columns/index.js'
+export * from './constraints/index.js'
+export * from './entities/index.js'
+export * from './enums/index.js'
+export * from './fields/index.js'
+export * from './relations/index.js'
+export * from './validation/index.js'
+export * from './ModificationHandlerFactory.js'
+export * from './ModificationVersions.js'
+export * from './ModificationHandler.js'
+export { SchemaUpdateError } from './exceptions.js'
+export * from './utils/sqlUpdateUtils.js'

package/src/modifications/indexes/CreateIndexModification.ts

@@ -1,9 +1,9 @@
 import { MigrationBuilder } from '@contember/database-migrations'
 import { Model, Schema } from '@contember/schema'
-import { SchemaUpdater, updateEntity, updateModel } from '../utils/schemaUpdateUtils'
-import { createModificationType, Differ, ModificationHandler, ModificationHandlerCreateSqlOptions } from '../ModificationHandler'
-import { wrapIdentifier } from '../../utils/dbHelpers'
-import { getIndexColumns } from './utils'
+import { SchemaUpdater, updateEntity, updateModel } from '../utils/schemaUpdateUtils.js'
+import { createModificationType, Differ, ModificationHandler, ModificationHandlerCreateSqlOptions } from '../ModificationHandler.js'
+import { wrapIdentifier } from '../../utils/dbHelpers.js'
+import { getIndexColumns } from './utils.js'
 import deepEqual from 'fast-deep-equal'
 
 export class CreateIndexModificationHandler implements ModificationHandler<CreateIndexModificationData> {
@@ -14,18 +14,41 @@ export class CreateIndexModificationHandler implements ModificationHandler<Creat
 		if (entity.view && !entity.view.materialized) {
 			return
 		}
-		const fields = this.data.index.fields
+		const index = this.data.index
 		const columns = getIndexColumns({
-			fields,
+			fields: index.fields,
 			entity,
 			model: this.schema.model,
 		})
 
 		const tableNameId = wrapIdentifier(entity.tableName)
-		const columnNameIds = columns.map(wrapIdentifier)
-		const methodClause = this.data.index.method ? ` USING ${this.data.index.method}` : ''
+		// Each key column may carry its own operator class (falling back to the global opClass),
+		// sort direction (ASC is the default and omitted) and NULLS placement. Postgres expects
+		// the parts in this order: column [opclass] [ASC|DESC] [NULLS {FIRST|LAST}].
+		// The opclass is emitted verbatim (validated to an identifier shape in ModelValidator). Migrations
+		// run with search_path set to the stage schema, so the value must already carry any needed schema
+		// qualifier: an extension's class as "public.gin_trgm_ops", a built-in one (in pg_catalog) as
+		// plain "text_pattern_ops".
+		const columnNameIds = index.fields.map((field, i) => {
+			const options = index.columnOptions?.[field]
+			const opClass = options?.opClass ?? index.opClass
+			const opClassSuffix = opClass ? ` ${opClass}` : ''
+			const orderSuffix = options?.order === 'desc' ? ' DESC' : ''
+			const nullsSuffix = options?.nulls === 'first' ? ' NULLS FIRST' : options?.nulls === 'last' ? ' NULLS LAST' : ''
+			return wrapIdentifier(columns[i]) + opClassSuffix + orderSuffix + nullsSuffix
+		})
+		const methodClause = index.method ? ` USING ${index.method}` : ''
+
+		const includeClause = index.include?.length
+			? ` INCLUDE (${getIndexColumns({ fields: index.include, entity, model: this.schema.model }).map(wrapIdentifier).join(', ')})`
+			: ''
+		// `where` is a raw, developer-authored SQL predicate. Its trust boundary is identical to
+		// @c.View's raw body — committed to a migration and gated by code review, not end-user input.
+		// Its shape is validated in ModelValidator (non-empty, no statement terminator); here we only
+		// wrap it in parentheses so it stays a self-contained boolean expression.
+		const whereClause = index.where ? ` WHERE (${index.where})` : ''
 
-		builder.sql(`CREATE INDEX ON ${tableNameId}${methodClause} (${columnNameIds.join(', ')})`)
+		builder.sql(`CREATE INDEX ON ${tableNameId}${methodClause} (${columnNameIds.join(', ')})${includeClause}${whereClause}`)
 
 		invalidateDatabaseMetadata()
 	}
@@ -43,9 +66,22 @@ export class CreateIndexModificationHandler implements ModificationHandler<Creat
 	}
 
 	describe() {
-		const methodText = this.data.index.method ? ` using ${this.data.index.method}` : ''
+		const index = this.data.index
+		const methodText = index.method ? ` using ${index.method}` : ''
+		const includeText = index.include?.length ? ` include (${index.include.join(', ')})` : ''
+		const whereText = index.where ? ` where ${index.where}` : ''
+		// columnOptions is part of index identity, so surface it in the description too — otherwise two
+		// indexes on the same columns differing only by sort order / NULLS / opClass render identically.
+		const columnOptionsText = index.columnOptions && Object.keys(index.columnOptions).length > 0
+			? ` options (${
+				Object.entries(index.columnOptions).map(([field, opts]) => {
+					const parts = [opts.order, opts.nulls ? `nulls ${opts.nulls}` : '', opts.opClass ? `opclass ${opts.opClass}` : ''].filter(Boolean)
+					return `${field}: ${parts.join(' ')}`
+				}).join(', ')
+			})`
+			: ''
 		return {
-			message: `Create index(${this.data.index.fields.join(', ')})${methodText} on entity ${this.data.entityName}`,
+			message: `Create index(${index.fields.join(', ')})${methodText}${includeText}${whereText}${columnOptionsText} on entity ${this.data.entityName}`,
 		}
 	}
 }

package/src/modifications/indexes/RemoveIndexModification.ts

@@ -1,10 +1,19 @@
 import { MigrationBuilder } from '@contember/database-migrations'
-import { Schema } from '@contember/schema'
-import { SchemaUpdater, updateEntity, updateModel } from '../utils/schemaUpdateUtils'
-import { createModificationType, Differ, ModificationHandler, ModificationHandlerCreateSqlOptions } from '../ModificationHandler'
+import { Model, Schema } from '@contember/schema'
+import { SchemaUpdater, updateEntity, updateModel } from '../utils/schemaUpdateUtils.js'
+import { createModificationType, Differ, ModificationHandler, ModificationHandlerCreateSqlOptions } from '../ModificationHandler.js'
 import deepEqual from 'fast-deep-equal'
-import { getIndexColumns } from './utils'
-import { wrapIdentifier } from '../../utils/dbHelpers'
+import { getIndexColumns } from './utils.js'
+import { wrapIdentifier } from '../../utils/dbHelpers.js'
+
+type IndexIdentity = Pick<Model.Index, 'fields' | 'where' | 'include' | 'columnOptions' | 'method' | 'opClass'>
+const indexIdentityEquals = (a: IndexIdentity, b: IndexIdentity) =>
+	deepEqual(a.fields, b.fields)
+	&& (a.where ?? undefined) === (b.where ?? undefined)
+	&& deepEqual(a.include ?? undefined, b.include ?? undefined)
+	&& deepEqual(a.columnOptions ?? undefined, b.columnOptions ?? undefined)
+	&& (a.method ?? undefined) === (b.method ?? undefined)
+	&& (a.opClass ?? undefined) === (b.opClass ?? undefined)
 
 export class RemoveIndexModificationHandler implements ModificationHandler<RemoveIndexModificationData> {
 	constructor(private readonly data: RemoveIndexModificationData, private readonly schema: Schema) {}
@@ -14,16 +23,38 @@ export class RemoveIndexModificationHandler implements ModificationHandler<Remov
 		if (entity.view && !entity.view.materialized) {
 			return
 		}
-		const fields = this.getFields()
+		const index = this.getIndex()
 
-		const columns = getIndexColumns({
-			entity,
-			fields,
-			model: this.schema.model,
-		})
+		// The DB-metadata layer (DatabaseMetadataResolver) exposes only table + columns (as an unordered
+		// set) + uniqueness, so the physical DROP is matched by table + columns. Postgres' pg_index.indkey
+		// includes the INCLUDE columns alongside the key columns, so a covering index's metadata lists both —
+		// we match the same combined set here. Everything else that distinguishes two indexes on the same
+		// column set — the partial WHERE predicate, per-column options (sort order / NULLS / operator class),
+		// key-column ORDER (the set comparison is order-insensitive), the index method, and the index-level
+		// operator class — is invisible to the metadata, so such siblings are indistinguishable here. We
+		// detect that ambiguity below and fail loudly rather than DROP a sibling the schema still expects to
+		// keep. Schema-level identity (see getSchemaUpdater) IS fully aware of these discriminators, so the
+		// diff itself never conflates them.
+		const columns = [
+			...getIndexColumns({ entity, fields: index.fields, model: this.schema.model }),
+			...(index.include ? getIndexColumns({ entity, fields: index.include, model: this.schema.model }) : []),
+		]
 
 		const indexNames = databaseMetadata.indexes.filter({ tableName: entity.tableName, columnNames: columns, unique: false }).getNames()
 
+		// If more than one physical index matches these columns we cannot tell which one this modification
+		// targets (the metadata hides the predicate / per-column options / column order / index method /
+		// index-level operator class that distinguish them). Dropping every match would silently take out an
+		// index the schema still expects — refuse instead, so the obsolete one can be dropped by hand.
+		if (indexNames.length > 1) {
+			throw new Error(
+				`Cannot unambiguously drop index on entity ${this.data.entityName} (${index.fields.join(', ')}): `
+					+ `${indexNames.length} indexes match these columns and the database metadata does not expose the predicate (where), `
+					+ `per-column options (sort order / NULLS / operator class), column order, index method or index-level operator class that distinguish them. `
+					+ `Drop the obsolete index manually.`,
+			)
+		}
+
 		for (const name of indexNames) {
 			builder.sql(`DROP INDEX ${wrapIdentifier(name)}`)
 		}
@@ -31,10 +62,10 @@ export class RemoveIndexModificationHandler implements ModificationHandler<Remov
 	}
 
 	public getSchemaUpdater(): SchemaUpdater {
-		const fields = this.getFields()
+		const index = this.getIndex()
 		return updateModel(
 			updateEntity(this.data.entityName, ({ entity }) => {
-				const indexes = entity.indexes.filter(it => !deepEqual(it.fields, fields))
+				const indexes = entity.indexes.filter(it => !indexIdentityEquals(it, index))
 				return {
 					...entity,
 					indexes,
@@ -44,19 +75,38 @@ export class RemoveIndexModificationHandler implements ModificationHandler<Remov
 	}
 
 	describe() {
-		const fields = this.getFields()
-		return { message: `Remove index (${fields.join(', ')}) on entity ${this.data.entityName}` }
+		const index = this.getIndex()
+		return { message: `Remove index (${index.fields.join(', ')}) on entity ${this.data.entityName}` }
 	}
 
-	getFields() {
-		const entity = this.schema.model.entities[this.data.entityName]
-		const fields = 'indexName' in this.data
-			? entity.indexes.find(it => it.name === this.data.indexName)?.fields
-			: this.data.fields
-		if (!fields) {
-			throw new Error()
+	private getIndex(): IndexIdentity {
+		const { entityName } = this.data
+		const entity = this.schema.model.entities[entityName]
+		if ('indexName' in this.data && this.data.indexName !== undefined) {
+			const index = entity.indexes.find(it => it.name === this.data.indexName)
+			if (!index) {
+				throw new Error(`Index named "${this.data.indexName}" not found on entity ${entityName}`)
+			}
+			return {
+				fields: index.fields,
+				where: index.where,
+				include: index.include,
+				columnOptions: index.columnOptions,
+				method: index.method,
+				opClass: index.opClass,
+			}
+		}
+		if (!this.data.fields) {
+			throw new Error(`removeIndex modification on entity ${entityName} requires either "indexName" or "fields"`)
+		}
+		return {
+			fields: this.data.fields,
+			where: this.data.where,
+			include: this.data.include,
+			columnOptions: this.data.columnOptions,
+			method: this.data.method,
+			opClass: this.data.opClass,
 		}
-		return fields
 	}
 }
 
@@ -70,10 +120,20 @@ export type RemoveIndexModificationData =
 		entityName: string
 		indexName: string
 		fields?: never
+		where?: never
+		include?: never
+		columnOptions?: never
+		method?: never
+		opClass?: never
 	}
 	| {
 		entityName: string
 		fields: readonly string[]
+		where?: string
+		include?: readonly string[]
+		columnOptions?: { readonly [field: string]: Model.IndexColumnOptions }
+		method?: Model.IndexMethod
+		opClass?: string
 		indexName?: never
 	}
 
@@ -94,6 +154,15 @@ export class RemoveIndexDiffer implements Differ {
 					removeIndexModification.createModification({
 						entityName: entity.name,
 						fields: index.fields,
+						// keep every identity-bearing option (WHERE/INCLUDE/columnOptions/method/opClass) in the
+						// modification so indexes that share the same key columns but differ by any of them are
+						// removed individually; omit the keys when absent to keep legacy migration JSON
+						// byte-for-byte identical.
+						...(index.where !== undefined ? { where: index.where } : {}),
+						...(index.include !== undefined ? { include: index.include } : {}),
+						...(index.columnOptions !== undefined ? { columnOptions: index.columnOptions } : {}),
+						...(index.method !== undefined ? { method: index.method } : {}),
+						...(index.opClass !== undefined ? { opClass: index.opClass } : {}),
 					})
 				)
 		)