@contember/schema-migrations 2.1.0-rc.3 → 2.2.0-alpha.10

package/src/modifications/differs/RemoveViewDiffer.ts

@@ -1,13 +1,24 @@
-import { Differ } from '../ModificationHandler'
+import { Differ } from '../ModificationHandler.js'
 import { Schema } from '@contember/schema'
 import deepEqual from 'fast-deep-equal'
-import { cascadeRemoveDependantViews } from '../utils/viewDependencies'
-import { UpdateColumnDefinitionDiffer } from '../columns'
+import { cascadeRemoveDependantViews, isReplaceableViewChange } from '../utils/viewDependencies.js'
+import { UpdateColumnDefinitionDiffer } from '../columns/index.js'
 
 /**
- * Remove changed or removed view.
+ * Remove views that were removed or changed in a way that requires a drop & recreate.
+ *
+ * View changes that can be applied in-place via `CREATE OR REPLACE VIEW` (see
+ * {@link isReplaceableViewChange}) are intentionally skipped here so they don't trigger
+ * the drop cascade onto dependant views – those are handled by `UpdateViewDiffer`.
+ *
+ * When `recreateAllViews` is set, the in-place optimization is disabled and every changed
+ * view drops & recreates (with its dependant cascade) as before. This is the escape hatch
+ * for the rare case where a view's actual output columns drifted without a matching field
+ * change, which `CREATE OR REPLACE VIEW` would reject at execute time (`SQLSTATE 42P16`).
  */
 export class RemoveViewDiffer implements Differ {
+	constructor(private readonly recreateAllViews: boolean = false) {}
+
 	createDiff(originalSchema: Schema, updatedSchema: Schema) {
 		const changedOrRemovedViews = Object.values(originalSchema.model.entities)
 			.filter(it => {
@@ -30,7 +41,8 @@ export class RemoveViewDiffer implements Differ {
 				}
 
 				if (!deepEqual(updatedEntity.view, it.view)) {
-					return true // view is different
+					// view changed – cascade only when it cannot be replaced in-place
+					return this.recreateAllViews || !isReplaceableViewChange(it, updatedEntity)
 				}
 
 				return false

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}`,
 		}
 	}
 }