Integration Npgsql Extension

The TestTrackingDiagrams.Extensions.Npgsql package adds PostgreSQL operation tracking to your test diagrams via Npgsql's built-in DiagnosticSource instrumentation. No code changes required in production — just install and configure in your test project.

Zero production changes. Npgsql emits diagnostic events automatically. This extension subscribes to them globally, so every NpgsqlConnection in the process is tracked without any wrapping or decoration.

---

How It Works

Npgsql publishes DiagnosticSource events under the listener name "Npgsql". The NpgsqlDiagnosticTracker subscribes to these events and correlates BeforeExecuteCommand / AfterExecuteCommand pairs using ExecutionId (a GUID extracted via reflection). Each pair is classified by UnifiedSqlClassifier and logged to RequestResponseLogger.

Because it logs to the same RequestResponseLogger as the standard TestTrackingMessageHandler, SQL operations appear alongside your HTTP API calls in the same sequence diagram.

---

Install

dotnet add package TestTrackingDiagrams.Extensions.Npgsql

---

Setup

Option A — Dependency Injection

// In your test WebApplicationFactory ConfigureTestServices:
services.AddPostgreSqlTestTracking(options =>
{
    options.Verbosity = SqlTrackingVerbosityLevel.Detailed;
    // options.LogSqlText = true;
    // options.LogParameters = true;
});

Option B — Static (No DI)

// In your test setup (e.g. constructor or OneTimeSetUp):
NpgsqlTestTracking.EnsureTracking(new NpgsqlTrackingOptions
{
    Verbosity = SqlTrackingVerbosityLevel.Detailed
});

// In teardown:
NpgsqlTestTracking.Reset();

---

Configuration

Property	Default	Description
ServiceName	"PostgreSQL"	The participant name shown in diagrams
CallingServiceName	null	The caller participant (defaults to SUT name)
Verbosity	Detailed	Raw, Detailed, or Summarised
LogSqlText	false	Include full SQL text in Detailed mode
LogParameters	false	Include parameter values
DependencyCategory	"PostgreSQL"	Controls participant shape/colour
UriScheme	"postgresql"	URI scheme in diagram URIs
ExcludedOperations	[]	Operations to exclude from tracking
TrackDuringSetup	true	Track during test setup phase
TrackDuringAction	true	Track during test action phase

All options inherit from SqlTrackingOptionsBase in the core package.

---

Verbosity Levels

Level	Arrow label	URI
Raw	Full SQL text	postgresql://host/database
Detailed	SELECT FROM Users	postgresql://host/database/Users
Summarised	SELECT	postgresql:///database/Users

---

Classified Operations

Uses UnifiedSqlClassifier — supports SELECT, INSERT, UPDATE, DELETE, MERGE, UPSERT (ON CONFLICT DO UPDATE), stored procedures (EXEC/CALL), DDL (CREATE/ALTER/DROP TABLE), TRUNCATE, and transactions. Multi-dialect: handles PostgreSQL double-quotes, brackets, backticks, CTEs, SET prefix stripping, and Spanner hints.