Add PostgreSQL expression index support and enhance complex index handling

- Introduced expression index functionality for PostgreSQL, including migration SQL generation for `CREATE INDEX … ((expr))`.
- Added `ResolvedIndexPart` for detailed index part resolution, supporting both columns and SQL expressions.
- Enhanced `IndexDescriptor` and related builders to handle mixed column and expression parts.
- Introduced `IndexPartsSerializer` for serializing index parts.
- Exposed `HasExpressionIndex` API for defining functional indexes with advanced options (e.g., unique, filters, include properties).
- Refactored PostgreSQL index option methods to support both complex-property and expression indexes.
- Updated README.md with PostgreSQL-specific instructions and usage examples.
- Incremented package version to 3.0.0.

Author: CaffeinatedCoder

Directory.Build.props

@@ -1,6 +1,6 @@
 <Project>
     <PropertyGroup>
-        <Version>2.0.5</Version>
+        <Version>3.0.0</Version>
         <Authors>CaffeinatedCoder</Authors>
         <PackageLicenseExpression>MIT</PackageLicenseExpression>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>

EFCore.ComplexIndexes.PostgreSQL/ExpressionIndexBuilder.cs

@@ -0,0 +1,57 @@
+namespace EFCore.ComplexIndexes.PostgreSQL;
+
+/// <summary>
+/// Builds a PostgreSQL expression index: an ordered list of parts, each a verbatim SQL fragment.
+/// Provider-specific options (e.g. <c>UseGin</c>) are available as extension methods via
+/// <see cref="IIndexAnnotationBuilder"/>.
+/// </summary>
+/// <remarks>
+/// Every part is supplied as raw SQL and emitted verbatim — no property-to-column resolution and
+/// no identifier quoting.
+/// </remarks>
+public sealed class ExpressionIndexBuilder : IIndexAnnotationBuilder
+{
+    private readonly List<IndexPartDefinition> _parts = [];
+
+    internal Dictionary<string, object?> Annotations { get; } = new();
+
+    internal IReadOnlyList<IndexPartDefinition> Parts => _parts;
+
+    Dictionary<string, object?> IIndexAnnotationBuilder.Annotations => Annotations;
+
+    /// <summary>Adds a verbatim SQL fragment as the next part of the index's column list.</summary>
+    public ExpressionIndexBuilder Expression(string sql)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(sql);
+        _parts.Add(new IndexPartDefinition { Expression = sql });
+        return this;
+    }
+
+    /// <summary>Adds a part from an <see cref="IIndexExpression"/>, resolving it to its SQL fragment.</summary>
+    public ExpressionIndexBuilder Expression(IIndexExpression expression)
+    {
+        ArgumentNullException.ThrowIfNull(expression);
+        return Expression(expression.ToSql());
+    }
+
+    /// <summary>Marks the index as unique.</summary>
+    public ExpressionIndexBuilder IsUnique(bool unique = true)
+    {
+        Annotations[ComplexIndexAnnotations.IsUnique] = unique;
+        return this;
+    }
+
+    /// <summary>Applies a SQL filter (partial index) expression.</summary>
+    public ExpressionIndexBuilder HasFilter(string filter)
+    {
+        Annotations[ComplexIndexAnnotations.Filter] = filter;
+        return this;
+    }
+
+    /// <summary>Sets a custom name for the index.</summary>
+    public ExpressionIndexBuilder HasName(string name)
+    {
+        Annotations[ComplexIndexAnnotations.IndexName] = name;
+        return this;
+    }
+}

EFCore.ComplexIndexes.PostgreSQL/NpgsqlComplexIndexBuilderExtensions.cs

@@ -1,52 +1,54 @@
 namespace EFCore.ComplexIndexes.PostgreSQL;
 
 /// <summary>
-/// PostgreSQL-specific extension methods for <see cref="ComplexIndexBuilder"/>.
+/// PostgreSQL-specific index options. These work on any index option builder
+/// (<see cref="ComplexIndexBuilder"/> for complex-property indexes and
+/// <see cref="ExpressionIndexBuilder"/> for expression indexes) via <see cref="IIndexAnnotationBuilder"/>.
 /// </summary>
 public static class NpgsqlComplexIndexBuilderExtensions
 {
     /// <summary>Creates a GIN index — ideal for full-text search, JSONB, and array columns.</summary>
-    public static ComplexIndexBuilder UseGin(this ComplexIndexBuilder builder)
-        => builder.HasAnnotation(NpgsqlAnnotations.IndexMethod, "gin");
+    public static TBuilder UseGin<TBuilder>(this TBuilder builder) where TBuilder : IIndexAnnotationBuilder
+        => builder.Set(NpgsqlAnnotations.IndexMethod, "gin");
 
     /// <summary>Creates a GiST index — ideal for geometric, range, and full-text search columns.</summary>
-    public static ComplexIndexBuilder UseGist(this ComplexIndexBuilder builder)
-        => builder.HasAnnotation(NpgsqlAnnotations.IndexMethod, "gist");
+    public static TBuilder UseGist<TBuilder>(this TBuilder builder) where TBuilder : IIndexAnnotationBuilder
+        => builder.Set(NpgsqlAnnotations.IndexMethod, "gist");
 
     /// <summary>Creates a BRIN index — ideal for large, naturally ordered tables (e.g., time-series data).</summary>
-    public static ComplexIndexBuilder UseBrin(this ComplexIndexBuilder builder)
-        => builder.HasAnnotation(NpgsqlAnnotations.IndexMethod, "brin");
+    public static TBuilder UseBrin<TBuilder>(this TBuilder builder) where TBuilder : IIndexAnnotationBuilder
+        => builder.Set(NpgsqlAnnotations.IndexMethod, "brin");
 
     /// <summary>Creates a hash index — useful for simple equality comparisons.</summary>
-    public static ComplexIndexBuilder UseHash(this ComplexIndexBuilder builder)
-        => builder.HasAnnotation(NpgsqlAnnotations.IndexMethod, "hash");
+    public static TBuilder UseHash<TBuilder>(this TBuilder builder) where TBuilder : IIndexAnnotationBuilder
+        => builder.Set(NpgsqlAnnotations.IndexMethod, "hash");
 
     /// <summary>Creates an SP-GiST index — ideal for partitioned search trees (e.g., IP addresses, phone numbers).</summary>
-    public static ComplexIndexBuilder UseSpGist(this ComplexIndexBuilder builder)
-        => builder.HasAnnotation(NpgsqlAnnotations.IndexMethod, "spgist");
+    public static TBuilder UseSpGist<TBuilder>(this TBuilder builder) where TBuilder : IIndexAnnotationBuilder
+        => builder.Set(NpgsqlAnnotations.IndexMethod, "spgist");
 
-    /// <summary>
-    /// Specifies per-column operator classes for the index (e.g., <c>jsonb_path_ops</c>).
-    /// </summary>
-    public static ComplexIndexBuilder HasOperators(this ComplexIndexBuilder builder, params string[] operators)
-        => builder.HasAnnotation(NpgsqlAnnotations.IndexOperators, operators);
+    /// <summary>Specifies per-column operator classes for the index (e.g., <c>jsonb_path_ops</c>).</summary>
+    public static TBuilder HasOperators<TBuilder>(this TBuilder builder, params string[] operators) where TBuilder : IIndexAnnotationBuilder
+        => builder.Set(NpgsqlAnnotations.IndexOperators, operators);
 
-    /// <summary>
-    /// Specifies non-key columns to include in the index (covering index).
-    /// </summary>
-    public static ComplexIndexBuilder IncludeProperties(this ComplexIndexBuilder builder, params string[] properties)
-        => builder.HasAnnotation(NpgsqlAnnotations.IndexInclude, properties);
+    /// <summary>Specifies non-key columns to include in the index (covering index).</summary>
+    public static TBuilder IncludeProperties<TBuilder>(this TBuilder builder, params string[] properties) where TBuilder : IIndexAnnotationBuilder
+        => builder.Set(NpgsqlAnnotations.IndexInclude, properties);
 
-    /// <summary>
-    /// Specifies that the index should be created concurrently (non-blocking).
-    /// </summary>
-    public static ComplexIndexBuilder IsCreatedConcurrently(this ComplexIndexBuilder builder, bool concurrent = true)
-        => builder.HasAnnotation(NpgsqlAnnotations.CreatedConcurrently, concurrent);
+    /// <summary>Specifies that the index should be created concurrently (non-blocking).</summary>
+    public static TBuilder IsCreatedConcurrently<TBuilder>(this TBuilder builder, bool concurrent = true) where TBuilder : IIndexAnnotationBuilder
+        => builder.Set(NpgsqlAnnotations.CreatedConcurrently, concurrent);
 
     /// <summary>
     /// Specifies whether null values are considered distinct in a unique index.
     /// When <c>false</c>, multiple nulls violate the uniqueness constraint.
     /// </summary>
-    public static ComplexIndexBuilder AreNullsDistinct(this ComplexIndexBuilder builder, bool nullsDistinct = true)
-        => builder.HasAnnotation(NpgsqlAnnotations.NullsDistinct, nullsDistinct);
-}
+    public static TBuilder AreNullsDistinct<TBuilder>(this TBuilder builder, bool nullsDistinct = true) where TBuilder : IIndexAnnotationBuilder
+        => builder.Set(NpgsqlAnnotations.NullsDistinct, nullsDistinct);
+
+    private static TBuilder Set<TBuilder>(this TBuilder builder, string key, object? value) where TBuilder : IIndexAnnotationBuilder
+    {
+        builder.Annotations[key] = value;
+        return builder;
+    }
+}

EFCore.ComplexIndexes.PostgreSQL/NpgsqlComplexIndexDbContextOptionsExtensions.cs

@@ -0,0 +1,18 @@
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+namespace EFCore.ComplexIndexes.PostgreSQL;
+
+/// <summary>
+/// Runtime wiring for expression indexes on PostgreSQL.
+/// </summary>
+public static class NpgsqlComplexIndexDbContextOptionsExtensions
+{
+    /// <summary>
+    /// Replaces the migrations SQL generator with one that can render expression indexes
+    /// defined via <c>HasExpressionIndex</c>. Call this after <c>UseNpgsql(...)</c>:
+    /// <code>options.UseNpgsql(connectionString).UseNpgsqlComplexIndexes();</code>
+    /// </summary>
+    public static DbContextOptionsBuilder UseNpgsqlComplexIndexes(this DbContextOptionsBuilder optionsBuilder)
+        => optionsBuilder.ReplaceService<IMigrationsSqlGenerator, NpgsqlComplexIndexSqlGenerator>();
+}

EFCore.ComplexIndexes.PostgreSQL/NpgsqlComplexIndexSqlGenerator.cs

@@ -0,0 +1,108 @@
+using System.Collections;
+using Microsoft.EntityFrameworkCore.Metadata;
+using Microsoft.EntityFrameworkCore.Migrations;
+using Microsoft.EntityFrameworkCore.Migrations.Operations;
+using Npgsql.EntityFrameworkCore.PostgreSQL.Infrastructure.Internal;
+using Npgsql.EntityFrameworkCore.PostgreSQL.Migrations;
+
+namespace EFCore.ComplexIndexes.PostgreSQL;
+
+#pragma warning disable EF1001
+
+/// <summary>
+/// Renders <c>CREATE INDEX</c> for expression indexes — those whose column list contains one or
+/// more verbatim SQL expressions. Npgsql's base generator builds the column list from
+/// <c>operation.Columns</c> (quoted identifiers) with no hook to inject an expression, so when the
+/// <see cref="ComplexIndexAnnotations.IndexParts"/> annotation is present this generator renders the
+/// statement itself; all other operations delegate to the base Npgsql generator unchanged.
+/// </summary>
+public class NpgsqlComplexIndexSqlGenerator(
+    MigrationsSqlGeneratorDependencies dependencies,
+    INpgsqlSingletonOptions            npgsqlSingletonOptions
+) : NpgsqlMigrationsSqlGenerator(dependencies, npgsqlSingletonOptions)
+{
+    protected override void Generate(
+        CreateIndexOperation        operation,
+        IModel?                     model,
+        MigrationCommandListBuilder builder,
+        bool                        terminate = true
+    )
+    {
+        if (operation[ComplexIndexAnnotations.IndexParts] is not string partsJson)
+        {
+            base.Generate(operation, model, builder, terminate);
+            return;
+        }
+
+        var parts     = IndexPartsSerializer.Deserialize(partsJson);
+        var sqlHelper = Dependencies.SqlGenerationHelper;
+
+        var concurrently  = operation[NpgsqlAnnotations.CreatedConcurrently] is true;
+        var method        = operation[NpgsqlAnnotations.IndexMethod] as string;
+        var operators     = ToStringList(operation[NpgsqlAnnotations.IndexOperators]);
+        var include       = ToStringList(operation[NpgsqlAnnotations.IndexInclude]);
+        var nullsDistinct = operation[NpgsqlAnnotations.NullsDistinct];
+
+        builder.Append("CREATE ");
+        if (operation.IsUnique)
+            builder.Append("UNIQUE ");
+        builder.Append("INDEX ");
+        if (concurrently)
+            builder.Append("CONCURRENTLY ");
+
+        builder
+           .Append(sqlHelper.DelimitIdentifier(operation.Name))
+           .Append(" ON ")
+           .Append(sqlHelper.DelimitIdentifier(operation.Table, operation.Schema));
+
+        if (!string.IsNullOrEmpty(method))
+            builder.Append(" USING ").Append(method);
+
+        builder.Append(" (");
+        for (var i = 0; i < parts.Count; i++)
+        {
+            if (i > 0)
+                builder.Append(", ");
+
+            builder.Append(parts[i].IsExpression
+                               ? $"({parts[i].Value})"
+                               : sqlHelper.DelimitIdentifier(parts[i].Value));
+
+            if (operators is not null && i < operators.Count && !string.IsNullOrEmpty(operators[i]))
+                builder.Append(" ").Append(operators[i]);
+        }
+
+        builder.Append(")");
+
+        if (include is { Count: > 0 })
+        {
+            builder.Append(" INCLUDE (");
+            builder.Append(string.Join(", ", include.Select(sqlHelper.DelimitIdentifier)));
+            builder.Append(")");
+        }
+
+        // Default in PostgreSQL is NULLS DISTINCT; only the non-default needs emitting.
+        if (nullsDistinct is false)
+            builder.Append(" NULLS NOT DISTINCT");
+
+        if (!string.IsNullOrEmpty(operation.Filter))
+            builder.Append(" WHERE ").Append(operation.Filter);
+
+        if (terminate)
+        {
+            builder.AppendLine(sqlHelper.StatementTerminator);
+            EndStatement(builder, suppressTransaction: concurrently);
+        }
+    }
+
+    private static IReadOnlyList<string>? ToStringList(object? value) =>
+        value switch
+        {
+            null          => null,
+            string[] s    => s,
+            IEnumerable e => [.. e.Cast<object?>().Select(o => o?.ToString() ?? string.Empty)],
+            _             => null
+        };
+}
+
+#pragma warning restore EF1001

EFCore.ComplexIndexes.PostgreSQL/NpgsqlExpressionIndexExtensions.cs

@@ -0,0 +1,82 @@
+using Microsoft.EntityFrameworkCore.Metadata.Builders;
+
+namespace EFCore.ComplexIndexes.PostgreSQL;
+
+/// <summary>
+/// PostgreSQL expression-index API. Expression indexes are provider-specific (PostgreSQL renders
+/// <c>CREATE INDEX … ((expr))</c> natively; other providers model the same intent differently, e.g.
+/// SQL Server via persisted computed columns), so the entry point lives in the provider package
+/// rather than the provider-agnostic core.
+/// </summary>
+public static class NpgsqlExpressionIndexExtensions
+{
+    /// <summary>
+    /// Configures an index whose single entry is a verbatim SQL expression (e.g. <c>lower(name)</c>).
+    /// The expression is emitted exactly as given — it must reference real column names.
+    /// Requires runtime wiring via <c>UseNpgsqlComplexIndexes()</c>.
+    /// </summary>
+    public static EntityTypeBuilder<TEntity> HasExpressionIndex<TEntity>(
+        this EntityTypeBuilder<TEntity> builder,
+        string                          expression,
+        bool                            isUnique  = false,
+        string?                         filter    = null,
+        string?                         indexName = null
+    )
+        where TEntity : class
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(expression);
+
+        var definition = new CompositeIndexDefinition
+                         {
+                             Parts     = [new IndexPartDefinition { Expression = expression }],
+                             IsUnique  = isUnique,
+                             Filter    = filter,
+                             IndexName = indexName
+                         };
+
+        ComplexIndexStorage.AddOrReplace(builder, definition);
+        return builder;
+    }
+
+    /// <summary>
+    /// Configures an index from an ordered list of verbatim SQL parts using a builder callback.
+    /// Provider-specific options (GIN, INCLUDE, …) are available as extension methods on
+    /// <see cref="ExpressionIndexBuilder"/>. Requires runtime wiring via <c>UseNpgsqlComplexIndexes()</c>.
+    /// </summary>
+    public static EntityTypeBuilder<TEntity> HasExpressionIndex<TEntity>(
+        this EntityTypeBuilder<TEntity> builder,
+        Action<ExpressionIndexBuilder>  configure
+    )
+        where TEntity : class
+    {
+        ArgumentNullException.ThrowIfNull(configure);
+
+        var indexBuilder = new ExpressionIndexBuilder();
+        configure(indexBuilder);
+
+        if (indexBuilder.Parts.Count == 0)
+            throw new ArgumentException(
+                "An expression index requires at least one part. Call Expression(...) at least once."
+            );
+
+        var annotations = indexBuilder.Annotations;
+
+        var providerAnnotations = annotations
+                                 .Where(kv => kv.Key != ComplexIndexAnnotations.IsUnique
+                                           && kv.Key != ComplexIndexAnnotations.Filter
+                                           && kv.Key != ComplexIndexAnnotations.IndexName)
+                                 .ToDictionary(kv => kv.Key, kv => kv.Value);
+
+        var definition = new CompositeIndexDefinition
+                         {
+                             Parts               = [.. indexBuilder.Parts],
+                             IsUnique            = annotations.TryGetValue(ComplexIndexAnnotations.IsUnique, out var u) && u is true,
+                             Filter              = annotations.GetValueOrDefault(ComplexIndexAnnotations.Filter) as string,
+                             IndexName           = annotations.GetValueOrDefault(ComplexIndexAnnotations.IndexName) as string,
+                             ProviderAnnotations = providerAnnotations.Count > 0 ? providerAnnotations : null
+                         };
+
+        ComplexIndexStorage.AddOrReplace(builder, definition);
+        return builder;
+    }
+}