Building and Testing

This page documents the build infrastructure, continuous integration pipeline, dependency management, and testing procedures for the Npgsql EF Core provider. It covers how to build the project locally, run tests against different PostgreSQL versions, and how the automated CI/CD pipeline operates.

Overview

The Npgsql EF Core provider uses a modern .NET build system with centralized package management, GitHub Actions for CI/CD, and a comprehensive test matrix covering multiple PostgreSQL versions and operating systems. The build system is configured to target .NET 11 preview releases and locks to specific EF Core versions to ensure provider-facing API compatibility.

Sources: .github/workflows/build.yml1-186 Directory.Build.props1-58

Build System Configuration

SDK and Target Framework

The project requires the .NET 11 SDK as specified in global.json1-7 The SDK version is locked to a specific preview build to ensure consistent compilation across environments:

All projects target net11.0 as defined in Directory.Build.props4 The build configuration includes:

Property	Value	Purpose
LangVersion	latest	Use latest C# language features
Nullable	enable	Enable nullable reference types
TreatWarningsAsErrors	true	Enforce zero-warning policy
SignAssembly	true	Strong-name assemblies
ImplicitUsings	true	Enable implicit global usings
GenerateDocumentationFile	true	Generate XML documentation

Sources: Directory.Build.props1-58 global.json1-7

Dependency Management

The project uses Central Package Management (CPM) as indicated by ManagePackageVersionsCentrally in Directory.Build.props12 All package versions are centralized in Directory.Packages.props1-40

Key Dependencies

EF Core Version Locking: Dependencies on EF Core preview versions are locked to exact versions using the syntax Version="[$(EFCoreVersion)]" as seen in Directory.Packages.props14-18 This prevents automatic updates which could introduce breaking changes. For released versions, the provider would depend on any patch version within the same major version.

Sources: Directory.Packages.props1-40

Package Source Configuration

The project uses multiple NuGet feeds configured in NuGet.config1-26:

Feed	Purpose
dotnet11	Preview builds of .NET 11 and EF Core
dotnet-eng	Engineering infrastructure packages
npgsql-vnext	Preview builds of Npgsql packages
nuget.org	Stable and stable-preview packages

Package source mapping ensures that packages come from the correct feed. For example, Npgsql packages can come from either nuget.org or npgsql-vnext, with the vnext feed taking precedence for preview builds NuGet.config17-20

Sources: NuGet.config1-26

CI/CD Pipeline

GitHub Actions Workflow

The build pipeline is defined in .github/workflows/build.yml1-186 and triggers on:

• Pushes to main, hotfix/**, and release/** branches
• All tags starting with v
• Pull requests to any branch

Sources: .github/workflows/build.yml1-186

Test Matrix

The pipeline uses a matrix strategy to test across multiple configurations .github/workflows/build.yml25-37:

Operating System	PostgreSQL Versions	Configuration	PostGIS
Ubuntu 24.04	18, 17, 16, 15, 14, 13	Release	✓
Windows 2022	17	Release	✗
Ubuntu 24.04	18	Debug	✓

PostGIS testing is disabled on Windows because installation is complicated/unreliable. The environment variable NPGSQL_TEST_POSTGIS is set to control whether PostGIS tests fail the build if PostGIS is unavailable .github/workflows/build.yml47-51

Sources: .github/workflows/build.yml18-51

PostgreSQL Installation

Linux Installation

On Ubuntu, the workflow:

1. Uninstalls any existing PostgreSQL installations .github/workflows/build.yml67-68
2. Installs the official PostgreSQL APT repository .github/workflows/build.yml71-72
3. Installs the specified PostgreSQL version .github/workflows/build.yml74
4. Installs PostGIS extension .github/workflows/build.yml78
5. Configures max_connections = 200 .github/workflows/build.yml81
6. Creates test user npgsql_tests with superuser privileges .github/workflows/build.yml83

Sources: .github/workflows/build.yml64-84

Windows Installation

On Windows, the workflow:

1. Queries the PostgreSQL website to find the latest EnterpriseDB binary version .github/workflows/build.yml88-95
2. Downloads and extracts the portable PostgreSQL binaries .github/workflows/build.yml98-100
3. Copies SSL certificates from .build/ directory .github/workflows/build.yml103
4. Initializes a new database cluster with UTF-8 encoding .github/workflows/build.yml106
5. Starts PostgreSQL with custom configuration including SSL support .github/workflows/build.yml107
6. Creates test user and database .github/workflows/build.yml110-111

The Windows configuration enables SSL with certificates and sets max_connections=200 and max_prepared_transactions=10 .github/workflows/build.yml107

Sources: .github/workflows/build.yml85-112

Test Execution

Tests are executed using the command:

The GitHubActionsTestLogger package Directory.Packages.props35 formats test output for GitHub Actions. The report-warnings=false flag prevents warnings from cluttering the workflow summary .github/workflows/build.yml115 The environment variable Test__Npgsql__DefaultConnection is set to point to the local test instance .github/workflows/build.yml119

Sources: .github/workflows/build.yml114-120 Directory.Packages.props35

Package Publishing

CI Package Publishing

For commits to development branches, the pipeline creates CI packages. The version suffix format is ci.$(date -u +%Y%m%dT%H%M%S)+sha.${GITHUB_SHA:0:9} .github/workflows/build.yml148

The -p:ContinuousIntegrationBuild=true flag enables deterministic builds and embeds proper source link information .github/workflows/build.yml148

Sources: .github/workflows/build.yml134-165

Release Package Publishing

When a version tag (e.g., v11.0.0) is pushed:

1. The build job sets outputs is_release=true and optionally is_prerelease=true .github/workflows/build.yml121-132
2. The release job runs only if is_release is true .github/workflows/build.yml169
3. Packages are built without version suffix .github/workflows/build.yml182
4. Packages are published to nuget.org .github/workflows/build.yml166-186

Sources: .github/workflows/build.yml121-132 .github/workflows/build.yml166-186

Building Locally

Prerequisites

1. Install .NET 11 SDK version 11.0.100-preview.4.26210.111 or compatible global.json3
2. Install PostgreSQL (supported versions 13-18) .github/workflows/build.yml29
3. Configure PostgreSQL with a test user:

Sources: global.json1-7 .github/workflows/build.yml110-111

Build Commands

Build the entire solution in Debug mode:

Sources: .github/workflows/build.yml61

Running Tests Locally

Running All Tests

Execute all tests against the default PostgreSQL instance:

Sources: .github/workflows/build.yml115

Test Infrastructure Classes

The codebase provides specialized helpers for testing the Npgsql provider.

NpgsqlTestStore

This class manages the lifecycle of a PostgreSQL database for functional tests test/EFCore.PG.FunctionalTests/TestUtilities/NpgsqlTestStore.cs8 It handles:

• Connection Management: Creates NpgsqlConnection with specific test strings test/EFCore.PG.FunctionalTests/TestUtilities/NpgsqlTestStore.cs58-59
• Database Lifecycle: Implements CreateDatabaseAsync which uses an admin connection to create the test database test/EFCore.PG.FunctionalTests/TestUtilities/NpgsqlTestStore.cs119-141
• Provider Configuration: Configures NpgsqlDbContextOptionsBuilder with standard test settings like ReverseNullOrdering() to match EF Core's expected NULL behavior test/EFCore.PG.FunctionalTests/TestUtilities/NpgsqlTestStore.cs106-117

NpgsqlTestHelpers

Provides a singleton instance to register Npgsql-specific services into the EF Core service provider test/EFCore.PG.FunctionalTests/TestUtilities/NpgsqlTestHelpers.cs5-18

Sources: test/EFCore.PG.FunctionalTests/TestUtilities/NpgsqlTestStore.cs1-193 test/EFCore.PG.FunctionalTests/TestUtilities/NpgsqlTestHelpers.cs1-18

Automated Maintenance

The repository includes "Agentic Workflows" for automated maintenance, specifically for keeping the provider in sync with the latest EF Core daily builds.

Workflow	Purpose
Sync To Latest Ef	Periodically updates the EFCoreVersion in Directory.Packages.props to reference the latest EF daily build and runs tests .github/workflows/sync-to-latest-ef.lock.yml24-44
Agentic Maintenance	Manages expired entities like issues or pull requests generated by automated agents .github/workflows/agentics-maintenance.yml33-101

Sources: .github/workflows/sync-to-latest-ef.lock.yml1-165 .github/workflows/agentics-maintenance.yml1-182