Pglite.EntityFrameworkCore 0.1.0

Pglite.EntityFrameworkCore

Run PGlite — PostgreSQL 18.3 compiled to run as a single in-process, embedded engine — inside a .NET process, and use it through Entity Framework Core. No JavaScript, no Node, no wasm runtime.

Where PGlite's upstream distribution drives the engine from JavaScript (an Emscripten runtime host in the browser/Node), this project drives the same PostgreSQL backend directly from C# by compiling it to a native shared library (libpglite) and calling it via P/Invoke. PGlite's query I/O already flows through two runtime-settable C function pointers (pgl_set_rw_cbs) that carry the standard PostgreSQL wire protocol — so C# [UnmanagedCallersOnly] callbacks replace the JS callbacks 1:1.

How it works

DbContext (UsePglite)
      │  UseNpgsql(NpgsqlDataSource)
      ▼
   Npgsql  ──opens real socket──►  loopback 127.0.0.1:<ephemeral>
      ▲  wire-protocol bytes                 │  (PgliteListener)
      │                                      ▼
      └───────── response bytes ◄──── PgliteBridge (byte pump)
                                             │
                                             ▼
                                       PgliteEngine  (SemaphoreSlim-serialized)
                                             │  P/Invoke + rw callbacks
                                             ▼
                                       libpglite (native .so/.dll/.dylib)

Because Npgsql exposes no public "bring-your-own-transport" seam, the engine is fronted by an in-process loopback socket that the mature Npgsql driver and Npgsql.EntityFrameworkCore.PostgreSQL provider connect to unmodified. That inherits migrations, LINQ translation, and type mapping for free — PGlite is PostgreSQL 18.3, speaking the identical wire protocol.

Install

dotnet add package Pglite.EntityFrameworkCore

This pulls the whole chain (Pglite.Runtime, Pglite.Native). The package bundles a prebuilt native libpglite for every supported RID (linux-x64, linux-arm64, win-x64); NuGet's runtimes/<rid> fallback selects the right one for your platform at publish/run time — no recompile, no PostgreSQL toolchain, no initdb. Not on EF Core? Reference Pglite.Runtime for raw Npgsql access.

Usage notes

Migrations (dotnet ef)

dotnet ef migrations add / database update work against UsePglite(...), inheriting the Npgsql EF provider's migration support. Because dotnet ef boots your DbContext in a separate design-time process, provide an IDesignTimeDbContextFactory<T> that constructs UsePglite(...) so the tool doesn't have to start your app host. A complete, runnable example is in samples/Pglite.Sample.Migrations.

The embedded engine is single-process: only one process may open a given on-disk data directory at a time (PostgreSQL likewise refuses two backends on one cluster). If a running app and a dotnet ef command both point at the same PgliteDataDirectory, the second one fails fast with a clear PgliteException rather than corrupting the cluster. Stop the app before running design-time commands, or point them at a separate data directory.

Single-connection constraint

The backend serves one connection at a time (the Npgsql data source is capped at MaxPoolSize=1). Using connections/contexts sequentially is fine — pooling reuses the one physical connection. But opening a second connection while another is still in use (nested DbContexts, a second context opened inside an active query, or genuinely concurrent queries on one flow) cannot be served. Instead of hanging on an opaque pool timeout, it throws a PgliteException with actionable guidance after a short, configurable wait (PgliteOptions.ConnectionTimeoutSeconds, default 5). Await each operation to completion before starting the next.

Large result sets stream

Query responses are streamed to the socket as the backend produces them rather than buffered whole in managed memory, so a large result (e.g. SELECT * FROM generate_series(1, 1_000_000)) completes with bounded memory.

Projects

Versioning & releases

This project follows Semantic Versioning; all three packages are versioned and released together from a single git tag. See docs/versioning.md for the SemVer policy and docs/releasing.md for how releases are cut and published to nuget.org.

Status

Early scaffolding. See docs/PLAN.md for the staged implementation plan and current progress.

License

Apache-2.0. Bundles PostgreSQL (PostgreSQL License) via the postgres-pglite fork.