Extensions and Plugins

Overview

The Npgsql EF Core provider uses a plugin architecture to allow optional functionality to be added without bloating the core provider. Plugins extend the provider by:

1. Registering additional type mappings between CLR types and PostgreSQL types.
2. Adding method call and member translators for LINQ query operations.
3. Configuring the underlying Npgsql ADO.NET provider's type system via INpgsqlDataSourceConfigurationPlugin src/EFCore.PG.NodaTime/Extensions/NpgsqlNodaTimeServiceCollectionExtensions.cs25

The provider includes two major plugin packages:

• NetTopologySuite (NTS): PostGIS spatial data support.
• NodaTime: Advanced date/time handling (see page NodaTime Integration for details).

Sources:

• src/EFCore.PG/Extensions/NpgsqlServiceCollectionExtensions.cs94-114
• src/EFCore.PG.NTS/Infrastructure/Internal/NpgsqlNetTopologySuiteOptionsExtension.cs83-84
• src/EFCore.PG.NodaTime/Extensions/NpgsqlNodaTimeServiceCollectionExtensions.cs19-33

Plugin Architecture

Package Dependencies

The following diagram illustrates how plugins bridge the gap between high-level EF Core constructs and the low-level ADO.NET Npgsql driver.

Sources:

• src/EFCore.PG.NodaTime/Extensions/NpgsqlNodaTimeServiceCollectionExtensions.cs25-30
• src/EFCore.PG/Extensions/NpgsqlServiceCollectionExtensions.cs90-118

Type Mapping and Query Translation

Plugins register themselves into the internal service provider using the EntityFrameworkNpgsqlServicesBuilder src/EFCore.PG.NodaTime/Extensions/NpgsqlNodaTimeServiceCollectionExtensions.cs24-30 This allows the NpgsqlTypeMappingSource to iterate through all registered IRelationalTypeMappingSourcePlugin instances before falling back to built-in provider mappings.

Similarly, query translation is extended by implementing:

• IMethodCallTranslatorPlugin: For translating LINQ methods (e.g., NodaTime specific methods) src/EFCore.PG.NodaTime/Extensions/NpgsqlNodaTimeServiceCollectionExtensions.cs27
• IMemberTranslatorPlugin: For translating property access (e.g., Instant.InZone) src/EFCore.PG.NodaTime/Extensions/NpgsqlNodaTimeServiceCollectionExtensions.cs29
• IEvaluatableExpressionFilterPlugin: To prevent EF Core from evaluating certain expressions locally on the client when they should be translated to SQL src/EFCore.PG.NodaTime/Query/Internal/NpgsqlNodaTimeEvaluatableExpressionFilterPlugin.cs9-47

Local Evaluation Prevention

The NpgsqlEvaluatableExpressionFilter src/EFCore.PG/Query/Internal/NpgsqlEvaluatableExpressionFilter.cs12-74 handles core provider logic (like preventing local evaluation of Full Text Search functions), while plugins like NpgsqlNodaTimeEvaluatableExpressionFilterPlugin src/EFCore.PG.NodaTime/Query/Internal/NpgsqlNodaTimeEvaluatableExpressionFilterPlugin.cs17-46 ensure that expressions like SystemClock.Instance.GetCurrentInstant() are sent to the database (e.g., as NOW()) rather than being evaluated once at the client.

Sources:

• src/EFCore.PG/Query/Internal/NpgsqlEvaluatableExpressionFilter.cs41-61
• src/EFCore.PG.NodaTime/Query/Internal/NpgsqlNodaTimeEvaluatableExpressionFilterPlugin.cs17-46
• src/EFCore.PG.NodaTime/Extensions/NpgsqlNodaTimeServiceCollectionExtensions.cs24-31

NetTopologySuite Plugin

The NetTopologySuite plugin adds PostGIS spatial support.

Integration Mechanism

The plugin is enabled via NpgsqlNetTopologySuiteOptionsExtension src/EFCore.PG.NTS/Infrastructure/Internal/NpgsqlNetTopologySuiteOptionsExtension.cs13-55 It configures the service collection to include NTS-specific mapping and translation logic src/EFCore.PG.NTS/Infrastructure/Internal/NpgsqlNetTopologySuiteOptionsExtension.cs83-84

Key Features

• Coordinate Systems: Support for CoordinateSequenceFactory and PrecisionModel src/EFCore.PG.NTS/Infrastructure/Internal/NpgsqlNetTopologySuiteOptionsExtension.cs23-31
• Geography vs Geometry: Support for toggling whether types default to geography or geometry src/EFCore.PG.NTS/Infrastructure/Internal/NpgsqlNetTopologySuiteOptionsExtension.cs47
• Design-time Support: Provides NpgsqlNetTopologySuiteDesignTimeServices for scaffolding spatial columns from an existing database.

Sources:

• src/EFCore.PG.NTS/Infrastructure/Internal/NpgsqlNetTopologySuiteOptionsExtension.cs13-110

NodaTime Integration

The NodaTime plugin provides superior date/time handling. For a full breakdown of type mappings and time zone behavior, see the child page.

Package: Npgsql.EntityFrameworkCore.PostgreSQL.NodaTime

Key features:

• Service Registration: Uses AddEntityFrameworkNpgsqlNodaTime to register translators and mapping plugins src/EFCore.PG.NodaTime/Extensions/NpgsqlNodaTimeServiceCollectionExtensions.cs19-33
• Validation: Ensures that the internal service provider is correctly configured when UseNodaTime() is called src/EFCore.PG.NodaTime/Infrastructure/Internal/NpgsqlNodaTimeOptionsExtension.cs40-56
• SQL Translation: Translates SystemClock and DateTimeZoneProviders members into PostgreSQL-compatible SQL src/EFCore.PG.NodaTime/Query/Internal/NpgsqlNodaTimeEvaluatableExpressionFilterPlugin.cs21-43

For details, see NodaTime Integration.

Sources:

• src/EFCore.PG.NodaTime/Extensions/NpgsqlNodaTimeServiceCollectionExtensions.cs12-34
• src/EFCore.PG.NodaTime/Infrastructure/Internal/NpgsqlNodaTimeOptionsExtension.cs12-78

Using Plugins

Plugins are typically configured during the OnConfiguring stage or in AddDbContext.

Dependency Injection

When using AddNpgsql<TContext>, the provider handles the registration of core services src/EFCore.PG/Extensions/NpgsqlServiceCollectionExtensions.cs52-67 Plugins then hook into this collection via their respective Use... methods, which call ApplyServices on the option extensions src/EFCore.PG.NodaTime/Infrastructure/Internal/NpgsqlNodaTimeOptionsExtension.cs22-23

Sources:

• src/EFCore.PG/Extensions/NpgsqlServiceCollectionExtensions.cs52-67
• src/EFCore.PG.NodaTime/Infrastructure/Internal/NpgsqlNodaTimeOptionsExtension.cs22-23
• src/EFCore.PG.NTS/Infrastructure/Internal/NpgsqlNetTopologySuiteOptionsExtension.cs83-84