feat: initial release of Equibles.ParadeDB.EntityFrameworkCore

daniel3303 · daniel3303 · commit 765fc44da85d · 2026-03-10T19:31:29.000Z
EF Core integration for ParadeDB pg_search BM25 full-text search.
Provides [Bm25Index] attribute and UseParadeDb() extension for
automatic index creation via EF Core conventions and migrations.
diff --git a/.github/workflows/nuget-publish.yml b/.github/workflows/nuget-publish.yml
@@ -0,0 +1,34 @@
+name: Publish to NuGet
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Extract version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
+
+      - name: Restore
+        run: dotnet restore
+
+      - name: Build
+        run: dotnet build -c Release --no-restore /p:Version=${{ steps.version.outputs.VERSION }}
+
+      - name: Pack
+        run: dotnet pack -c Release --no-build /p:Version=${{ steps.version.outputs.VERSION }} -o ./nupkg
+
+      - name: Push to NuGet
+        run: dotnet nuget push ./nupkg/*.nupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,24 @@
+## .NET
+bin/
+obj/
+*.user
+*.suo
+*.userosscache
+*.sln.docstates
+
+## NuGet
+*.nupkg
+**/[Pp]ackages/*
+!**/[Pp]ackages/build/
+
+## IDE
+.vs/
+.idea/
+*.DotSettings.user
+
+## OS
+.DS_Store
+Thumbs.db
+
+## Claude Code
+.claude/
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -0,0 +1,22 @@
+<Project>
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Version>0.1.0</Version>
+    <Authors>Equibles, Daniel Oliveira</Authors>
+    <Company>Equibles</Company>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <PackageProjectUrl>https://github.com/daniel3303/ParadeDbEfCore</PackageProjectUrl>
+    <RepositoryUrl>https://github.com/daniel3303/ParadeDbEfCore</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <PackageTags>efcore paradedb bm25 postgresql full-text-search pg_search entityframeworkcore</PackageTags>
+    <IsPackable>true</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <None Include="$(MSBuildThisFileDirectory)README.md" Pack="true" PackagePath="\" />
+  </ItemGroup>
+
+</Project>
diff --git a/Equibles.ParadeDB.EntityFrameworkCore.slnx b/Equibles.ParadeDB.EntityFrameworkCore.slnx
@@ -0,0 +1,3 @@
+<Solution>
+  <Project Path="Equibles.ParadeDB.EntityFrameworkCore/Equibles.ParadeDB.EntityFrameworkCore.csproj" />
+</Solution>
diff --git a/Equibles.ParadeDB.EntityFrameworkCore/Bm25IndexAttribute.cs b/Equibles.ParadeDB.EntityFrameworkCore/Bm25IndexAttribute.cs
@@ -0,0 +1,12 @@
+namespace Equibles.ParadeDB.EntityFrameworkCore;
+
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = false)]
+public sealed class Bm25IndexAttribute : Attribute {
+    public string KeyField { get; }
+    public string[] Columns { get; }
+
+    public Bm25IndexAttribute(string keyField, params string[] columns) {
+        KeyField = keyField;
+        Columns = [keyField, ..columns];
+    }
+}
diff --git a/Equibles.ParadeDB.EntityFrameworkCore/Equibles.ParadeDB.EntityFrameworkCore.csproj b/Equibles.ParadeDB.EntityFrameworkCore/Equibles.ParadeDB.EntityFrameworkCore.csproj
@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <Description>EF Core integration for ParadeDB pg_search BM25 full-text search indexes on PostgreSQL. Provides a [Bm25Index] attribute and UseParadeDb() extension for automatic index creation via EF Core conventions.</Description>
+        <PackageId>Equibles.ParadeDB.EntityFrameworkCore</PackageId>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.0" />
+    </ItemGroup>
+
+</Project>
diff --git a/Equibles.ParadeDB.EntityFrameworkCore/ParadeDbConventionSetPlugin.cs b/Equibles.ParadeDB.EntityFrameworkCore/ParadeDbConventionSetPlugin.cs
@@ -0,0 +1,11 @@
+using Microsoft.EntityFrameworkCore.Metadata.Conventions;
+using Microsoft.EntityFrameworkCore.Metadata.Conventions.Infrastructure;
+
+namespace Equibles.ParadeDB.EntityFrameworkCore;
+
+public sealed class ParadeDbConventionSetPlugin : IConventionSetPlugin {
+    public ConventionSet ModifyConventions(ConventionSet conventionSet) {
+        conventionSet.ModelFinalizingConventions.Add(new ParadeDbModelFinalizingConvention());
+        return conventionSet;
+    }
+}
diff --git a/Equibles.ParadeDB.EntityFrameworkCore/ParadeDbDbContextOptionsBuilderExtensions.cs b/Equibles.ParadeDB.EntityFrameworkCore/ParadeDbDbContextOptionsBuilderExtensions.cs
@@ -0,0 +1,18 @@
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Infrastructure;
+using Npgsql.EntityFrameworkCore.PostgreSQL.Infrastructure;
+
+namespace Equibles.ParadeDB.EntityFrameworkCore;
+
+public static class ParadeDbDbContextOptionsBuilderExtensions {
+    public static NpgsqlDbContextOptionsBuilder UseParadeDb(this NpgsqlDbContextOptionsBuilder npgsqlBuilder) {
+        var builder = ((IRelationalDbContextOptionsBuilderInfrastructure)npgsqlBuilder).OptionsBuilder;
+
+        var extension = builder.Options.FindExtension<ParadeDbDbContextOptionsExtension>()
+                        ?? new ParadeDbDbContextOptionsExtension();
+
+        ((IDbContextOptionsBuilderInfrastructure)builder).AddOrUpdateExtension(extension);
+
+        return npgsqlBuilder;
+    }
+}
diff --git a/Equibles.ParadeDB.EntityFrameworkCore/ParadeDbDbContextOptionsExtension.cs b/Equibles.ParadeDB.EntityFrameworkCore/ParadeDbDbContextOptionsExtension.cs
@@ -0,0 +1,26 @@
+using Microsoft.EntityFrameworkCore.Infrastructure;
+using Microsoft.EntityFrameworkCore.Metadata.Conventions.Infrastructure;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Equibles.ParadeDB.EntityFrameworkCore;
+
+public sealed class ParadeDbDbContextOptionsExtension : IDbContextOptionsExtension {
+    public DbContextOptionsExtensionInfo Info => new ParadeDbExtensionInfo(this);
+
+    public void ApplyServices(IServiceCollection services) {
+        new EntityFrameworkRelationalServicesBuilder(services)
+            .TryAdd<IConventionSetPlugin, ParadeDbConventionSetPlugin>();
+    }
+
+    public void Validate(IDbContextOptions options) { }
+
+    private sealed class ParadeDbExtensionInfo : DbContextOptionsExtensionInfo {
+        public ParadeDbExtensionInfo(IDbContextOptionsExtension extension) : base(extension) { }
+
+        public override bool IsDatabaseProvider => false;
+        public override string LogFragment => "using ParadeDB ";
+        public override int GetServiceProviderHashCode() => 0;
+        public override bool ShouldUseSameServiceProvider(DbContextOptionsExtensionInfo other) => other is ParadeDbExtensionInfo;
+        public override void PopulateDebugInfo(IDictionary<string, string> debugInfo) => debugInfo["ParadeDB:BM25"] = "1";
+    }
+}
diff --git a/Equibles.ParadeDB.EntityFrameworkCore/ParadeDbModelFinalizingConvention.cs b/Equibles.ParadeDB.EntityFrameworkCore/ParadeDbModelFinalizingConvention.cs
@@ -0,0 +1,33 @@
+using System.Reflection;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Metadata.Builders;
+using Microsoft.EntityFrameworkCore.Metadata.Conventions;
+
+namespace Equibles.ParadeDB.EntityFrameworkCore;
+
+public sealed class ParadeDbModelFinalizingConvention : IModelFinalizingConvention {
+    public void ProcessModelFinalizing(IConventionModelBuilder modelBuilder, IConventionContext<IConventionModelBuilder> context) {
+        var hasBm25Index = false;
+
+        foreach (var entityType in modelBuilder.Metadata.GetEntityTypes()) {
+            var attribute = entityType.ClrType.GetCustomAttribute<Bm25IndexAttribute>();
+            if (attribute == null) continue;
+
+            var indexBuilder = entityType.Builder.HasIndex(attribute.Columns, fromDataAnnotation: true);
+            if (indexBuilder == null) continue;
+
+            indexBuilder.HasAnnotation("Npgsql:IndexMethod", "bm25", fromDataAnnotation: true);
+
+            // Resolve the key field to the actual column name
+            var keyProperty = entityType.FindProperty(attribute.KeyField);
+            var keyColumnName = keyProperty?.GetColumnName() ?? attribute.KeyField;
+            indexBuilder.HasAnnotation("Npgsql:StorageParameter:key_field", keyColumnName, fromDataAnnotation: true);
+
+            hasBm25Index = true;
+        }
+
+        if (hasBm25Index) {
+            modelBuilder.HasAnnotation("Npgsql:PostgresExtension:pg_search", ",,", fromDataAnnotation: true);
+        }
+    }
+}
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Equibles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,68 @@
+# Equibles.ParadeDB.EntityFrameworkCore
+
+EF Core integration for [ParadeDB](https://www.paradedb.com/) `pg_search` — BM25 full-text search indexes on PostgreSQL.
+
+Provides a `[Bm25Index]` attribute and `UseParadeDb()` extension method that automatically creates BM25 indexes via EF Core conventions and migrations. No raw SQL needed.
+
+## Requirements
+
+- PostgreSQL with the [pg_search](https://docs.paradedb.com/search/quickstart) extension installed
+- [Npgsql.EntityFrameworkCore.PostgreSQL](https://www.nuget.org/packages/Npgsql.EntityFrameworkCore.PostgreSQL) provider
+- .NET 10+
+
+## Installation
+
+```bash
+dotnet add package Equibles.ParadeDB.EntityFrameworkCore
+```
+
+## Usage
+
+### 1. Enable ParadeDB in your DbContext
+
+```csharp
+services.AddDbContext<MyDbContext>(options =>
+    options.UseNpgsql(connectionString, npgsql => npgsql.UseParadeDb()));
+```
+
+### 2. Add BM25 indexes to your entities
+
+```csharp
+using Equibles.ParadeDB.EntityFrameworkCore;
+
+[Bm25Index(nameof(Id), nameof(Title), nameof(Content))]
+public class Article
+{
+    public Guid Id { get; set; }
+    public string Title { get; set; }
+    public string Content { get; set; }
+}
+```
+
+The first parameter is the key field (primary key), followed by the columns to index for full-text search.
+
+### 3. Create a migration
+
+```bash
+dotnet ef migrations add AddBm25Index
+dotnet ef database update
+```
+
+EF Core will generate the migration automatically, creating:
+- The `pg_search` PostgreSQL extension
+- A BM25 index on the specified columns with the correct `key_field` storage parameter
+
+### How it works
+
+The library hooks into EF Core's model finalization pipeline via `IConventionSetPlugin`. During model building, it:
+
+1. Scans entity types for `[Bm25Index]` attributes
+2. Creates database indexes with the `bm25` index method
+3. Sets the `key_field` storage parameter (required by pg_search)
+4. Registers the `pg_search` PostgreSQL extension
+
+All of this is translated into standard EF Core migrations — no manual SQL required.
+
+## License
+
+MIT

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+<Solution>`
	`2`	`+ <Project Path="Equibles.ParadeDB.EntityFrameworkCore/Equibles.ParadeDB.EntityFrameworkCore.csproj" />`
	`3`	`+</Solution>`