From 53ca097e4c29ddf39bfeb2c65f8a94288443225d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Sat, 13 Jun 2026 13:11:23 +0200
Subject: [PATCH 01/25] =?UTF-8?q?fix(docker):=20JIT=20image=20=E2=80=94=20?=
 =?UTF-8?q?copy=20NpgsqlRest.Common=20shared=20source;=20CI:=20stop=20publ?=
 =?UTF-8?q?ishing=20on=20PRs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The JIT Docker build (docker/Dockerfile.jit) compiles from source inside the
container, and NpgsqlRest.csproj now compiles + global-uses the shared source
in NpgsqlRest.Common/ (<Compile Include="..\NpgsqlRest.Common\*.cs"/>). That
folder was never copied into the build context, so the publish failed with
CS0234 'NpgsqlRest.Common'. Added the COPY; validated by building the image
locally. (The other Docker variants copy a prebuilt binary, so they were fine.)

CI: removed the pull_request trigger so the publish/release pipeline no longer
runs on every PR (dependabot PRs were flooding Actions with failing publish runs
— PRs can't publish anyway, no secrets).

TEMP (this commit only): build-test-publish is if:false and build-docker-jit is
detached from create-release, so this push runs ONLY build-docker-jit to push
the missing v3.17.0-jit / latest-jit image. To be reverted once green.
---
 .github/workflows/build-test-publish.yml | 8 +++++---
 docker/Dockerfile.jit                    | 3 +++
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/build-test-publish.yml b/.github/workflows/build-test-publish.yml
index 3e5b8e75..fb10a49c 100644
--- a/.github/workflows/build-test-publish.yml
+++ b/.github/workflows/build-test-publish.yml
@@ -3,8 +3,6 @@ name: Build, Test, Publish and Release
 on:
   push:
     branches: [ master ]
-  pull_request:
-    branches: [ master ]
   workflow_dispatch:
 
 # Add workflow-level permissions
@@ -14,6 +12,9 @@ permissions:
 
 jobs:
   build-test-publish:
+    # TEMP (jit-only republish of v3.17.0): disabled so the whole release chain is skipped — 3.17.0 is
+    # already published, we only need the missing -jit Docker image. RESTORE: delete this `if: false`.
+    if: false
     runs-on: ubuntu-22.04
     services:
       postgres:
@@ -275,7 +276,8 @@ jobs:
           vbilopav/npgsqlrest:latest-aot
 
   build-docker-jit:
-    needs: create-release
+    # TEMP (jit-only republish): `needs: create-release` removed so this runs standalone while the rest of
+    # the chain is disabled. It reads the version from version.txt itself. RESTORE: re-add `needs: create-release`.
     runs-on: ubuntu-22.04
     permissions:
       contents: read
diff --git a/docker/Dockerfile.jit b/docker/Dockerfile.jit
index f5c86336..5b0ce475 100644
--- a/docker/Dockerfile.jit
+++ b/docker/Dockerfile.jit
@@ -21,6 +21,9 @@ RUN dotnet restore NpgsqlRestClient/NpgsqlRestClient.csproj
 COPY LICENSE LICENSE
 COPY README.md README.MD
 COPY NpgsqlRest/ NpgsqlRest/
+# Shared source compiled into NpgsqlRest.csproj (<Compile Include="..\NpgsqlRest.Common\*.cs"/> + global
+# usings). Without this the JIT build fails: NpgsqlRest.GlobalUsings.g.cs -> CS0234 'NpgsqlRest.Common'.
+COPY NpgsqlRest.Common/ NpgsqlRest.Common/
 COPY NpgsqlRestClient/*.cs NpgsqlRestClient/
 COPY NpgsqlRestClient/*.csproj NpgsqlRestClient/
 COPY NpgsqlRestClient/appsettings.json NpgsqlRestClient/

From 1f6e4074620f85bcec8a073c8683ddfec2e7d78e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Sat, 13 Jun 2026 13:12:25 +0200
Subject: [PATCH 02/25] docs(changelog): mark v3.17.0 released (2026-06-13);
 CI: restore full release workflow

Re-enables the full release chain (build-test-publish no longer if:false;
build-docker-jit needs create-release again) now that the v3.17.0-jit image is
published. The pull_request trigger stays removed, so the publish/release
pipeline runs only on push to master + manual dispatch (no PR/dependabot noise).
---
 .github/workflows/build-test-publish.yml | 6 +-----
 changelog/v3.17.0.md                     | 2 +-
 2 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/build-test-publish.yml b/.github/workflows/build-test-publish.yml
index fb10a49c..e9d337b2 100644
--- a/.github/workflows/build-test-publish.yml
+++ b/.github/workflows/build-test-publish.yml
@@ -12,9 +12,6 @@ permissions:
 
 jobs:
   build-test-publish:
-    # TEMP (jit-only republish of v3.17.0): disabled so the whole release chain is skipped — 3.17.0 is
-    # already published, we only need the missing -jit Docker image. RESTORE: delete this `if: false`.
-    if: false
     runs-on: ubuntu-22.04
     services:
       postgres:
@@ -276,8 +273,7 @@ jobs:
           vbilopav/npgsqlrest:latest-aot
 
   build-docker-jit:
-    # TEMP (jit-only republish): `needs: create-release` removed so this runs standalone while the rest of
-    # the chain is disabled. It reads the version from version.txt itself. RESTORE: re-add `needs: create-release`.
+    needs: create-release
     runs-on: ubuntu-22.04
     permissions:
       contents: read
diff --git a/changelog/v3.17.0.md b/changelog/v3.17.0.md
index f5b52704..4ee8ac7d 100644
--- a/changelog/v3.17.0.md
+++ b/changelog/v3.17.0.md
@@ -1,6 +1,6 @@
 # Changelog v3.17.0
 
-## Version [3.17.0](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.17.0) (unreleased)
+## Version [3.17.0](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.17.0) (2026-06-13)
 
 [Full Changelog](https://github.com/NpgsqlRest/NpgsqlRest/compare/3.16.3...3.17.0)
 

From bf78434dc6c95436d34f710d11851ae36e164d0a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Tue, 23 Jun 2026 11:47:02 +0200
Subject: [PATCH 03/25] fix(http-types): fire one outbound call per distinct
 HTTP type (v3.17.1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A DB-function composite parameter is expanded into one parameter per
field, each carrying the same TypeDescriptor.CustomType. The per-request
list of HTTP types therefore held the type name once per field, and
InvokeAllAsync fired InvokeAsync once per entry — making N identical
outbound calls (N = field count) while the fill loop resolved handlers
by distinct type name. SQL-file endpoints kept the type as a single
composite parameter and were unaffected.

Guard the firing loop to request each distinct HTTP type once, reusing
the dictionary the fill loop already keys on. Preserves the established
one-call-per-distinct-type contract.

Adds two regression tests that count actual outbound calls via a
WireMock callback: a 6-field type fires exactly 1 call (was 6), and two
distinct types fire 1 call each. Verified failing pre-fix (found 6).

See changelog/v3.17.1.md.
---
 .../HttpClientType/HttpClientTypeHandler.cs   |  8 +++
 .../HttpClientTypeTests.cs                    | 72 +++++++++++++++++++
 changelog/v3.17.1.md                          | 45 ++++++++++++
 npm/package.json                              |  2 +-
 version.txt                                   |  2 +-
 5 files changed, 127 insertions(+), 2 deletions(-)
 create mode 100644 changelog/v3.17.1.md

diff --git a/NpgsqlRest/HttpClientType/HttpClientTypeHandler.cs b/NpgsqlRest/HttpClientType/HttpClientTypeHandler.cs
index 41a126c1..96add620 100644
--- a/NpgsqlRest/HttpClientType/HttpClientTypeHandler.cs
+++ b/NpgsqlRest/HttpClientType/HttpClientTypeHandler.cs
@@ -284,6 +284,14 @@ public static async Task InvokeAllAsync(
 
         foreach (var typeName in typeNames)
         {
+            // A DB-function composite parameter is expanded into one parameter per field,
+            // each carrying the same CustomType, so typeNames can contain the same type
+            // multiple times. Fire exactly one outbound call per distinct HTTP type - the
+            // fill loop below resolves handlers by distinct type name as well.
+            if (handlers.ContainsKey(typeName))
+            {
+                continue;
+            }
             if (HttpClientTypes.Definitions.TryGetValue(typeName, out var definition))
             {
                 var handler = new HttpClientTypeHandler(definition, replacements);
diff --git a/NpgsqlRestTests/HttpClientTypeTests/HttpClientTypeTests.cs b/NpgsqlRestTests/HttpClientTypeTests/HttpClientTypeTests.cs
index d4e6bfad..9cd232b7 100644
--- a/NpgsqlRestTests/HttpClientTypeTests/HttpClientTypeTests.cs
+++ b/NpgsqlRestTests/HttpClientTypeTests/HttpClientTypeTests.cs
@@ -2,6 +2,9 @@
 using WireMock.RequestBuilders;
 using WireMock.ResponseBuilders;
 using WireMock.Settings;
+using WireMock;
+using WireMock.Types;
+using WireMock.Util;
 
 namespace NpgsqlRestTests;
 
@@ -879,4 +882,73 @@ public async Task Test_get_http_api_multi_types_one_fails()
         content.Should().Contain("\"users_status\" : 200");
         content.Should().Contain("\"products_status\" : 500");
     }
+
+    // Regression: a DB-function composite parameter is expanded into one parameter per field,
+    // each carrying the same HTTP CustomType. Before the InvokeAllAsync dedup guard, the request
+    // fired once per field (6 outbound calls for the 6-field all-fields type). It must fire exactly
+    // once per distinct HTTP type. Counter-based to count actual outbound calls (same pattern as
+    // the retry tests).
+    [Fact]
+    public async Task Test_multi_field_type_fires_exactly_one_outbound_call()
+    {
+        int calls = 0;
+        _server
+            .Given(Request.Create().WithPath("/api/all-fields").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                Interlocked.Increment(ref calls);
+                return new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = "response body", DetectedBodyType = BodyType.String }
+                };
+            }));
+
+        using var response = await _test.Client.GetAsync("/api/get-http-api-all-fields/");
+        var content = await response.Content.ReadAsStringAsync();
+
+        response?.StatusCode.Should().Be(HttpStatusCode.OK);
+        content.Should().Contain("\"body\" : \"response body\"");
+        calls.Should().Be(1);
+    }
+
+    // Regression: two distinct HTTP types referenced by a single function must each fire exactly
+    // once - one outbound call per distinct type, not per expanded field.
+    [Fact]
+    public async Task Test_multi_types_each_fire_exactly_one_outbound_call()
+    {
+        int usersCalls = 0;
+        int productsCalls = 0;
+        _server
+            .Given(Request.Create().WithPath("/api/users").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                Interlocked.Increment(ref usersCalls);
+                return new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = "[{\"id\": 1}]", DetectedBodyType = BodyType.String }
+                };
+            }));
+        _server
+            .Given(Request.Create().WithPath("/api/products").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                Interlocked.Increment(ref productsCalls);
+                return new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = "[{\"id\": 101}]", DetectedBodyType = BodyType.String }
+                };
+            }));
+
+        using var response = await _test.Client.GetAsync("/api/get-http-api-multi-types/");
+        var content = await response.Content.ReadAsStringAsync();
+
+        response?.StatusCode.Should().Be(HttpStatusCode.OK);
+        content.Should().Contain("\"users_status\" : 200");
+        content.Should().Contain("\"products_status\" : 200");
+        usersCalls.Should().Be(1);
+        productsCalls.Should().Be(1);
+    }
 }
diff --git a/changelog/v3.17.1.md b/changelog/v3.17.1.md
new file mode 100644
index 00000000..3d659752
--- /dev/null
+++ b/changelog/v3.17.1.md
@@ -0,0 +1,45 @@
+# Changelog v3.17.1
+
+## Version [3.17.1](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.17.1)
+
+[Full Changelog](https://github.com/NpgsqlRest/NpgsqlRest/compare/3.17.0...3.17.1)
+
+Patch release that fixes **duplicate outbound HTTP calls for HTTP Custom Types on database-function endpoints**.
+
+## The bug
+
+An endpoint backed by a **database function/procedure** whose parameter is an HTTP Custom Type fired **one outbound HTTP call per field of the type** on every inbound request. A 4-field type made 4 identical calls; a 6-field type made 6 — multiplying latency and load on the target service. SQL-file endpoints were not affected.
+
+## Cause
+
+A composite function parameter is expanded into one parameter **per field**, and each of those expanded parameters carries the same `TypeDescriptor.CustomType` (the HTTP type name). The type name was therefore collected once per field, so the per-request list of HTTP types to invoke contained the same name N times. The firing loop in `HttpClientTypeHandler.InvokeAllAsync` then called `InvokeAsync` once per entry, with no dedup — while the fill loop immediately below resolves handlers by **distinct** type name out of a dictionary. The design already assumes exactly one call per distinct type; the firing loop just failed to match, so the extra calls were made and their handlers discarded.
+
+SQL-file endpoints keep the HTTP type as a single composite parameter (`CustomTypeName` null), so the name was collected once → exactly one call, which is why they were unaffected.
+
+## What changed
+
+A one-line guard in `HttpClientTypeHandler.InvokeAllAsync` makes the firing loop request each distinct HTTP type once:
+
+```csharp
+foreach (var typeName in typeNames)
+{
+    if (handlers.ContainsKey(typeName)) continue; // fire once per distinct type
+    if (HttpClientTypes.Definitions.TryGetValue(typeName, out var definition))
+    {
+        var handler = new HttpClientTypeHandler(definition, replacements);
+        handlers[typeName] = handler;
+        tasks.Add((typeName, handler, handler.InvokeAsync(cancellationToken)));
+    }
+}
+```
+
+This is the single choke point for firing outbound calls and reuses the same dictionary the fill loop already keys on, so it is robust regardless of how the parameter list is built. The established contract is preserved: one call per **distinct** HTTP type, shared from one response — two parameters referencing the same type still share a single call, and two different types remain two separate calls.
+
+## Tests
+
+Two regression tests added (`NpgsqlRestTests/HttpClientTypeTests/HttpClientTypeTests.cs`) that count **actual** outbound calls via a WireMock response callback (the prior suite asserted response content but never call counts):
+
+- A 6-field HTTP type fires **exactly one** outbound call (was 6 before the fix).
+- Two distinct HTTP types in one function each fire **exactly one** call.
+
+Verified against the pre-fix code: the multi-field test failed with `Expected calls to be 1, but found 6`, reproducing the reported behavior. All 46 HTTP-client-type tests pass with the fix.
diff --git a/npm/package.json b/npm/package.json
index 484cd0f8..859024b3 100644
--- a/npm/package.json
+++ b/npm/package.json
@@ -1,6 +1,6 @@
 {
   "name": "npgsqlrest",
-  "version": "3.17.0",
+  "version": "3.17.1",
   "description": "Automatic REST API for PostgreSQL Databases Client Build",
   "scripts": {
     "postinstall": "node postinstall.js",
diff --git a/version.txt b/version.txt
index f85bf6e3..0caba260 100644
--- a/version.txt
+++ b/version.txt
@@ -1 +1 @@
-3.17.0
\ No newline at end of file
+3.17.1
\ No newline at end of file

From 9f67d878a885fb1a4731f57b040efbd545bf1b6b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Tue, 23 Jun 2026 12:27:35 +0200
Subject: [PATCH 04/25] feat(http-types): response caching via @cache; parse
 directives after headers (v3.18.0)

Add opt-in HTTP Custom Type response caching with a @cache <interval>
type-comment directive (alongside @timeout/@retry_delay):

- GET-only (warn + ignore on non-GET); success-only storage so a
  transient upstream failure is never pinned for the TTL.
- New HttpResponseCache: in-memory store with Lazy<Task> stampede
  coalescing (one outbound call per key), max-entries cap, prune timer.
- Cache key = method + resolved URL + content-type + headers + body.
- HttpClientOptions.CacheEnabled (global kill switch), MaxCacheEntries,
  CachePruneIntervalSeconds; full config round-trip wired (Builder,
  appsettings.json, ConfigTemplate, ConfigDefaults, ConfigSchemaGenerator).

Also fix: @timeout/@retry_delay/@cache are now parsed both before the
request line AND after the headers. Previously only the leading position
was recognized, so a directive after the headers (as the docs showed)
was silently ignored. Real headers (e.g. Cache-Control) are unaffected.

Folds in the v3.17.1 duplicate-outbound-call fix: version.txt and
npm/package.json bumped to 3.18.0, changelog renamed v3.17.1 -> v3.18.0
covering both the feature and the fix.

Tests: parse-level @cache forms + both-placement directive tests;
integration tests for cache hit, 6-field dedup+cache, error-not-cached,
POST-ignored, TTL expiry. Full suite green (2284).
---
 .../HttpClientType/HttpClientTypeHandler.cs   |  72 ++++-
 NpgsqlRest/HttpClientType/HttpClientTypes.cs  | 126 +++++++-
 .../HttpClientType/HttpResponseCache.cs       | 160 ++++++++++
 .../HttpClientType/HttpTypeDefinition.cs      |  13 +
 NpgsqlRest/NpgsqlRestBuilder.cs               |   9 +
 NpgsqlRest/Options/HttpClientOptions.cs       |  20 ++
 NpgsqlRestClient/Builder.cs                   |   5 +-
 NpgsqlRestClient/ConfigDefaults.cs            |   5 +-
 NpgsqlRestClient/ConfigSchemaGenerator.cs     |   3 +
 NpgsqlRestClient/ConfigTemplate.cs            |  17 +-
 NpgsqlRestClient/appsettings.json             |  17 +-
 .../HttpClientTypeCacheTests.cs               | 289 ++++++++++++++++++
 .../ParseHttpTypeDefinitionTests.cs           | 144 +++++++++
 changelog/v3.17.1.md                          |  45 ---
 changelog/v3.18.0.md                          |  53 ++++
 npm/package.json                              |   2 +-
 version.txt                                   |   2 +-
 17 files changed, 929 insertions(+), 53 deletions(-)
 create mode 100644 NpgsqlRest/HttpClientType/HttpResponseCache.cs
 create mode 100644 NpgsqlRestTests/HttpClientTypeTests/HttpClientTypeCacheTests.cs
 delete mode 100644 changelog/v3.17.1.md
 create mode 100644 changelog/v3.18.0.md

diff --git a/NpgsqlRest/HttpClientType/HttpClientTypeHandler.cs b/NpgsqlRest/HttpClientType/HttpClientTypeHandler.cs
index 96add620..76e6127b 100644
--- a/NpgsqlRest/HttpClientType/HttpClientTypeHandler.cs
+++ b/NpgsqlRest/HttpClientType/HttpClientTypeHandler.cs
@@ -160,6 +160,76 @@ public async Task InvokeAsync(CancellationToken cancellationToken = default)
         }
     }
 
+    /// <summary>
+    /// Runs the outbound call, routing it through <see cref="HttpResponseCache"/> when the type opts in
+    /// via <c>@cache</c> and caching is enabled globally. On a cache hit (or a coalesced concurrent call)
+    /// the cached response is applied to this handler so the fill loop reads it exactly as a live response.
+    /// </summary>
+    public async Task InvokeWithCacheAsync(CancellationToken cancellationToken = default)
+    {
+        if (!Options.HttpClientOptions.CacheEnabled || !definition.CacheEnabled)
+        {
+            await InvokeAsync(cancellationToken);
+            return;
+        }
+
+        var key = ComputeCacheKey();
+        var cached = await HttpResponseCache.GetOrCreateAsync(
+            key,
+            definition.CacheDuration,
+            async ct =>
+            {
+                await InvokeAsync(ct);
+                return SnapshotResponse();
+            },
+            cancellationToken);
+
+        ApplyResponse(cached);
+    }
+
+    /// <summary>
+    /// Cache key for this request: method + resolved URL + resolved content-type + resolved headers
+    /// (sorted) + resolved body. Placeholders are resolved so per-request values vary the key; a type
+    /// with no placeholders produces a constant key (one shared cached response).
+    /// </summary>
+    private string ComputeCacheKey()
+    {
+        var sb = new StringBuilder();
+        sb.Append(definition.Method).Append('\n');
+        sb.Append(ResolveValue(definition.Url)).Append('\n');
+        if (definition.ContentType is not null)
+        {
+            sb.Append(ResolveValue(definition.ContentType));
+        }
+        sb.Append('\n');
+        if (definition.Headers is { Count: > 0 })
+        {
+            foreach (var header in definition.Headers.OrderBy(h => h.Key, StringComparer.Ordinal))
+            {
+                sb.Append(header.Key).Append(':').Append(ResolveValue(header.Value)).Append('\n');
+            }
+        }
+        sb.Append('\n');
+        if (definition.Body is not null)
+        {
+            sb.Append(ResolveValue(definition.Body));
+        }
+        return sb.ToString();
+    }
+
+    private CachedHttpResponse SnapshotResponse() =>
+        new(StatusCode, Body, ResponseHeaders, ContentType, IsSuccess, ErrorMessage);
+
+    private void ApplyResponse(CachedHttpResponse r)
+    {
+        StatusCode = r.StatusCode;
+        Body = r.Body;
+        ResponseHeaders = r.ResponseHeaders;
+        ContentType = r.ContentType;
+        IsSuccess = r.IsSuccess;
+        ErrorMessage = r.ErrorMessage;
+    }
+
     private bool ShouldRetry(int statusCode)
     {
         if (definition.RetryOnStatusCodes is null)
@@ -296,7 +366,7 @@ public static async Task InvokeAllAsync(
             {
                 var handler = new HttpClientTypeHandler(definition, replacements);
                 handlers[typeName] = handler;
-                tasks.Add((typeName, handler, handler.InvokeAsync(cancellationToken)));
+                tasks.Add((typeName, handler, handler.InvokeWithCacheAsync(cancellationToken)));
             }
         }
 
diff --git a/NpgsqlRest/HttpClientType/HttpClientTypes.cs b/NpgsqlRest/HttpClientType/HttpClientTypes.cs
index 7debf487..49c40c25 100644
--- a/NpgsqlRest/HttpClientType/HttpClientTypes.cs
+++ b/NpgsqlRest/HttpClientType/HttpClientTypes.cs
@@ -91,6 +91,8 @@ public HttpClientTypes(IApplicationBuilder? builder, RetryStrategy? retryStrateg
         TimeSpan? timeout = null;
         TimeSpan[]? retryDelays = null;
         HashSet<int>? retryOnStatusCodes = null;
+        bool cacheEnabled = false;
+        TimeSpan? cacheDuration = null;
 
         // Parse directives before the request line
         while (pos < span.Length)
@@ -129,6 +131,17 @@ public HttpClientTypes(IApplicationBuilder? builder, RetryStrategy? retryStrateg
                 continue;
             }
 
+            // Check for cache directive
+            if (TryParseCacheDirective(trimmedLine, typeName, out var parsedCacheDuration))
+            {
+                cacheEnabled = true;
+                cacheDuration = parsedCacheDuration;
+                pos += lineEnd == -1 ? line.Length : lineEnd;
+                if (pos < span.Length && span[pos] == '\r') pos++;
+                if (pos < span.Length && span[pos] == '\n') pos++;
+                continue;
+            }
+
             // Check for # comment (non-timeout directive)
             if (trimmedLine[0] == '#')
             {
@@ -198,12 +211,15 @@ public HttpClientTypes(IApplicationBuilder? builder, RetryStrategy? retryStrateg
             Url = new string(urlSpan),
             Timeout = timeout,
             RetryDelays = retryDelays,
-            RetryOnStatusCodes = retryOnStatusCodes
+            RetryOnStatusCodes = retryOnStatusCodes,
+            CacheEnabled = cacheEnabled,
+            CacheDuration = cacheDuration
         };
 
         // Move past first line
         if (firstLineEnd == -1)
         {
+            NormalizeCacheDirective(result, typeName);
             result.NeedsParsing = needsParsing;
             return result;
         }
@@ -233,6 +249,36 @@ public HttpClientTypes(IApplicationBuilder? builder, RetryStrategy? retryStrateg
                 break;
             }
 
+            // Directives may also appear in the header section (after the request line), not only
+            // before it. Check for them before treating the line as an HTTP header. A directive's
+            // separator/value shape means real headers (which carry a 'Name-Word: value') don't match.
+            if (TryParseTimeoutDirective(line, typeName, out var hdrTimeout))
+            {
+                result.Timeout = hdrTimeout;
+                pos += lineEnd == -1 ? line.Length : lineEnd;
+                if (pos < span.Length && span[pos] == '\r') pos++;
+                if (pos < span.Length && span[pos] == '\n') pos++;
+                continue;
+            }
+            if (TryParseRetryDirective(line, typeName, out var hdrDelays, out var hdrCodes))
+            {
+                result.RetryDelays = hdrDelays;
+                result.RetryOnStatusCodes = hdrCodes;
+                pos += lineEnd == -1 ? line.Length : lineEnd;
+                if (pos < span.Length && span[pos] == '\r') pos++;
+                if (pos < span.Length && span[pos] == '\n') pos++;
+                continue;
+            }
+            if (TryParseCacheDirective(line, typeName, out var hdrCacheDuration))
+            {
+                result.CacheEnabled = true;
+                result.CacheDuration = hdrCacheDuration;
+                pos += lineEnd == -1 ? line.Length : lineEnd;
+                if (pos < span.Length && span[pos] == '\r') pos++;
+                if (pos < span.Length && span[pos] == '\n') pos++;
+                continue;
+            }
+
             int colonIndex = line.IndexOf(':');
             if (colonIndex > 0)
             {
@@ -285,10 +331,33 @@ public HttpClientTypes(IApplicationBuilder? builder, RetryStrategy? retryStrateg
             }
         }
 
+        NormalizeCacheDirective(result, typeName);
         result.NeedsParsing = needsParsing;
         return result;
     }
 
+    // Caching is only safe for GET (idempotent reads). A @cache directive on any other method is
+    // almost always a mistake; warn and ignore it rather than caching a mutating call. Applied after
+    // the whole comment is parsed so it sees @cache whether it appeared before the request line or
+    // among the headers, and after the method is known.
+    private static void NormalizeCacheDirective(HttpTypeDefinition result, string? typeName)
+    {
+        if (!result.CacheEnabled)
+        {
+            return;
+        }
+        if (!string.Equals(result.Method, "GET", StringComparison.Ordinal))
+        {
+            Logger?.LogWarning("Type '{TypeName}': @cache is only supported for GET requests; ignoring it for '{Method}'", typeName, result.Method);
+            result.CacheEnabled = false;
+            result.CacheDuration = null;
+        }
+        else if (result.CacheDuration is null)
+        {
+            Logger?.LogWarning("Type '{TypeName}': @cache has no expiration interval; responses will be cached until the process restarts", typeName);
+        }
+    }
+
     private static ReadOnlySpan<char> TrimSpan(ReadOnlySpan<char> span)
     {
         int start = 0;
@@ -548,4 +617,59 @@ private static bool TryParseRetryDirective(
 
         return true;
     }
+
+    private static bool TryParseCacheDirective(ReadOnlySpan<char> line, string? typeName, out TimeSpan? duration)
+    {
+        duration = null;
+        var trimmed = TrimSpan(line);
+
+        // Remove leading # if present
+        if (!trimmed.IsEmpty && trimmed[0] == '#')
+        {
+            trimmed = TrimSpan(trimmed[1..]);
+        }
+
+        // Remove leading @ if present
+        if (!trimmed.IsEmpty && trimmed[0] == '@')
+        {
+            trimmed = TrimSpan(trimmed[1..]);
+        }
+
+        // Check for "cache" keyword (case-insensitive). Must be the whole token, so "cache_profile"
+        // or other future "cache*" directives are not swallowed here.
+        if (!trimmed.StartsWith("cache", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        var afterKeyword = trimmed[5..]; // Skip "cache"
+
+        // Bare "@cache" (no value) → enabled with no expiration.
+        if (afterKeyword.IsEmpty)
+        {
+            return true;
+        }
+
+        // The next char must be a separator (space, '=', ':'); otherwise this is a different keyword.
+        char sep = afterKeyword[0];
+        if (sep != ' ' && sep != '\t' && sep != '=' && sep != ':')
+        {
+            return false;
+        }
+
+        if (sep == '=' || sep == ':')
+        {
+            afterKeyword = afterKeyword[1..];
+        }
+        afterKeyword = TrimSpan(afterKeyword);
+
+        // "@cache" followed only by separator → enabled with no expiration.
+        if (afterKeyword.IsEmpty)
+        {
+            return true;
+        }
+
+        duration = ParseTimeoutValue(afterKeyword, typeName);
+        return true;
+    }
 }
\ No newline at end of file
diff --git a/NpgsqlRest/HttpClientType/HttpResponseCache.cs b/NpgsqlRest/HttpClientType/HttpResponseCache.cs
new file mode 100644
index 00000000..df1d5099
--- /dev/null
+++ b/NpgsqlRest/HttpClientType/HttpResponseCache.cs
@@ -0,0 +1,160 @@
+using System.Collections.Concurrent;
+
+namespace NpgsqlRest.HttpClientType;
+
+/// <summary>
+/// Immutable snapshot of an outbound HTTP type response, suitable for caching and reuse.
+/// </summary>
+public sealed record CachedHttpResponse(
+    int StatusCode,
+    string? Body,
+    string? ResponseHeaders,
+    string? ContentType,
+    bool IsSuccess,
+    string? ErrorMessage);
+
+/// <summary>
+/// In-memory cache of HTTP type responses with stampede protection. A burst of concurrent requests
+/// for the same key coalesce into a single outbound call; the rest await the in-flight result.
+/// Only successful responses are stored, so a transient upstream failure is never pinned for the TTL.
+/// </summary>
+public static class HttpResponseCache
+{
+    private sealed class CacheEntry
+    {
+        public required CachedHttpResponse Value { get; init; }
+        public DateTime? ExpirationTime { get; init; }
+        public bool IsExpired => ExpirationTime.HasValue && DateTime.UtcNow > ExpirationTime.Value;
+    }
+
+    private static readonly ConcurrentDictionary<string, CacheEntry> _cache = new(StringComparer.Ordinal);
+    // In-flight factory invocations keyed by cache key. The value is a Lazy so that even if
+    // ConcurrentDictionary.GetOrAdd runs its value-factory more than once under contention, only the
+    // stored Lazy's task is ever started — guaranteeing a single outbound call per key.
+    private static readonly ConcurrentDictionary<string, Lazy<Task<CachedHttpResponse>>> _inflight = new(StringComparer.Ordinal);
+
+    private static Timer? _cleanupTimer;
+    private static int _maxEntries = 10_000;
+
+    public static void Start(NpgsqlRestOptions options)
+    {
+        _maxEntries = options.HttpClientOptions.MaxCacheEntries;
+        var interval = TimeSpan.FromSeconds(options.HttpClientOptions.CachePruneIntervalSeconds);
+        _cleanupTimer?.Dispose();
+        _cleanupTimer = new Timer(_ => CleanupExpiredEntries(), null, interval, interval);
+    }
+
+    public static void Shutdown()
+    {
+        _cleanupTimer?.Dispose();
+        _cleanupTimer = null;
+        _cache.Clear();
+        _inflight.Clear();
+    }
+
+    private static void CleanupExpiredEntries()
+    {
+        foreach (var kvp in _cache)
+        {
+            if (kvp.Value.IsExpired)
+            {
+                _cache.TryRemove(kvp.Key, out _);
+            }
+        }
+    }
+
+    private static bool TryGet(string key, out CachedHttpResponse value)
+    {
+        if (_cache.TryGetValue(key, out var entry))
+        {
+            if (entry.IsExpired)
+            {
+                _cache.TryRemove(key, out _);
+                value = null!;
+                return false;
+            }
+            value = entry.Value;
+            return true;
+        }
+        value = null!;
+        return false;
+    }
+
+    private static void Store(string key, CachedHttpResponse value, TimeSpan? ttl)
+    {
+        // Bound memory: once full, don't admit new keys (existing entries still serve and expire).
+        // Updates to an already-cached key are always allowed.
+        if (_cache.Count >= _maxEntries && !_cache.ContainsKey(key))
+        {
+            return;
+        }
+
+        _cache[key] = new CacheEntry
+        {
+            Value = value,
+            ExpirationTime = ttl.HasValue ? DateTime.UtcNow + ttl.Value : null
+        };
+    }
+
+    /// <summary>
+    /// Returns the cached response for <paramref name="key"/> if present and unexpired; otherwise runs
+    /// <paramref name="factory"/> (the outbound call), stores the result when it is successful, and
+    /// returns it. Concurrent callers for the same key coalesce into one factory invocation.
+    /// </summary>
+    public static async Task<CachedHttpResponse> GetOrCreateAsync(
+        string key,
+        TimeSpan? ttl,
+        Func<CancellationToken, Task<CachedHttpResponse>> factory,
+        CancellationToken cancellationToken)
+    {
+        while (true)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            if (TryGet(key, out var cached))
+            {
+                return cached;
+            }
+
+            var lazy = _inflight.GetOrAdd(
+                key,
+                _ => new Lazy<Task<CachedHttpResponse>>(() => RunFactoryAsync(key, ttl, factory, cancellationToken)));
+
+            try
+            {
+                return await lazy.Value.WaitAsync(cancellationToken);
+            }
+            catch (OperationCanceledException)
+            {
+                if (cancellationToken.IsCancellationRequested)
+                {
+                    throw;
+                }
+                // The lead caller (whose token drove the shared run) was cancelled before this waiter.
+                // Loop and retry — the value may now be cached, or this caller becomes the new lead.
+            }
+        }
+    }
+
+    private static async Task<CachedHttpResponse> RunFactoryAsync(
+        string key,
+        TimeSpan? ttl,
+        Func<CancellationToken, Task<CachedHttpResponse>> factory,
+        CancellationToken cancellationToken)
+    {
+        try
+        {
+            var result = await factory(cancellationToken).ConfigureAwait(false);
+            // Success-only: never pin a transient upstream failure for the whole TTL.
+            if (result.IsSuccess)
+            {
+                Store(key, result, ttl);
+            }
+            return result;
+        }
+        finally
+        {
+            _inflight.TryRemove(key, out _);
+        }
+    }
+}
diff --git a/NpgsqlRest/HttpClientType/HttpTypeDefinition.cs b/NpgsqlRest/HttpClientType/HttpTypeDefinition.cs
index 6cb1ffb8..045a3960 100644
--- a/NpgsqlRest/HttpClientType/HttpTypeDefinition.cs
+++ b/NpgsqlRest/HttpClientType/HttpTypeDefinition.cs
@@ -11,4 +11,17 @@ public class HttpTypeDefinition
     public TimeSpan[]? RetryDelays { get; set; }
     public HashSet<int>? RetryOnStatusCodes { get; set; }
     public bool NeedsParsing { get; set; }
+
+    /// <summary>
+    /// True when the type comment carries a <c>@cache</c> directive, opting this HTTP type into
+    /// response caching. Successful responses are cached and reused for matching requests
+    /// (same method + resolved URL + headers + body) until <see cref="CacheDuration"/> elapses.
+    /// </summary>
+    public bool CacheEnabled { get; set; }
+
+    /// <summary>
+    /// Time-to-live for cached responses. <c>null</c> when <see cref="CacheEnabled"/> is true means
+    /// the response is cached with no expiration (until the process restarts).
+    /// </summary>
+    public TimeSpan? CacheDuration { get; set; }
 }
\ No newline at end of file
diff --git a/NpgsqlRest/NpgsqlRestBuilder.cs b/NpgsqlRest/NpgsqlRestBuilder.cs
index a7b87d30..42b5fb15 100644
--- a/NpgsqlRest/NpgsqlRestBuilder.cs
+++ b/NpgsqlRest/NpgsqlRestBuilder.cs
@@ -58,6 +58,15 @@ public static IApplicationBuilder UseNpgsqlRest(this WebApplication builder, Npg
         if (Options.HttpClientOptions.Enabled is true)
         {
             new HttpClientTypes(builder, defaultStrategy);
+
+            if (Options.HttpClientOptions.CacheEnabled)
+            {
+                HttpClientType.HttpResponseCache.Start(Options);
+                if (builder is WebApplication httpCacheApp)
+                {
+                    httpCacheApp.Lifetime.ApplicationStopping.Register(HttpClientType.HttpResponseCache.Shutdown);
+                }
+            }
         }
 
         var (
diff --git a/NpgsqlRest/Options/HttpClientOptions.cs b/NpgsqlRest/Options/HttpClientOptions.cs
index 6cbfd0fe..a72ebd18 100644
--- a/NpgsqlRest/Options/HttpClientOptions.cs
+++ b/NpgsqlRest/Options/HttpClientOptions.cs
@@ -44,4 +44,24 @@ public class HttpClientOptions
     /// Example: "http://localhost:5000"
     /// </summary>
     public string? SelfBaseUrl { get; set; }
+
+    /// <summary>
+    /// Global kill switch for HTTP type response caching. When false, the <c>@cache</c> directive on
+    /// individual types is ignored and every request fires a fresh outbound call. Default is true,
+    /// so caching is opt-in per type via <c>@cache</c> and globally disable-able here.
+    /// </summary>
+    public bool CacheEnabled { get; set; } = true;
+
+    /// <summary>
+    /// Maximum number of distinct cached HTTP responses held in memory. Once the cache is full, new
+    /// responses are not cached (existing entries are still served and expire normally). Bounds memory
+    /// for types whose URL/body/headers contain per-request placeholders. Default is 10000.
+    /// </summary>
+    public int MaxCacheEntries { get; set; } = 10_000;
+
+    /// <summary>
+    /// Interval in seconds at which expired cached HTTP responses are pruned from memory.
+    /// Default is 60 seconds.
+    /// </summary>
+    public int CachePruneIntervalSeconds { get; set; } = 60;
 }
diff --git a/NpgsqlRestClient/Builder.cs b/NpgsqlRestClient/Builder.cs
index 8fb0b747..d38119aa 100644
--- a/NpgsqlRestClient/Builder.cs
+++ b/NpgsqlRestClient/Builder.cs
@@ -2806,7 +2806,10 @@ public HttpClientOptions BuildHttpClientOptions()
             ResponseHeadersField = _config.GetConfigStr("ResponseHeadersField", cfg) ?? "headers",
             ResponseContentTypeField = _config.GetConfigStr("ResponseContentTypeField", cfg) ?? "content_type",
             ResponseSuccessField = _config.GetConfigStr("ResponseSuccessField", cfg) ?? "success",
-            ResponseErrorMessageField = _config.GetConfigStr("ResponseErrorMessageField", cfg) ?? "error_message"
+            ResponseErrorMessageField = _config.GetConfigStr("ResponseErrorMessageField", cfg) ?? "error_message",
+            CacheEnabled = _config.GetConfigBool("CacheEnabled", cfg, true),
+            MaxCacheEntries = _config.GetConfigInt("MaxCacheEntries", cfg) ?? 10_000,
+            CachePruneIntervalSeconds = _config.GetConfigInt("CachePruneIntervalSeconds", cfg) ?? 60
         };
 
         if (options.Enabled)
diff --git a/NpgsqlRestClient/ConfigDefaults.cs b/NpgsqlRestClient/ConfigDefaults.cs
index 4c4f30c9..cbdeff67 100644
--- a/NpgsqlRestClient/ConfigDefaults.cs
+++ b/NpgsqlRestClient/ConfigDefaults.cs
@@ -1044,7 +1044,10 @@ private static JsonObject GetHttpClientOptionsDefaults()
             ["ResponseHeadersField"] = "headers",
             ["ResponseContentTypeField"] = "content_type",
             ["ResponseSuccessField"] = "success",
-            ["ResponseErrorMessageField"] = "error_message"
+            ["ResponseErrorMessageField"] = "error_message",
+            ["CacheEnabled"] = true,
+            ["MaxCacheEntries"] = 10000,
+            ["CachePruneIntervalSeconds"] = 60
         };
     }
 
diff --git a/NpgsqlRestClient/ConfigSchemaGenerator.cs b/NpgsqlRestClient/ConfigSchemaGenerator.cs
index d58b0882..114082cb 100644
--- a/NpgsqlRestClient/ConfigSchemaGenerator.cs
+++ b/NpgsqlRestClient/ConfigSchemaGenerator.cs
@@ -493,6 +493,9 @@ public static partial class ConfigSchemaGenerator
         ["NpgsqlRest:HttpClientOptions:ResponseContentTypeField"] = "Default name for the response content type field within annotated types.",
         ["NpgsqlRest:HttpClientOptions:ResponseSuccessField"] = "Default name for the response success field within annotated types.",
         ["NpgsqlRest:HttpClientOptions:ResponseErrorMessageField"] = "Default name for the response error message field within annotated types.",
+        ["NpgsqlRest:HttpClientOptions:CacheEnabled"] = "Global kill switch for HTTP type response caching. When false, the '@cache' directive on individual types is ignored and every request fires a fresh outbound call. Caching is opt-in per type via the '@cache <interval>' type-comment directive.",
+        ["NpgsqlRest:HttpClientOptions:MaxCacheEntries"] = "Maximum number of distinct cached HTTP responses held in memory. Once full, new responses are not cached (existing entries are still served and expire normally).",
+        ["NpgsqlRest:HttpClientOptions:CachePruneIntervalSeconds"] = "Interval in seconds at which expired cached HTTP responses are pruned from memory.",
         ["NpgsqlRest:ProxyOptions"] = "Reverse proxy functionality for NpgsqlRest endpoints.\nWhen an endpoint is marked with 'proxy' annotation, incoming requests are forwarded to another URL.",
         ["NpgsqlRest:ProxyOptions:Enabled"] = "Enable proxy functionality for annotated endpoints.",
         ["NpgsqlRest:ProxyOptions:Host"] = "Base URL (host) for proxy requests (e.g., \"https://api.example.com\").\nWhen set, proxy endpoints will forward requests to this host + the original path.",
diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index aaeafd15..df4b51c6 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -2803,7 +2803,22 @@ public static partial class ConfigSchemaGenerator
           //
           // Default name for the response error message field within annotated types.
           //
-          "ResponseErrorMessageField": "error_message"
+          "ResponseErrorMessageField": "error_message",
+          //
+          // Global kill switch for HTTP type response caching. When false, the '@cache' directive on
+          // individual types is ignored and every request fires a fresh outbound call. Caching is opt-in
+          // per type via the '@cache <interval>' type-comment directive.
+          //
+          "CacheEnabled": true,
+          //
+          // Maximum number of distinct cached HTTP responses held in memory. Once full, new responses are
+          // not cached (existing entries are still served and expire normally).
+          //
+          "MaxCacheEntries": 10000,
+          //
+          // Interval in seconds at which expired cached HTTP responses are pruned from memory.
+          //
+          "CachePruneIntervalSeconds": 60
         },
     
         //
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index 14ba99a4..9b19fb5d 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -2794,7 +2794,22 @@
       //
       // Default name for the response error message field within annotated types.
       //
-      "ResponseErrorMessageField": "error_message"
+      "ResponseErrorMessageField": "error_message",
+      //
+      // Global kill switch for HTTP type response caching. When false, the '@cache' directive on
+      // individual types is ignored and every request fires a fresh outbound call. Caching is opt-in
+      // per type via the '@cache <interval>' type-comment directive.
+      //
+      "CacheEnabled": true,
+      //
+      // Maximum number of distinct cached HTTP responses held in memory. Once full, new responses are
+      // not cached (existing entries are still served and expire normally).
+      //
+      "MaxCacheEntries": 10000,
+      //
+      // Interval in seconds at which expired cached HTTP responses are pruned from memory.
+      //
+      "CachePruneIntervalSeconds": 60
     },
 
     //
diff --git a/NpgsqlRestTests/HttpClientTypeTests/HttpClientTypeCacheTests.cs b/NpgsqlRestTests/HttpClientTypeTests/HttpClientTypeCacheTests.cs
new file mode 100644
index 00000000..d204e052
--- /dev/null
+++ b/NpgsqlRestTests/HttpClientTypeTests/HttpClientTypeCacheTests.cs
@@ -0,0 +1,289 @@
+using WireMock.Server;
+using WireMock.RequestBuilders;
+using WireMock.ResponseBuilders;
+using WireMock;
+using WireMock.Types;
+using WireMock.Util;
+
+namespace NpgsqlRestTests;
+
+public static partial class Database
+{
+    public static void HttpClientTypeCacheTests()
+    {
+        script.Append($@"
+        -- Cache test 1: basic GET with @cache, body response
+        create type cache_basic_api as (
+            body text
+        );
+        comment on type cache_basic_api is '@cache 60s
+GET http://localhost:{WireMockFixture.Port}/api/cache-basic';
+
+        create function get_cache_basic(
+            req cache_basic_api
+        )
+        returns text
+        language plpgsql
+        as
+        $$
+        begin
+            return (req).body;
+        end;
+        $$;
+
+        -- Cache test 2: multi-field (6) type with @cache - dedup + cache combined
+        create type cache_sixfield_api as (
+            body text,
+            status_code int,
+            content_type text,
+            headers json,
+            success boolean,
+            error_message text
+        );
+        comment on type cache_sixfield_api is '@cache 60s
+GET http://localhost:{WireMockFixture.Port}/api/cache-sixfield';
+
+        create function get_cache_sixfield(
+            req cache_sixfield_api
+        )
+        returns text
+        language plpgsql
+        as
+        $$
+        begin
+            return (req).body;
+        end;
+        $$;
+
+        -- Cache test 3: error responses must NOT be cached
+        create type cache_error_api as (
+            body text,
+            status_code int,
+            success boolean
+        );
+        comment on type cache_error_api is '@cache 60s
+GET http://localhost:{WireMockFixture.Port}/api/cache-error';
+
+        create function get_cache_error(
+            req cache_error_api
+        )
+        returns json
+        language plpgsql
+        as
+        $$
+        begin
+            return json_build_object(
+                'body', (req).body,
+                'status_code', (req).status_code,
+                'success', (req).success
+            );
+        end;
+        $$;
+
+        -- Cache test 4: @cache on POST is ignored (only GET is cacheable)
+        create type cache_post_api as (
+            body text,
+            status_code int
+        );
+        comment on type cache_post_api is '@cache 60s
+POST http://localhost:{WireMockFixture.Port}/api/cache-post
+Content-Type: application/json
+
+{{""ping"": true}}';
+
+        create function get_cache_post(
+            req cache_post_api
+        )
+        returns text
+        language plpgsql
+        as
+        $$
+        begin
+            return (req).body;
+        end;
+        $$;
+
+        -- Cache test 5: short TTL for expiry verification
+        create type cache_ttl_api as (
+            body text
+        );
+        comment on type cache_ttl_api is '@cache 1s
+GET http://localhost:{WireMockFixture.Port}/api/cache-ttl';
+
+        create function get_cache_ttl(
+            req cache_ttl_api
+        )
+        returns text
+        language plpgsql
+        as
+        $$
+        begin
+            return (req).body;
+        end;
+        $$;
+");
+    }
+}
+
+[Collection("TestFixture")]
+public class HttpClientTypeCacheTests : IClassFixture<WireMockFixture>
+{
+    private readonly TestFixture _test;
+    private readonly WireMockServer _server;
+
+    public HttpClientTypeCacheTests(TestFixture test, WireMockFixture wireMock)
+    {
+        _test = test;
+        _server = wireMock.Server;
+        _server.Reset();
+    }
+
+    // A cached GET fires the outbound call once; the second request is served from the cache. The
+    // callback embeds its invocation count in the body, so a cache hit returns the SAME body the
+    // first call produced - proving the second response is the cached one, not a fresh fetch.
+    [Fact]
+    public async Task Test_cached_get_fires_outbound_call_once()
+    {
+        int calls = 0;
+        _server
+            .Given(Request.Create().WithPath("/api/cache-basic").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                int n = Interlocked.Increment(ref calls);
+                return new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = $"cache-basic-call-{n}", DetectedBodyType = BodyType.String }
+                };
+            }));
+
+        using var first = await _test.Client.GetAsync("/api/get-cache-basic/");
+        var firstContent = await first.Content.ReadAsStringAsync();
+        using var second = await _test.Client.GetAsync("/api/get-cache-basic/");
+        var secondContent = await second.Content.ReadAsStringAsync();
+
+        first.StatusCode.Should().Be(HttpStatusCode.OK);
+        second.StatusCode.Should().Be(HttpStatusCode.OK);
+        firstContent.Should().Be("cache-basic-call-1");
+        secondContent.Should().Be("cache-basic-call-1"); // served from cache, not "call-2"
+        calls.Should().Be(1);
+    }
+
+    // A 6-field composite type combines the dedup fix (one call per request, not 6) with caching
+    // (one call across requests). Two requests against a 6-field cached type → exactly one call.
+    [Fact]
+    public async Task Test_cached_multi_field_type_fires_one_call_across_requests()
+    {
+        int calls = 0;
+        _server
+            .Given(Request.Create().WithPath("/api/cache-sixfield").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                Interlocked.Increment(ref calls);
+                return new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = "sixfield-body", DetectedBodyType = BodyType.String }
+                };
+            }));
+
+        using var first = await _test.Client.GetAsync("/api/get-cache-sixfield/");
+        var firstContent = await first.Content.ReadAsStringAsync();
+        using var second = await _test.Client.GetAsync("/api/get-cache-sixfield/");
+
+        first.StatusCode.Should().Be(HttpStatusCode.OK);
+        second.StatusCode.Should().Be(HttpStatusCode.OK);
+        firstContent.Should().Be("sixfield-body");
+        calls.Should().Be(1);
+    }
+
+    // A failed (non-2xx) response must not be cached, so a transient upstream error is not pinned for
+    // the whole TTL. First call returns 500, second returns 200 - the second must reach upstream and
+    // observe the 200, and both calls must hit the server.
+    [Fact]
+    public async Task Test_error_response_is_not_cached()
+    {
+        int calls = 0;
+        _server
+            .Given(Request.Create().WithPath("/api/cache-error").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                int n = Interlocked.Increment(ref calls);
+                return n == 1
+                    ? new ResponseMessage
+                    {
+                        StatusCode = 500,
+                        BodyData = new BodyData { BodyAsString = "boom", DetectedBodyType = BodyType.String }
+                    }
+                    : new ResponseMessage
+                    {
+                        StatusCode = 200,
+                        BodyData = new BodyData { BodyAsString = "recovered", DetectedBodyType = BodyType.String }
+                    };
+            }));
+
+        using var first = await _test.Client.GetAsync("/api/get-cache-error/");
+        var firstContent = await first.Content.ReadAsStringAsync();
+        using var second = await _test.Client.GetAsync("/api/get-cache-error/");
+        var secondContent = await second.Content.ReadAsStringAsync();
+
+        firstContent.Should().Contain("\"status_code\" : 500");
+        firstContent.Should().Contain("\"success\" : false");
+        secondContent.Should().Contain("\"status_code\" : 200");
+        secondContent.Should().Contain("\"success\" : true");
+        calls.Should().Be(2); // the 500 was not cached
+    }
+
+    // @cache on a non-GET method is ignored (warned at startup), so POST fires every request.
+    [Fact]
+    public async Task Test_cache_directive_ignored_for_post()
+    {
+        int calls = 0;
+        _server
+            .Given(Request.Create().WithPath("/api/cache-post").UsingPost())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                Interlocked.Increment(ref calls);
+                return new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = "posted", DetectedBodyType = BodyType.String }
+                };
+            }));
+
+        using var first = await _test.Client.GetAsync("/api/get-cache-post/");
+        using var second = await _test.Client.GetAsync("/api/get-cache-post/");
+
+        first.StatusCode.Should().Be(HttpStatusCode.OK);
+        second.StatusCode.Should().Be(HttpStatusCode.OK);
+        calls.Should().Be(2); // POST is never cached
+    }
+
+    // After the TTL elapses, the entry expires and the next request re-fetches.
+    [Fact]
+    public async Task Test_cached_response_expires_after_ttl()
+    {
+        int calls = 0;
+        _server
+            .Given(Request.Create().WithPath("/api/cache-ttl").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                Interlocked.Increment(ref calls);
+                return new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = "ttl-body", DetectedBodyType = BodyType.String }
+                };
+            }));
+
+        using var first = await _test.Client.GetAsync("/api/get-cache-ttl/");      // miss -> 1 call
+        using var second = await _test.Client.GetAsync("/api/get-cache-ttl/");     // hit  -> still 1
+        calls.Should().Be(1);
+
+        await Task.Delay(TimeSpan.FromSeconds(2)); // TTL is 1s; generous margin
+
+        using var third = await _test.Client.GetAsync("/api/get-cache-ttl/");      // expired -> 2 calls
+        third.StatusCode.Should().Be(HttpStatusCode.OK);
+        calls.Should().Be(2);
+    }
+}
diff --git a/NpgsqlRestTests/HttpClientTypeTests/ParseHttpTypeDefinitionTests.cs b/NpgsqlRestTests/HttpClientTypeTests/ParseHttpTypeDefinitionTests.cs
index 9a05221b..5cb76b3d 100644
--- a/NpgsqlRestTests/HttpClientTypeTests/ParseHttpTypeDefinitionTests.cs
+++ b/NpgsqlRestTests/HttpClientTypeTests/ParseHttpTypeDefinitionTests.cs
@@ -1016,4 +1016,148 @@ public void NeedsParsing_handles_nested_json_with_placeholder()
         result.Should().NotBeNull();
         result!.NeedsParsing.Should().BeTrue();
     }
+
+    // No @cache directive: caching is off and duration is null.
+    [Fact]
+    public void Cache_disabled_by_default()
+    {
+        var result = _parser.ParseHttpTypeDefinition("GET https://api.example.com/data");
+
+        result.Should().NotBeNull();
+        result!.CacheEnabled.Should().BeFalse();
+        result.CacheDuration.Should().BeNull();
+    }
+
+    [Theory]
+    [InlineData("cache 60s")]
+    [InlineData("cache=60s")]
+    [InlineData("cache: 60s")]
+    [InlineData("@cache 60s")]
+    public void Parses_cache_directive_with_interval(string directive)
+    {
+        var input = $"{directive}\nGET https://api.example.com/data";
+
+        var result = _parser.ParseHttpTypeDefinition(input);
+
+        result.Should().NotBeNull();
+        result!.CacheEnabled.Should().BeTrue();
+        result.CacheDuration.Should().Be(TimeSpan.FromSeconds(60));
+    }
+
+    [Fact]
+    public void Parses_cache_directive_with_timespan_format()
+    {
+        var input = """
+            @cache 00:05:00
+            GET https://api.example.com/data
+            """;
+
+        var result = _parser.ParseHttpTypeDefinition(input);
+
+        result.Should().NotBeNull();
+        result!.CacheEnabled.Should().BeTrue();
+        result.CacheDuration.Should().Be(TimeSpan.FromMinutes(5));
+    }
+
+    // Bare @cache (no interval): enabled, no expiration.
+    [Fact]
+    public void Parses_bare_cache_directive_as_enabled_no_expiry()
+    {
+        var input = """
+            @cache
+            GET https://api.example.com/data
+            """;
+
+        var result = _parser.ParseHttpTypeDefinition(input);
+
+        result.Should().NotBeNull();
+        result!.CacheEnabled.Should().BeTrue();
+        result.CacheDuration.Should().BeNull();
+    }
+
+    // @cache on a non-GET method is ignored (only GET is cacheable).
+    [Theory]
+    [InlineData("POST")]
+    [InlineData("PUT")]
+    [InlineData("PATCH")]
+    [InlineData("DELETE")]
+    public void Cache_directive_ignored_for_non_get(string method)
+    {
+        var input = $"@cache 60s\n{method} https://api.example.com/data";
+
+        var result = _parser.ParseHttpTypeDefinition(input);
+
+        result.Should().NotBeNull();
+        result!.CacheEnabled.Should().BeFalse();
+        result.CacheDuration.Should().BeNull();
+    }
+
+    // Directives may appear AFTER the request line and headers, not only before it. The docs show
+    // them in this position; the parser recognizes them in the header section too.
+    [Fact]
+    public void Parses_timeout_directive_after_headers()
+    {
+        var input = """
+            GET https://api.example.com/data
+            Accept: application/json
+            @timeout 30s
+            """;
+
+        var result = _parser.ParseHttpTypeDefinition(input);
+
+        result.Should().NotBeNull();
+        result!.Timeout.Should().Be(TimeSpan.FromSeconds(30));
+        result.Headers.Should().ContainKey("Accept");
+    }
+
+    [Fact]
+    public void Parses_retry_directive_after_headers()
+    {
+        var input = """
+            GET https://api.example.com/data
+            Accept: application/json
+            @retry_delay 1s, 2s on 429, 503
+            """;
+
+        var result = _parser.ParseHttpTypeDefinition(input);
+
+        result.Should().NotBeNull();
+        result!.RetryDelays.Should().Equal(TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(2));
+        result.RetryOnStatusCodes.Should().BeEquivalentTo(new[] { 429, 503 });
+        result.Headers.Should().ContainKey("Accept");
+    }
+
+    [Fact]
+    public void Parses_cache_directive_after_headers()
+    {
+        var input = """
+            GET https://api.example.com/data
+            Accept: application/json
+            @cache 5m
+            """;
+
+        var result = _parser.ParseHttpTypeDefinition(input);
+
+        result.Should().NotBeNull();
+        result!.CacheEnabled.Should().BeTrue();
+        result.CacheDuration.Should().Be(TimeSpan.FromMinutes(5));
+        result.Headers.Should().ContainKey("Accept");
+    }
+
+    // A real header whose name merely starts with a directive keyword but isn't one (e.g.
+    // "Cache-Control") is still treated as a header, not a directive.
+    [Fact]
+    public void Cache_control_header_is_not_treated_as_cache_directive()
+    {
+        var input = """
+            GET https://api.example.com/data
+            Cache-Control: no-cache
+            """;
+
+        var result = _parser.ParseHttpTypeDefinition(input);
+
+        result.Should().NotBeNull();
+        result!.CacheEnabled.Should().BeFalse();
+        result.Headers.Should().ContainKey("Cache-Control");
+    }
 }
diff --git a/changelog/v3.17.1.md b/changelog/v3.17.1.md
deleted file mode 100644
index 3d659752..00000000
--- a/changelog/v3.17.1.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# Changelog v3.17.1
-
-## Version [3.17.1](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.17.1)
-
-[Full Changelog](https://github.com/NpgsqlRest/NpgsqlRest/compare/3.17.0...3.17.1)
-
-Patch release that fixes **duplicate outbound HTTP calls for HTTP Custom Types on database-function endpoints**.
-
-## The bug
-
-An endpoint backed by a **database function/procedure** whose parameter is an HTTP Custom Type fired **one outbound HTTP call per field of the type** on every inbound request. A 4-field type made 4 identical calls; a 6-field type made 6 — multiplying latency and load on the target service. SQL-file endpoints were not affected.
-
-## Cause
-
-A composite function parameter is expanded into one parameter **per field**, and each of those expanded parameters carries the same `TypeDescriptor.CustomType` (the HTTP type name). The type name was therefore collected once per field, so the per-request list of HTTP types to invoke contained the same name N times. The firing loop in `HttpClientTypeHandler.InvokeAllAsync` then called `InvokeAsync` once per entry, with no dedup — while the fill loop immediately below resolves handlers by **distinct** type name out of a dictionary. The design already assumes exactly one call per distinct type; the firing loop just failed to match, so the extra calls were made and their handlers discarded.
-
-SQL-file endpoints keep the HTTP type as a single composite parameter (`CustomTypeName` null), so the name was collected once → exactly one call, which is why they were unaffected.
-
-## What changed
-
-A one-line guard in `HttpClientTypeHandler.InvokeAllAsync` makes the firing loop request each distinct HTTP type once:
-
-```csharp
-foreach (var typeName in typeNames)
-{
-    if (handlers.ContainsKey(typeName)) continue; // fire once per distinct type
-    if (HttpClientTypes.Definitions.TryGetValue(typeName, out var definition))
-    {
-        var handler = new HttpClientTypeHandler(definition, replacements);
-        handlers[typeName] = handler;
-        tasks.Add((typeName, handler, handler.InvokeAsync(cancellationToken)));
-    }
-}
-```
-
-This is the single choke point for firing outbound calls and reuses the same dictionary the fill loop already keys on, so it is robust regardless of how the parameter list is built. The established contract is preserved: one call per **distinct** HTTP type, shared from one response — two parameters referencing the same type still share a single call, and two different types remain two separate calls.
-
-## Tests
-
-Two regression tests added (`NpgsqlRestTests/HttpClientTypeTests/HttpClientTypeTests.cs`) that count **actual** outbound calls via a WireMock response callback (the prior suite asserted response content but never call counts):
-
-- A 6-field HTTP type fires **exactly one** outbound call (was 6 before the fix).
-- Two distinct HTTP types in one function each fire **exactly one** call.
-
-Verified against the pre-fix code: the multi-field test failed with `Expected calls to be 1, but found 6`, reproducing the reported behavior. All 46 HTTP-client-type tests pass with the fix.
diff --git a/changelog/v3.18.0.md b/changelog/v3.18.0.md
new file mode 100644
index 00000000..33042a0a
--- /dev/null
+++ b/changelog/v3.18.0.md
@@ -0,0 +1,53 @@
+# Changelog v3.18.0
+
+## Version [3.18.0](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.18.0)
+
+[Full Changelog](https://github.com/NpgsqlRest/NpgsqlRest/compare/3.17.0...3.18.0)
+
+The headline of this release is **HTTP Custom Type response caching** — outbound HTTP calls made by HTTP Custom Types can now be cached and reused, eliminating repeated calls to the same upstream within a configurable time window. The release also fixes a duplicate-outbound-call bug for HTTP types on database-function endpoints.
+
+## New Features
+
+### HTTP Custom Type response caching — `@cache` directive
+
+An HTTP Custom Type can now opt into response caching with a `@cache` directive in its type comment, alongside the existing `@timeout` and `@retry_delay` directives. Directives appear **before** the request line:
+
+```sql
+comment on type books_api is '@cache 5m
+GET https://books.toscrape.com/';
+```
+
+A cached type fires **one outbound call** for a given request shape; subsequent matching requests are served from the in-memory cache until the TTL elapses. For a type with no per-request placeholders (a constant URL/headers/body), that means a single shared upstream call per TTL window across the whole application — instead of one call per inbound request.
+
+**Behavior and safety rules:**
+
+- **Opt-in, GET-only.** Caching is enabled per type by `@cache`. A `@cache` directive on any non-GET method is ignored with a startup warning — caching a mutating call is almost always a mistake.
+- **TTL.** `@cache <interval>` accepts the same formats as `@timeout` (`5m`, `30s`, `1h`, `00:05:00`, or a bare number of seconds). A bare `@cache` (no interval) caches with no expiration (until the process restarts) and warns.
+- **Success-only.** Only successful (2xx) responses are cached, so a transient upstream failure is never pinned for the whole TTL — the next request re-fetches.
+- **Stampede protection.** A burst of concurrent requests for the same cache key coalesces into a **single** outbound call; the rest await the in-flight result (same `Lazy<Task>` coalescing model as the routine cache).
+- **Cache key** = HTTP method + resolved URL + resolved content-type + resolved headers + resolved body. Placeholders are resolved first, so per-request values vary the key naturally.
+
+**Configuration** (`HttpClientOptions`):
+
+- `CacheEnabled` (default `true`) — global kill switch. When `false`, `@cache` directives are ignored and every request fires a fresh call.
+- `MaxCacheEntries` (default `10000`) — bounds memory; once full, new responses are not cached (existing entries still serve and expire normally).
+- `CachePruneIntervalSeconds` (default `60`) — how often expired entries are pruned.
+
+## Fixes
+
+### HTTP Custom Type request fired once per composite field on database-function endpoints
+
+An endpoint backed by a **database function/procedure** whose parameter is an HTTP Custom Type fired **one outbound HTTP call per field of the type** on every inbound request (a 4-field type → 4 identical calls; a 6-field type → 6), multiplying latency and load on the target. SQL-file endpoints were not affected.
+
+**Cause.** A composite function parameter is expanded into one parameter per field, each carrying the same `TypeDescriptor.CustomType` (the HTTP type name). The per-request list of HTTP types therefore held the same name N times, and the firing loop in `HttpClientTypeHandler.InvokeAllAsync` called `InvokeAsync` once per entry — while the fill loop immediately below resolves handlers by **distinct** type name. The design already assumes one call per distinct type; the firing loop just failed to match.
+
+**Fix.** A guard in the firing loop requests each distinct HTTP type once, reusing the dictionary the fill loop already keys on. The established contract is preserved: one call per **distinct** HTTP type, shared from one response — two parameters referencing the same type still share a single call, and two different types remain two separate calls.
+
+### HTTP type directives after the headers were silently ignored
+
+The `@timeout`, `@retry_delay`, and `@cache` directives are now parsed both **before** the request line and **after** the headers. Previously only the leading position (before the request line) was recognized, so a directive placed after the headers — as the documentation and examples showed — was silently dropped (e.g. a `@timeout` that never applied). Both placements are now equivalent. Real HTTP headers are unaffected: a header whose name merely starts with a directive keyword (e.g. `Cache-Control`) is still treated as a header.
+
+## Tests
+
+- Regression tests count **actual** outbound calls via WireMock response callbacks (the prior suite asserted content but never call counts): a 6-field type fires exactly one call (was 6), and two distinct types fire one call each.
+- Caching tests cover: cache hit reduces to one call, 6-field dedup + caching combined, error responses not cached, `@cache` ignored on POST, and TTL expiry. Parse-level tests cover the `@cache` directive forms and GET-only enforcement.
diff --git a/npm/package.json b/npm/package.json
index 859024b3..621ecdbe 100644
--- a/npm/package.json
+++ b/npm/package.json
@@ -1,6 +1,6 @@
 {
   "name": "npgsqlrest",
-  "version": "3.17.1",
+  "version": "3.18.0",
   "description": "Automatic REST API for PostgreSQL Databases Client Build",
   "scripts": {
     "postinstall": "node postinstall.js",
diff --git a/version.txt b/version.txt
index 0caba260..ae561550 100644
--- a/version.txt
+++ b/version.txt
@@ -1 +1 @@
-3.17.1
\ No newline at end of file
+3.18.0
\ No newline at end of file

From e036f3d322e900e7a36c5d65ae96f4f48b32602e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Tue, 23 Jun 2026 12:36:52 +0200
Subject: [PATCH 05/25] upgrade references

---
 NpgsqlRestClient/NpgsqlRestClient.csproj | 4 ++--
 NpgsqlRestTests/NpgsqlRestTests.csproj   | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/NpgsqlRestClient/NpgsqlRestClient.csproj b/NpgsqlRestClient/NpgsqlRestClient.csproj
index 03e0a02b..6beaecf6 100644
--- a/NpgsqlRestClient/NpgsqlRestClient.csproj
+++ b/NpgsqlRestClient/NpgsqlRestClient.csproj
@@ -15,14 +15,14 @@
 
   <ItemGroup>
     <PackageReference Include="AspNetCore.HealthChecks.NpgSql" Version="9.0.0" />
-    <PackageReference Include="ExcelDataReader" Version="3.8.0" />
+    <PackageReference Include="ExcelDataReader" Version="3.9.0" />
     <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.9" />
     <PackageReference Include="Serilog.AspNetCore" Version="10.0.0" />
     <PackageReference Include="Serilog.Sinks.OpenTelemetry" Version="4.2.0" />
     <PackageReference Include="Microsoft.Extensions.Caching.Hybrid" Version="10.7.0" />
     <PackageReference Include="Microsoft.Extensions.Caching.StackExchangeRedis" Version="10.0.9" />
     <PackageReference Include="SpreadCheetah" Version="1.27.0" />
-    <PackageReference Include="StackExchange.Redis" Version="2.13.17" />
+    <PackageReference Include="StackExchange.Redis" Version="3.0.0" />
   </ItemGroup>
   
   <ItemGroup>
diff --git a/NpgsqlRestTests/NpgsqlRestTests.csproj b/NpgsqlRestTests/NpgsqlRestTests.csproj
index fcd52b6b..a2a10468 100644
--- a/NpgsqlRestTests/NpgsqlRestTests.csproj
+++ b/NpgsqlRestTests/NpgsqlRestTests.csproj
@@ -16,9 +16,9 @@
 
   <ItemGroup>
     <PackageReference Include="FluentAssertions" Version="8.10.0" />
-    <PackageReference Include="WireMock.Net" Version="2.10.0" />
+    <PackageReference Include="WireMock.Net" Version="2.11.0" />
     <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.9" />
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.6.0" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.7.0" />
     <PackageReference Include="xunit" Version="2.9.3" />
     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5">
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>

From c74a4b5db331f47f62f3707138ca2e40bae0b8a1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Tue, 23 Jun 2026 14:06:57 +0200
Subject: [PATCH 06/25] feat(proxy): forward all automatic parameters to proxy
 upstream consistently (v3.18.1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When an endpoint is a proxy, all server-filled parameters now forward to
the upstream through one unified path: user claims, IP address, HTTP
Custom Type fields, and resolved-parameter expressions.

Placement mirrors the endpoint's own signature, NOT the HTTP verb:
- a @body_parameter_name param carries the raw request body;
- otherwise RequestParamType decides — QueryString appends to the proxy
  query string, BodyJson merges into the proxy JSON body (typed:
  numbers / booleans / embedded json / strings) when the method carries
  a body.

Additive: the verbatim incoming request is still forwarded; the
automatic params are added on top so the upstream receives the same
parameter set the routine would.

The previous claim/IP-only query append in BuildTargetUrl is removed and
folded into the unified mechanism. Behavior change: claims/IP now follow
RequestParamType (unchanged for GET/QueryString — still query; for
BodyJson endpoints they now go to the body).

Notes: body merge only for JSON content types (multipart/non-JSON
forwarded verbatim); only expanded per-field HTTP-type params forwarded.

Tests cover GET-query, POST-body (typed), param_type-query on POST, and
resolved-param forwarding; existing claim/IP proxy tests pass unchanged.
Full suite green (2288). See changelog/v3.18.1.md.

Also adds a Claude Code skill bundle (.claude/skills/npgsqlrest/) — a usage
guide plus full annotation and configuration references generated from
--annotations/--config — and a README section on installing it.
---
 .claude/skills/npgsqlrest/SKILL.md            |  238 ++
 .../npgsqlrest/annotations-reference.md       |  355 ++
 .../npgsqlrest/configuration-reference.jsonc  | 2949 +++++++++++++++++
 NpgsqlRest/Proxy/ProxyRequestHandler.cs       |  226 +-
 .../ProxyTests/ProxyHttpTypeProbeTest.cs      |  272 ++
 README.md                                     |   16 +
 changelog/v3.18.0.md                          |    2 +-
 changelog/v3.18.1.md                          |   40 +
 npm/package.json                              |    2 +-
 version.txt                                   |    2 +-
 10 files changed, 4066 insertions(+), 36 deletions(-)
 create mode 100644 .claude/skills/npgsqlrest/SKILL.md
 create mode 100644 .claude/skills/npgsqlrest/annotations-reference.md
 create mode 100644 .claude/skills/npgsqlrest/configuration-reference.jsonc
 create mode 100644 NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs
 create mode 100644 changelog/v3.18.1.md

diff --git a/.claude/skills/npgsqlrest/SKILL.md b/.claude/skills/npgsqlrest/SKILL.md
new file mode 100644
index 00000000..2cb12cd5
--- /dev/null
+++ b/.claude/skills/npgsqlrest/SKILL.md
@@ -0,0 +1,238 @@
+---
+name: npgsqlrest
+description: Build and modify REST APIs with NpgsqlRest — exposing PostgreSQL as HTTP endpoints from two sources (database functions/procedures/tables/views, and plain .sql files), driven by SQL comment annotations (no C# needed). Use when working in an NpgsqlRest project: writing or changing endpoint SQL (functions or .sql files), comment annotations (HTTP routing, authorize, cached, proxy, HTTP Custom Types, SSE, MCP, upload), appsettings.json config, or running/troubleshooting the `npgsqlrest` client.
+---
+
+# Working with NpgsqlRest
+
+NpgsqlRest auto-generates a REST API from PostgreSQL. You write SQL and **annotate it with comments**; NpgsqlRest turns each annotated object into an HTTP endpoint at startup. There is **no controller/model/mapping layer and no C# to write** — behavior is declared in SQL comments and `appsettings.json`.
+
+## Mental model (read this first)
+
+- An endpoint comes from one of **two sources** (see below): a **database routine** (function/procedure/table/view) or a **`.sql` file**. Both use the **same annotation vocabulary**; only where you write the annotation differs.
+- An endpoint is created when its comment/file carries an `HTTP` tag (or a plugin tag like `mcp`), under the default `CommentsMode: OnlyAnnotated`.
+- The result is serialized to JSON automatically (a set → array; `@single` → one object; `@raw` → plain text; multi-statement `.sql` → object keyed per statement).
+- Auth, caching, rate limiting, headers, validation, proxy, outbound HTTP, SSE, MCP — all are **comment annotations**.
+- `appsettings.json` configures the server, connection, auth, and which sources/schemas/objects are exposed.
+
+## Authoritative sources — prefer these over guessing
+
+The annotation/config surface is large and version-dependent. In order of preference:
+
+1. **Bundled with this skill** (offline, complete — these files sit next to this `SKILL.md`):
+   - `annotations-reference.md` — every comment annotation (name, aliases, syntax, description).
+   - `configuration-reference.jsonc` — the full `appsettings.json` with every option and inline comments.
+2. **The installed binary** (authoritative for the exact version in use):
+   ```bash
+   npgsqlrest --annotations    # every supported annotation, as JSON
+   npgsqlrest --config         # full default appsettings.json (every option, commented)
+   npgsqlrest --validate       # test DB connectivity + that endpoints build (incl. .sql Describe)
+   npgsqlrest --version
+   ```
+3. **Online:** docs at <https://npgsqlrest.github.io> (e.g. `/guide/annotations`, `/guide/sql-files`, `/annotations/<name>`, `/config/<section>`); source & issues at <https://github.com/NpgsqlRest/NpgsqlRest>.
+
+The two bundled files were generated from `--annotations` / `--config`. If your installed `npgsqlrest` version differs, trust the binary (or regenerate them with those commands).
+
+## The two endpoint sources
+
+Both are independently enabled; you can use either or **both together** (a `.sql` file can call a function; an HTTP Custom Type can reference any endpoint regardless of source).
+
+### 1. Database routines (functions / procedures / tables / views)
+
+Annotations live in the PostgreSQL **object comment**. NpgsqlRest reads the catalog at startup. Nothing extra to enable beyond schema selection.
+
+```sql
+create function get_users(_active boolean default true)
+returns setof users language sql as $$
+  select * from users where active = _active;
+$$;
+
+comment on function get_users(boolean) is '
+HTTP GET /api/users
+@authorize
+@cached _active
+@cache_expires_in 5m';
+```
+
+- Default path derives from the routine name (kebab-cased, under `UrlPathPrefix`, default `/api`).
+- Parameters auto-map by name; `@param` renames/retypes/defaults them.
+- Param location (query vs JSON body) is governed by `@request_param_type` / defaults, **not** the HTTP verb (a POST can use query params).
+- **Project helper pattern:** some projects wrap the comment in a helper like `call myschema.annotate('schema.func', 'HTTP POST', 'authorize manager', ...)` that just builds the `comment on ...` string. Follow the project's convention — the mechanism is always the routine comment.
+
+### 2. SQL files (`.sql`)
+
+Annotations live in **leading line comments** (`-- ...` or `/* ... */`) in a `.sql` file. No `CREATE FUNCTION`, no `COMMENT ON`. Enable the source and point it at a glob:
+
+```json
+{ "NpgsqlRest": { "SqlFileSource": { "Enabled": true, "FilePattern": "sql/**/*.sql" } } }
+```
+
+```sql
+-- sql/get-reports.sql
+-- HTTP GET
+-- @param $1 from_date
+-- @param $2 to_date
+-- @authorize
+select id, title, created_at
+from reports
+where created_at between $1 and $2;
+```
+
+- **Filename → path**: `get-reports.sql` → `/api/get-reports`.
+- **Startup Describe = static type checking.** Each statement is parsed/described against the live DB (no execution); SQL errors fail startup (`ErrorMode: Exit`; set `Skip` to log-and-continue). This catches `column does not exist` etc. before serving.
+- **Parameters are positional** (`$1, $2`). `@param $N name [type] [default ...]` names/retypes/defaults them (positional params have no native DEFAULT). `@define_param name [type]` creates a *virtual* param (for placeholders/claims; not bound to SQL).
+- **Verb inference** when no `HTTP` tag: `SELECT`→GET, `INSERT`→PUT, `UPDATE`→POST, `DELETE`→DELETE, `DO`→POST (most destructive wins). Explicit `-- HTTP POST` overrides.
+- **Multi-command files** (statements split on `;`) run in **one batch / round-trip** and return a JSON object keyed per statement. Positional annotations apply to the *next* statement (or inline after `;`):
+  - `@result name` — name the result key (default `result1`, `result2`, …)
+  - `@single` — that statement returns one object instead of an array
+  - `@skip` — run it but exclude from the response
+  - `@void` — whole endpoint returns **204 No Content** (all statements run for side effects only)
+- **`@returns <type|scalar|void>`** — skip Describe for a statement and resolve columns from a type instead. Needed when a statement references objects that don't exist at startup (e.g. a temp table built in a `DO` block).
+- **`DO` block limits** (PostgreSQL, not NpgsqlRest): `DO` blocks can't take `$N` params or return values. Bridge with `set_config(key, $1, true)` + `current_setting()`, or a temp table + `@returns`. For real procedural logic, prefer a function.
+- Config knobs: `CommentScope` (`All` | `Header`), `UnnamedSingleColumnSet` (single-column → flat array), `ResultPrefix`, `SkipNonQueryCommands`.
+
+### Functions vs SQL files — when to use which
+
+- **SQL files**: declarative queries, multi-statement workflows, teams that prefer plain `.sql` over DDL.
+- **Functions**: procedural logic, native params/returns, `assert`-based tests in repeatable migrations, optimizer hints (`STABLE`/`COST`/`ROWS`), overloading.
+
+Everything below (annotations, HTTP types, proxy, caching, auth, SSE, MCP) works **identically in both sources**.
+
+## Annotation cheat-sheet (grouped)
+
+Same annotations apply to functions and `.sql` files. Confirm exact syntax/aliases with `npgsqlrest --annotations`.
+
+**Routing / exposure**
+- `HTTP [METHOD] [/path]` — expose. `@path /x` — override path. `@disabled`/`@enabled`. `@internal` — exists but no public route (reachable via proxy / HTTP-type self-call). `@tags a,b`, `@openapi …`.
+
+**Auth**
+- `@authorize` (any authenticated) / `@authorize role1, role2`. `@allow_anonymous` (aliases `@anonymous`, `@anon`). `@login` / `@logout`. `@user_context` (claims → PG context + headers), `@user_parameters` (claims → params). `@security_sensitive` (keep param values out of logs).
+
+**Params / request**
+- `@param $1 name [type] [default …]` (rename/retype/default). `@define_param name [type]` (virtual, SQL-file). `@request_param_type query_string | body_json`. `@body_parameter_name _x` (one param = raw body). `@request_headers_mode parameter` + `@request_headers_parameter_name _headers`. Resolved param: a line `_token = select api_token from tokens where user_name = {_name}` fills `_token` server-side (client can't override).
+
+**Response shaping**
+- `@single`, `@raw` (+ `@separator`, `@new_line`, `@columns`), `@result <name>` (multi-command key), `@skip`, `@void` (204), `@nested` (keep composites nested), `@returns <type>` (SQL-file, skip Describe). Header lines like `Content-Type: text/csv`.
+
+**Caching** (server-side response cache)
+- `@cached [p1, p2, …]` — **always list the key params explicitly** (a bare `@cached` keys on the endpoint only). `@cache_expires_in 30s|5m|1h` (alias `@cache_expires`). `@cache_profile name` (backend + defaults from `CacheOptions:Profiles`).
+
+**Other**
+- `@rate_limiter_policy name`. `@command_timeout 30s`. `@connection Name` (multi-connection). `@buffer_rows N`. `@validate _email using required, email`. `@error_code_policy 23505 -> 409`. `@upload [for csv|excel|file_system|large_object]`.
+
+## HTTP Custom Types (outbound HTTP from SQL)
+
+A **composite type** whose comment defines an outbound HTTP request. When a routine (or `.sql` param) is of that type, NpgsqlRest performs the call **before** running the endpoint and fills the composite fields.
+
+```sql
+create type books_api as (body text, status_code int, success boolean, error_message text);
+
+-- directives go BEFORE the request line
+comment on type books_api is '@timeout 30s
+@retry_delay 1s, 2s on 429, 503
+@cache 5m
+GET https://books.toscrape.com/
+Accept: text/html';
+```
+
+- Directives `@timeout` / `@retry_delay` / `@cache` may appear before the request line OR after the headers (both work since 3.18.0; before is safest).
+- Response fields (names configurable in `HttpClientOptions`): `body`, `status_code`, `content_type`, `headers` (json), `success`, `error_message`.
+- `@cache <interval>` (3.18.0+): caches the outbound response — **GET only, 2xx only**, stampede-coalesced; globally toggled by `HttpClientOptions.CacheEnabled`.
+- Placeholders `{name}` in URL/headers/body substitute from params, resolved-param expressions, allow-listed env vars.
+- A relative URL (`GET /api/other`) is a **self-call** to another endpoint with no HTTP round-trip — give a function several HTTP-type params and they fire concurrently.
+- Requires `HttpClientOptions.Enabled = true`.
+
+## Proxy (reverse proxy endpoints)
+
+`@proxy [METHOD] [host]` forwards upstream (target = `host + incoming path + query`; host from annotation or `ProxyOptions.Host`).
+
+- **Passthrough** (no proxy-response params): function body is **not executed**; upstream response streamed back; no DB connection.
+- **Transform** (routine declares `_proxy_status_code int`, `_proxy_body text`, `_proxy_success boolean`, `_proxy_headers json`, `_proxy_content_type text`, `_proxy_error_message text`): NpgsqlRest proxies, binds the response into those params, runs the function, returns its result.
+- **Automatic params forwarded upstream** (3.18.1+): user claims, IP, HTTP-Custom-Type fields, resolved-param expressions are forwarded in the endpoint's native shape (query for `QueryString` endpoints, merged JSON body for `BodyJson`), honoring `@body_parameter_name`.
+- Requires `ProxyOptions.Enabled = true`.
+
+## SSE (server-sent events)
+
+A long-running routine streams progress via `RAISE INFO/NOTICE`. Annotate with `@sse` (or a project's `sse_publish`/`sse_subscribe` split) and a scope (`all` | `authorize` | `matching`). Per-recipient targeting: `raise info 'msg' using hint = format('authorize %s', _user_id)`. A subscribe-only endpoint's body never runs. A cache hit skips execution → no RAISE → no broadcast (correct).
+
+## MCP (Model Context Protocol)
+
+`@mcp [text]` exposes a routine as an MCP tool. A bare `@mcp` with **no** HTTP tag = MCP-only (no public route). `@mcp_description` / `@mcp_name` refine it. Served at `/mcp` when the `NpgsqlRest.Mcp` plugin is loaded.
+
+## Auth pattern (login → claims)
+
+A login endpoint is a routine annotated `@login` returning a status/claims row; NpgsqlRest reads configured columns and issues the cookie/token:
+
+```sql
+-- returns (status, scheme, user_id, user_name, user_roles, message) by convention
+comment on function auth_login(text, text) is 'HTTP POST
+@login
+@allow_anonymous
+@rate_limiter_policy login_throttle
+@security_sensitive';
+```
+
+- `status` 200 → success (other codes → that HTTP status); `scheme` picks the auth scheme/cookie.
+- Column→claim mapping in `AuthenticationOptions` (`StatusColumnName`, `SchemeColumnName`, role/name/id claim columns).
+- **Inject identity from claims, never trust client-supplied IDs.** Declare params like `_user_id text = null`, `_user_roles text[] = '{}'` and map them via `AuthenticationOptions.ParameterNameClaimsMapping` / `IpAddressParameterName`. NpgsqlRest fills them from the authenticated principal.
+- Use `security definer` on API functions and still permission-check inside (`assert _user_roles && array['admin']` …).
+
+## Configuration (appsettings.json)
+
+`npgsqlrest --config` prints the full annotated default. Most-used sections:
+
+```jsonc
+{
+  "ConnectionStrings": { "Default": "Host={PGHOST};Port={PGPORT};Database={PGDATABASE};Username={APP_USER};Password={APP_PASSWORD}" },
+  "Urls": "http://0.0.0.0:8080",
+  "Auth": { "CookieAuth": true, "CookieName": "app", "CookieValid": "365 days" /* + Jwt/Bearer/Passkey/External */ },
+  "NpgsqlRest": {
+    "IncludeSchemas": ["myapi"],
+    "CommentsMode": "OnlyAnnotated",
+    "UrlPathPrefix": "/api",
+    "RequiresAuthorization": true,
+    "KebabCaseUrls": true, "CamelCaseNames": true,
+    "AuthenticationOptions": { /* status/scheme/claim columns, ParameterNameClaimsMapping, IpAddressParameterName */ },
+    "SqlFileSource": { "Enabled": false, "FilePattern": "sql/**/*.sql", "ErrorMode": "Exit", "CommentScope": "All" }
+  },
+  "CacheOptions": { "Enabled": true, "Type": "Memory" /* or Redis / Hybrid */, "Profiles": { } },
+  "HttpClientOptions": { "Enabled": false /* + CacheEnabled, response field names */ },
+  "ProxyOptions": { "Enabled": false, "Host": null },
+  "RateLimiterOptions": { "Enabled": false, "Policies": { } },
+  "Log": { "MinimalLevels": { "NpgsqlRest": "Information" } }
+}
+```
+
+- **Two sources, independently enabled:** database routines (always available via the catalog, filtered by `IncludeSchemas`/`SchemaSimilarTo`/`NameSimilarTo`/`CommentsMode`) and `NpgsqlRest:SqlFileSource` (off by default; needs `Enabled` + `FilePattern`).
+- `{ENV_VAR}` placeholders are substituted from environment variables at startup.
+- `--config <file>` loads a specific file; multiple files overlay (later wins): `npgsqlrest ./appsettings.json ./appsettings.development.json`.
+- Dev override file commonly enables `Debug` logging, TypeScript client codegen, and `.http` export.
+
+## Running
+
+```bash
+npgsqlrest                                  # appsettings.json in cwd
+npgsqlrest ./config/appsettings.json ./config/appsettings.development.json
+npgsqlrest --connectionstrings:default="Host=localhost;Database=db;Username=postgres;Password=postgres"
+npgsqlrest --log:minimallevels:npgsqlrest=debug    # see every annotation parsed
+```
+
+Install via the GitHub release binary, `npm install -g npgsqlrest`, or the `vbilopav/npgsqlrest` Docker image.
+
+## Project conventions worth copying (from real projects)
+
+- **One schema for the API** (`IncludeSchemas: ["myapi"]`); internal helpers in another schema.
+- **Organize by feature/domain**, not by migration type. Define endpoints as **repeatable migrations** (`R__<action>_<entity>.sql`) so re-running is idempotent — or as plain `.sql` files under the source glob.
+- **Dev codegen:** enable the TypeScript client generator + `.http` export in the dev override file only; commit the generated client.
+- **Two-layer caching:** a `Cache-Control` header for the browser + server-side `@cached`/`@cache_profile` for cross-client dedup; match the windows.
+- **Cache-key discipline:** include every param that changes the result (and `_user_id` for per-user data); omit `_user_id` for shared results so all users hit one entry. Add a `_cache_bust`/`_param_hash` param to force misses after writes.
+
+## Gotchas
+
+- **`@cached` needs an explicit param list** — bare `@cached` keys on the endpoint only (a common silent bug).
+- **Verb ≠ param location** — use `@request_param_type`, not the method, to reason about where params come from / are forwarded.
+- **HTTP-type directives** are safest **before the request line**.
+- **Passthrough proxy doesn't run the function** — declare proxy-response params (transform mode) if you need the body executed.
+- **`HttpClientOptions.Enabled` / `ProxyOptions.Enabled` / `SqlFileSource.Enabled`** must be true for those features. `@cache` on a non-GET HTTP type is ignored with a warning.
+- **SQL files:** annotations are in `--`/`/* */` comments; params are positional `$N` (name via `@param`); a startup Describe error fails boot unless `ErrorMode: Skip`; use `@returns` for statements over not-yet-existing objects (temp tables); `DO` blocks can't take `$N` or return values.
+- After changing an annotation, re-run with `--log:minimallevels:npgsqlrest=debug` (or `--validate`) to confirm it parsed as intended.
diff --git a/.claude/skills/npgsqlrest/annotations-reference.md b/.claude/skills/npgsqlrest/annotations-reference.md
new file mode 100644
index 00000000..d9c612ca
--- /dev/null
+++ b/.claude/skills/npgsqlrest/annotations-reference.md
@@ -0,0 +1,355 @@
+# NpgsqlRest — Full Annotation Reference
+
+Every comment annotation, generated from `npgsqlrest --annotations` (NpgsqlRest v3.18.1).
+Annotations apply to both endpoint sources (database routines via `comment on`, and `.sql` files via leading `--` comments). The `@` prefix is optional. Regenerate with `npgsqlrest --annotations`.
+
+## `http`
+
+- **Aliases:** http
+- **Syntax:** `http [GET|POST|PUT|DELETE] [path]`
+
+Enable endpoint and configure HTTP method and/or path. Required (for HTTP exposure) when CommentsMode is OnlyAnnotated (or its alias OnlyWithHttpTag).
+
+## `path`
+
+- **Aliases:** path
+- **Syntax:** `path <url_path>`
+
+Override the endpoint URL path.
+
+## `param_type`
+
+- **Aliases:** request_param_type, param_type
+- **Syntax:** `param_type [query_string|query|body_json|body]`
+
+Set request parameter type to query string or JSON body.
+
+## `authorize`
+
+- **Aliases:** authorize, authorized, requires_authorization
+- **Syntax:** `authorize [role1, role2, ...]`
+
+Require authorization, optionally restricting to specific roles.
+
+## `allow_anonymous`
+
+- **Aliases:** allow_anonymous, anonymous, allow_anon, anon
+- **Syntax:** `allow_anonymous`
+
+Allow unauthenticated access to this endpoint.
+
+## `login`
+
+- **Aliases:** login, signin
+- **Syntax:** `login`
+
+Mark endpoint as a login/authentication endpoint.
+
+## `logout`
+
+- **Aliases:** logout, signout
+- **Syntax:** `logout`
+
+Mark endpoint as a logout endpoint.
+
+## `raw`
+
+- **Aliases:** raw, raw_mode, raw_results
+- **Syntax:** `raw`
+
+Return raw results without JSON formatting.
+
+## `separator`
+
+- **Aliases:** separator, raw_separator
+- **Syntax:** `separator <value>`
+
+Set the value separator for raw mode output.
+
+## `new_line`
+
+- **Aliases:** new_line, raw_new_line
+- **Syntax:** `new_line <value>`
+
+Set the line separator for raw mode output.
+
+## `columns`
+
+- **Aliases:** columns, names, column_names
+- **Syntax:** `columns`
+
+Include column names as the first row in raw output.
+
+## `buffer_rows`
+
+- **Aliases:** buffer_rows, buffer
+- **Syntax:** `buffer_rows <number>`
+
+Set the number of rows to buffer before sending response.
+
+## `cached`
+
+- **Aliases:** cached
+- **Syntax:** `cached [param1, param2, ...]`
+
+Enable response caching, optionally specifying cache key parameters.
+
+## `cache_expires`
+
+- **Aliases:** cache_expires, cache_expires_in
+- **Syntax:** `cache_expires <interval>`
+
+Set cache expiration time (PostgreSQL interval format).
+
+## `cache_profile`
+
+- **Aliases:** cache_profile
+- **Syntax:** `cache_profile <name>`
+
+Select a named cache profile defined in CacheOptions.Profiles. The profile supplies the cache backend, default expiration, default key parameters, and per-parameter skip conditions. Implies caching even without @cached. Existing @cached and @cache_expires annotations override the profile's defaults. Unknown profile names cause startup to fail.
+
+## `connection_name`
+
+- **Aliases:** connection, connection_name
+- **Syntax:** `connection_name <name>`
+
+Use a specific named connection string for this endpoint.
+
+## `timeout`
+
+- **Aliases:** command_timeout, timeout
+- **Syntax:** `timeout <interval>`
+
+Set command execution timeout (PostgreSQL interval format).
+
+## `request_headers_mode`
+
+- **Aliases:** request_headers_mode, request_headers
+- **Syntax:** `request_headers [ignore|context|parameter]`
+
+Control how HTTP request headers are passed to the routine.
+
+## `request_headers_parameter_name`
+
+- **Aliases:** request_headers_parameter_name, request_headers_param_name, request-headers-param-name
+- **Syntax:** `request_headers_parameter_name <name>`
+
+Set the parameter name for request headers when mode is parameter.
+
+## `body_parameter_name`
+
+- **Aliases:** body_parameter_name, body_param_name
+- **Syntax:** `body_parameter_name <name>`
+
+Set the parameter name for the JSON body content.
+
+## `response_null_handling`
+
+- **Aliases:** response_null_handling, response_null
+- **Syntax:** `response_null [empty_string|null_literal|no_content|204]`
+
+Control how NULL return values are rendered in responses.
+
+## `query_string_null_handling`
+
+- **Aliases:** query_string_null_handling, query_null_handling, query_string_null, query_null
+- **Syntax:** `query_null [empty_string|null_literal|ignore]`
+
+Control how NULL query string parameters are handled.
+
+## `security_sensitive`
+
+- **Aliases:** sensitive, security, security_sensitive
+- **Syntax:** `security_sensitive`
+
+Mark endpoint as security-sensitive (suppresses logging of parameters).
+
+## `user_context`
+
+- **Aliases:** user_context
+- **Syntax:** `user_context`
+
+Pass authenticated user context to the routine via connection settings.
+
+## `user_parameters`
+
+- **Aliases:** user_parameters, user_params
+- **Syntax:** `user_parameters`
+
+Map user claims to routine parameters.
+
+## `upload`
+
+- **Aliases:** upload
+- **Syntax:** `upload [for handler1, handler2, ...]`
+
+Enable file upload for this endpoint, optionally specifying upload handlers.
+
+## `param`
+
+- **Aliases:** parameter, param
+- **Syntax:** `param <name> is hash of <other_name> | param <name> is upload metadata | param <original> <new_name> [type] | param <original> is <new_name> [type]`
+
+Configure parameter behavior: hash computation, upload metadata binding, or rename/retype. Rename forms: 'param $1 user_id', 'param $1 user_id integer', 'param $1 is user_id', 'param _old_name better_name'. Works on all endpoint types.
+
+## `sse_path`
+
+- **Aliases:** sse, sse_path, sse_events_path
+- **Syntax:** `sse_path [path] [on info|notice|warning]`
+
+Enable Server-Sent Events streaming with optional path and notice level.
+
+## `sse_level`
+
+- **Aliases:** sse_level, sse_events_level
+- **Syntax:** `sse_level [info|notice|warning]`
+
+Set the PostgreSQL notice level for SSE events.
+
+## `sse_scope`
+
+- **Aliases:** sse_scope, sse_events_scope
+- **Syntax:** `sse_scope [all|authorize|matching] [role1, role2, ...]`
+
+Set the broadcast scope for SSE events.
+
+## `basic_auth`
+
+- **Aliases:** basic_authentication, basic_auth
+- **Syntax:** `basic_auth [username] [password]`
+
+Enable HTTP Basic Authentication for this endpoint.
+
+## `basic_auth_realm`
+
+- **Aliases:** basic_authentication_realm, basic_auth_realm, realm
+- **Syntax:** `basic_auth_realm <realm>`
+
+Set the authentication realm for Basic Auth challenges.
+
+## `basic_auth_command`
+
+- **Aliases:** basic_authentication_command, basic_auth_command, challenge_command
+- **Syntax:** `basic_auth_command <sql_command>`
+
+Set a custom SQL command for Basic Auth credential validation.
+
+## `retry_strategy`
+
+- **Aliases:** retry_strategy_name, retry_strategy, retry
+- **Syntax:** `retry_strategy <name>`
+
+Apply a named retry strategy for transient database errors.
+
+## `rate_limiter`
+
+- **Aliases:** rate_limiter_policy_name, rate_limiter_policy, rate_limiter
+- **Syntax:** `rate_limiter <policy_name>`
+
+Apply a named rate limiting policy to this endpoint.
+
+## `error_code_policy`
+
+- **Aliases:** error_code_policy_name, error_code_policy, error_code
+- **Syntax:** `error_code_policy <name>`
+
+Apply a named error code mapping policy for PostgreSQL error codes.
+
+## `validate`
+
+- **Aliases:** validate, validation
+- **Syntax:** `validate <param_name> using <rule_name>`
+
+Add parameter validation using a named validation rule.
+
+## `proxy`
+
+- **Aliases:** proxy, reverse_proxy
+- **Syntax:** `proxy [GET|POST|PUT|DELETE|PATCH] [host_url]`
+
+Configure endpoint as a reverse proxy.
+
+## `proxy_out`
+
+- **Aliases:** proxy_out, forward_proxy
+- **Syntax:** `proxy_out [GET|POST|PUT|DELETE|PATCH] [host_url]`
+
+Execute function first, then forward result body to upstream proxy service.
+
+## `nested_json`
+
+- **Aliases:** nested, nested_json, nested_composite
+- **Syntax:** `nested_json`
+
+Serialize composite type columns as nested JSON objects.
+
+## `tags`
+
+- **Aliases:** for, tags, tag
+- **Syntax:** `for tag1, tag2, ...`
+
+Filter endpoint availability by tags.
+
+## `disabled`
+
+- **Aliases:** disabled
+- **Syntax:** `disabled [tag1, tag2, ...]`
+
+Disable this endpoint, optionally only for specific tags.
+
+## `enabled`
+
+- **Aliases:** enabled
+- **Syntax:** `enabled [tag1, tag2, ...]`
+
+Enable this endpoint, optionally only for specific tags.
+
+## `internal`
+
+- **Aliases:** internal, internal_only
+- **Syntax:** `internal`
+
+Mark endpoint as internal-only. Not exposed as an HTTP route, only accessible via self-referencing calls (proxy, HTTP client types).
+
+## `encrypt`
+
+- **Aliases:** encrypt, encrypted, protect, protected
+- **Syntax:** `encrypt [param1, param2, ...]`
+
+Encrypt parameter values using the default data protector before sending to PostgreSQL. Without arguments, encrypts all text parameters.
+
+## `decrypt`
+
+- **Aliases:** decrypt, decrypted, unprotect, unprotected
+- **Syntax:** `decrypt [column1, column2, ...]`
+
+Decrypt result column values using the default data protector before returning to the client. Without arguments, decrypts all text columns.
+
+## `custom_parameter`
+
+- **Aliases:** 
+- **Syntax:** `key = value`
+
+Define a custom parameter as key-value pair (separated by =).
+
+## `header`
+
+- **Aliases:** 
+- **Syntax:** `Header-Name: header-value`
+
+Add a response header (separated by :).
+
+## `resultN`
+
+- **Aliases:** result1, result2, result3
+- **Syntax:** `resultN <name> | resultN is <name>`
+
+Rename a result key in multi-command SQL file responses. N is the 1-based command index. Example: '@result1 validate' renames the first result from 'result1' to 'validate'. SQL file source only.
+
+## `define_param`
+
+- **Aliases:** define_param
+- **Syntax:** `define_param <name> [type]`
+
+Define a virtual parameter that exists for HTTP matching and claim mapping but is NOT bound to the PostgreSQL command. Useful for SQL file endpoints where you need parameters for comment placeholders or claim mapping without referencing them in SQL. Default type is text. SQL file source only.
+
diff --git a/.claude/skills/npgsqlrest/configuration-reference.jsonc b/.claude/skills/npgsqlrest/configuration-reference.jsonc
new file mode 100644
index 00000000..f986c9e0
--- /dev/null
+++ b/.claude/skills/npgsqlrest/configuration-reference.jsonc
@@ -0,0 +1,2949 @@
+// NpgsqlRest — FULL configuration reference (every option, with inline comments).
+// Generated verbatim from: npgsqlrest --config   (NpgsqlRest v3.18.1)
+// This is the source of truth for configuration. Regenerate with: npgsqlrest --config
+
+{
+  //
+  // The application name used to set the application name property in connection string by "NpgsqlRest.SetApplicationNameInConnection" or the "NpgsqlRest.UseJsonApplicationName" settings.
+  // It is the name of the top-level directory if set to null.
+  //
+  "ApplicationName": null,
+
+  //
+  // Production or Development
+  //
+  "EnvironmentName": "Production",
+
+  //
+  // Specify the urls the web host will listen on. See https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.hosting.hostingabstractionswebhostbuilderextensions.useurls?view=aspnetcore-8.0
+  //
+  "Urls": "http://localhost:8080",
+
+  //
+  // Logs at startup, format placeholders:
+  // {time} - startup time
+  // {urls} - listening on urls
+  // {version} - current version
+  // {environment} - EnvironmentName
+  // {application} - ApplicationName
+  //
+  // Note: This message is logged at Information level. To disable this message, set to empty string.
+  //
+  "StartupMessage": "Started in {time}, listening on {urls}, version {version}",
+
+  //
+  // Configuration settings
+  //
+  "Config": {
+    //
+    // Add the environment variables to configuration.
+    // When enabled, environment variables will override the settings in this configuration file but can be overridden by command line arguments.
+    // Complex hierarchical keys can be defined using double underscore as a separator. 
+    // For example, "ConnectionStrings__Default" environment variable will override the "ConnectionStrings.Default" setting in this configuration file.
+    //
+    "AddEnvironmentVariables": false,
+    //
+    // When set, configuration values will be parsed for environment variables in the format {ENV_VAR_NAME}
+    // and replaced with the value of the environment variable when available.
+    //
+    "ParseEnvironmentVariables": true,
+    //
+    // Path to a .env file containing environment variables.
+    // When AddEnvironmentVariables or ParseEnvironmentVariables is true and this file exists,
+    // variables from this file will be loaded and made available for configuration parsing.
+    // Format: KEY=VALUE (one per line)
+    //
+    "EnvFile": null,
+    //
+    // Validate configuration keys against known defaults at startup.
+    // "Ignore" - no validation
+    // "Warning" - log warnings for unknown keys, continue startup (default)
+    // "Error" - log errors for unknown keys and exit
+    //
+    "ValidateConfigKeys": "Warning"
+  },
+
+  //
+  // List of named connection strings to PostgreSQL databases.
+  // The "Default" connection string is used when no connection name is specified.
+  // For connection string definition see https://www.npgsql.org/doc/connection-string-parameters.html
+  //
+  "ConnectionStrings": {
+    "Default": "Host={PGHOST};Port=5432;Database={PGDATABASE};Username={PGUSER};Password={PGPASSWORD}"
+  },
+
+  //
+  // Additional connection settings and options.
+  //
+  "ConnectionSettings": {
+    //
+    // Sets the ApplicationName connection property in the connection string to the value of the ApplicationName configuration.
+    // Note: This option is ignored if the UseJsonApplicationName option is enabled.
+    //
+    "SetApplicationNameInConnection": true,
+    //
+    // Sets the ApplicationName connection property dynamically on every request in the following format: 
+    // {"app":"<ApplicationName>","uid":"<user_id>","id":"<NpgsqlRest.ExecutionIdHeaderName>"}
+    // Note: The ApplicationName connection property is limited to 64 characters.
+    //
+    "UseJsonApplicationName": false,
+    //
+    // Test any connection string before initializing the application and using it. The connection string is tested by opening and closing the connection.
+    //
+    "TestConnectionStrings": true,
+    //
+    // Connection open retry options.
+    //
+    "RetryOptions": {
+      "Enabled": true,
+      //
+      // Retry sequence in seconds. Accepts decimal numbers (0.25 is quarter of a second). The length of the array determines the maximum number of retries.
+      //
+      "RetrySequenceSeconds": [1, 3, 6, 12],
+      //
+      // Error codes that will trigger a retry when opening a connection. See https://www.postgresql.org/docs/current/errcodes-appendix.html
+      //
+      "ErrorCodes": [
+        "08000", "08003", "08006", "08001", "08004", // Connection failure codes
+        "55P03", // Lock not available
+        "55006", // Object in use
+        "53300", // Too many connections
+        "57P03", // Cannot connect now
+        "40001"  // Serialization failure (can be retried)
+      ]
+    },
+    //
+    // The connection name in ConnectionStrings configuration that will be used to execute the metadata query. If this value is null, the default connection string will be used.
+    //
+    "MetadataQueryConnectionName": null,
+    //
+    // Set the search path to this schema before executing the metadata query function.
+    // When null (default), no search path is set and the server's default search path is used.
+    //
+    // This is needed when using non superuser connection roles with limited schema access and mapping the metadata function to a specific schema.
+    // If the connection string contains the same "Search Path=" it will be skipped.
+    //
+    "MetadataQuerySchema": null,
+    // Any: Any successful connection is acceptable.
+    // Primary: Server must not be in hot standby mode (pg_is_in_recovery() must return false).
+    // Standby: Server must be in hot standby mode (pg_is_in_recovery() must return true).
+    // PreferPrimary: First try to find a primary server, but if none of the listed hosts is a primary server, try again in Any mode.
+    // PreferStandby: First try to find a standby server, but if none of the listed hosts is a standby server, try again in Any mode.
+    // ReadWrite: Session must accept read-write transactions by default (that is, the server must not be in hot standby mode and the default_transaction_read_only parameter must be off).
+    // ReadOnly: Session must not accept read-write transactions by default (the converse).
+    // see https://www.npgsql.org/doc/failover-and-load-balancing.html
+    "MultiHostConnectionTargets": {
+      // all connections use the same target mode
+      "Default": "Any",
+      // per connection overrides { "name": "Primary|Standby|Any|PreferPrimary|PreferStandby|ReadWrite|ReadOnly" } 
+      "ByConnectionName": {  }
+    }
+  },
+
+  //
+  // Enable to invoke UseKestrelHttpsConfiguration. See https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderkestrelextensions.usekestrelhttpsconfiguration?view=aspnetcore-8.0
+  //
+  "Ssl": {
+    "Enabled": false,
+    //
+    // Adds middleware for redirecting HTTP Requests to HTTPS. See https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.builder.httpspolicybuilderextensions.usehttpsredirection?view=aspnetcore-8.0
+    //
+    "UseHttpsRedirection": true,
+    //
+    // Adds middleware for using HSTS, which adds the Strict-Transport-Security header. See https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.builder.hstsbuilderextensions.usehsts?view=aspnetcore-2.1
+    //
+    "UseHsts": true
+  },
+
+  //
+  // Data protection settings. Encryption/decryption settings for Auth Cookies, Antiforgery tokens and custom data protection needs.
+  //
+  "DataProtection": {
+    "Enabled": false,
+    //
+    // Set to null to use the current "ApplicationName" value.
+    // This value determines encryption type or class. Meaning, different application names will not be able to decrypt each other's data.
+    //
+    "CustomApplicationName": null,
+    //
+    // Sets the default lifetime in days of keys created by the data protection system.
+    // Represents a number of days how long before keys are rotated.
+    //
+    "DefaultKeyLifetimeDays": 90,
+    //
+    // Data protection location: "Default", "FileSystem" or "Database"
+    //
+    // Note: When running on Linux, using Default location means keys will not be persisted. 
+    // When keys are lost on restart, encrypted tokens (auth) will also not work on restart.
+    // Linux users should use FileSystem or Database storage.
+    //
+    "Storage": "Default",
+    //
+    // FileSystem storage path. Set to a valid path when using FileSystem.
+    // Note: When running in Docker environment, the path must be a Docker volume path to persist the keys.
+    //
+    "FileSystemPath": "./data-protection-keys",
+    //
+    // GetAllElements database command. Expected to return rows with a single column of type text.
+    //
+    "GetAllElementsCommand": "select get_data_protection_keys()",
+    //
+    // StoreElement database command. Receives two parameters: name and data of type text. Doesn't return anything.
+    //
+    "StoreElementCommand": "call store_data_protection_keys($1,$2)",
+    //
+    // Configure encryption algorithms for data protection keys or null to use the default algorithm.
+    // Values: AES_128_CBC, AES_192_CBC, AES_256_CBC, AES_128_GCM, AES_192_GCM, AES_256_GCM
+    //
+    "EncryptionAlgorithm": null,
+    //
+    // Configure validation algorithms for data protection keys or null to use the default algorithm.
+    // Values: HMACSHA256, HMACSHA512
+    //
+    "ValidationAlgorithm": null,
+    //
+    // Key encryption method: "None", "Certificate", or "Dpapi" (Windows only)
+    // None: Keys are not encrypted at rest (default)
+    // Certificate: Keys are encrypted using an X.509 certificate
+    // Dpapi: Keys are encrypted using Windows Data Protection API (Windows only)
+    //
+    "KeyEncryption": "None",
+    //
+    // Path to the X.509 certificate file (.pfx) when using Certificate key encryption.
+    //
+    "CertificatePath": null,
+    //
+    // Password for the certificate file. Can be null for certificates without password.
+    // For security, consider using environment variable reference: "${CERT_PASSWORD}"
+    //
+    "CertificatePassword": null,
+    //
+    // When using Dpapi key encryption, set to true to protect keys to the local machine.
+    // If false (default), keys are protected to the current user account.
+    //
+    "DpapiLocalMachine": false
+  },
+
+  //
+  // Uncomment to configure Kestrel web server and to add certificates
+  // See https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel/endpoints?view=aspnetcore-9.0
+  //
+  "Kestrel": {
+    //  "Endpoints": {
+    //    "Http": {
+    //      "Url": "http://localhost:5000"
+    //    },
+    //    "HttpsInlineCertFile": {
+    //      "Url": "https://localhost:5001",
+    //      "Certificate": {
+    //        "Path": "<path to .pfx file>",
+    //        "Password": "$CREDENTIAL_PLACEHOLDER$"
+    //      }
+    //    },
+    //    "HttpsInlineCertAndKeyFile": {
+    //      "Url": "https://localhost:5002",
+    //      "Certificate": {
+    //        "Path": "<path to .pem/.crt file>",
+    //        "KeyPath": "<path to .key file>",
+    //        "Password": "$CREDENTIAL_PLACEHOLDER$"
+    //      }
+    //    },
+    //    "HttpsInlineCertStore": {
+    //      "Url": "https://localhost:5003",
+    //      "Certificate": {
+    //        "Subject": "<subject; required>",
+    //        "Store": "<certificate store; required>",
+    //        "Location": "<location; defaults to CurrentUser>",
+    //        "AllowInvalid": "<true or false; defaults to false>"
+    //      }
+    //    },
+    //    "HttpsDefaultCert": {
+    //      "Url": "https://localhost:5004"
+    //    }
+    //  },
+    //  "Certificates": {
+    //    "Default": {
+    //      "Path": "<path to .pfx file>",
+    //      "Password": "$CREDENTIAL_PLACEHOLDER$"
+    //    }
+    //  },
+    //  "Limits": {
+    //    "MaxConcurrentConnections": 100,
+    //    "MaxConcurrentUpgradedConnections": 100,
+    //    "MaxRequestBodySize": 30000000,
+    //    "MaxRequestBufferSize": 1048576,
+    //    "MaxRequestHeaderCount": 100,
+    //    "MaxRequestHeadersTotalSize": 32768,
+    //    "MaxRequestLineSize": 8192,
+    //    "MaxResponseBufferSize": 65536,
+    //    "KeepAliveTimeout": "00:02:00",
+    //    "RequestHeadersTimeout": "00:00:30",
+    //    "Http2": {
+    //      "MaxStreamsPerConnection": 100,
+    //      "HeaderTableSize": 4096,
+    //      "MaxFrameSize": 16384,
+    //      "MaxRequestHeaderFieldSize": 8192,
+    //      "InitialConnectionWindowSize": 65535,
+    //      "InitialStreamWindowSize": 65535,
+    //      "MaxReadFrameSize": 16384,
+    //      "KeepAlivePingDelay": "00:00:30",
+    //      "KeepAlivePingTimeout": "00:01:00",
+    //      "KeepAlivePingPolicy": "WithActiveRequests"
+    //    },
+    //    "Http3": {
+    //      "MaxRequestHeaderFieldSize": 8192
+    //    }
+    //  },
+    //  "DisableStringReuse": false,
+    //  "AllowAlternateSchemes": false,
+    //  "AllowSynchronousIO": false,
+    //  "AllowResponseHeaderCompression": true,
+    //  "AddServerHeader": true,
+    //  "AllowHostHeaderOverride": false
+  },
+
+  //
+  // Thread pool configuration settings for optimizing application performance
+  //
+  "ThreadPool": {
+    //
+    // Minimum number of worker threads in the thread pool. Set to null to use system defaults.
+    //
+    "MinWorkerThreads": null,
+    //
+    // Minimum number of completion port threads. Set to null to use system defaults.
+    //
+    "MinCompletionPortThreads": null,
+    //
+    // Maximum number of worker threads in the thread pool. Set to null to use system defaults.
+    //
+    "MaxWorkerThreads": null,
+    //
+    // Maximum number of completion port threads. Set to null to use system defaults.
+    //
+    "MaxCompletionPortThreads": null
+  },
+
+  //
+  // Authentication and Authorization settings
+  //
+  "Auth": {
+    //
+    // Enable Cookie Auth
+    //
+    "CookieAuth": false,
+    //
+    // Authentication scheme name for cookie authentication. Set to null to use default.
+    //
+    "CookieAuthScheme": "Cookies",
+    //
+    // Cookie validity duration in Postgres interval syntax: e.g. "14 days", "12 hours", "30 minutes".
+    // Set to null to fall back to the framework default (14 days).
+    //
+    "CookieValid": "14 days",
+    //
+    // Custom name for the authentication cookie. Set to null to use default.
+    //
+    "CookieName": null,
+    //
+    // Path scope for the authentication cookie. Set to null to use default.
+    //
+    "CookiePath": null,
+    //
+    // Domain scope for the authentication cookie. Set to null to use default.
+    //
+    "CookieDomain": null,
+    //
+    // Allow multiple concurrent sessions for the same user.
+    //
+    "CookieMultiSessions": true,
+    //
+    // Make cookie accessible only via HTTP (not JavaScript).
+    //
+    "CookieHttpOnly": true,
+    //
+    // Controls the SameSite attribute on the authentication cookie. Accepted values:
+    //   "Strict"      — cookie sent only on same-site requests. Most restrictive; CSRF-safe.
+    //   "Lax"         — cookie sent on same-site requests and top-level cross-site GETs (default).
+    //   "None"        — cookie sent on all cross-site requests. REQUIRED for cross-origin SPAs /
+    //                   mobile clients calling this API from a different origin. Browsers drop
+    //                   "SameSite=None" cookies without the Secure attribute, so CookieSecure
+    //                   must be set to "Always".
+    //   "Unspecified" — omit the SameSite attribute entirely (legacy browser behavior).
+    // Set to null to use ASP.NET Core's default (typically "Lax").
+    //
+    "CookieSameSite": null,
+    //
+    // Controls when the cookie's Secure attribute is set. Accepted values:
+    //   "SameAsRequest" — Secure is set only when the request itself is HTTPS (default).
+    //   "Always"        — Secure is always set; browsers only send the cookie over HTTPS. REQUIRED
+    //                     alongside CookieSameSite="None" for cross-origin auth.
+    //   "None"          — Secure is never set; cookies are sent over HTTP as well as HTTPS.
+    // Set to null to use ASP.NET Core's default ("SameAsRequest").
+    //
+    "CookieSecure": null,
+    //
+    // Enable Microsoft Bearer Token Auth (proprietary format, not JWT)
+    //
+    "BearerTokenAuth": false,
+    //
+    // Authentication scheme name for bearer token authentication. Set to null to use default.
+    //
+    "BearerTokenAuthScheme": "BearerToken",
+    //
+    // Bearer token expiration in Postgres interval syntax: e.g. "1 hour", "30 minutes", "2 days".
+    // Set to null to fall back to the framework default (1 hour).
+    //
+    "BearerTokenExpire": "1 hour",
+    // POST { "refresh": "{{refreshToken}}" }
+    "BearerTokenRefreshPath": "/api/token/refresh",
+    //
+    // Enable standard JWT (JSON Web Token) Bearer Authentication
+    //
+    "JwtAuth": false,
+    //
+    // Authentication scheme name for JWT authentication. Set to null to fall back to the framework default.
+    //
+    "JwtAuthScheme": "Bearer",
+    //
+    // Secret key used to sign JWT tokens. Must be at least 32 characters for HS256.
+    // IMPORTANT: Use a strong, unique secret in production. Store securely (e.g., environment variable).
+    //
+    "JwtSecret": null,
+    //
+    // JWT issuer (iss claim). Identifies the principal that issued the JWT.
+    //
+    "JwtIssuer": null,
+    //
+    // JWT audience (aud claim). Identifies the recipients that the JWT is intended for.
+    //
+    "JwtAudience": null,
+    //
+    // JWT access token expiration in Postgres interval syntax: e.g. "60 minutes", "1 hour", "30 seconds".
+    // Set to null to fall back to the framework default (60 minutes).
+    //
+    "JwtExpire": "60 minutes",
+    //
+    // JWT refresh token expiration in Postgres interval syntax: e.g. "7 days", "168 hours", "1 week".
+    // Set to null to fall back to the framework default (7 days).
+    //
+    "JwtRefreshExpire": "7 days",
+    //
+    // Validate the issuer (iss) claim. Set to true if JwtIssuer is configured.
+    //
+    "JwtValidateIssuer": false,
+    //
+    // Validate the audience (aud) claim. Set to true if JwtAudience is configured.
+    //
+    "JwtValidateAudience": false,
+    //
+    // Validate the token lifetime (exp claim). Default is true.
+    //
+    "JwtValidateLifetime": true,
+    //
+    // Validate the signing key. Default is true.
+    //
+    "JwtValidateIssuerSigningKey": true,
+    //
+    // Clock skew to apply when validating token lifetime. Format: PostgreSQL interval.
+    // Default is 5 minutes to account for clock differences between servers.
+    //
+    "JwtClockSkew": "5 minutes",
+    //
+    // URL path for JWT token refresh endpoint. POST with { "refreshToken": "..." }
+    // Returns new access token and refresh token pair.
+    //
+    "JwtRefreshPath": "/api/jwt/refresh",
+    //
+    // Named additional authentication schemes. Each entry registers a fully-fledged ASP.NET Core
+    // authentication scheme alongside the main one. A login function returning a scheme name in its
+    // `scheme` column signs the user in under that scheme — useful for "short-lived sensitive
+    // session", "separate admin scope", or "different JWT signing key per scope" patterns alongside
+    // the normal long-lived primary scheme.
+    //
+    // Each scheme has a `Type`: `Cookies`, `BearerToken`, or `Jwt`. Schemes inherit any unset field
+    // from the root Auth section so blocks stay small. See the type-specific override fields below.
+    //
+    // Validation: scheme name must not collide with the main scheme names (CookieAuthScheme,
+    // BearerTokenAuthScheme, JwtAuthScheme). Explicit `CookieName` values must be unique across all
+    // schemes. Refresh paths (BearerTokenRefreshPath / JwtRefreshPath) must be unique across all
+    // schemes that define one. Disabled schemes (`Enabled: false`) are skipped at startup.
+    //
+    "Schemes": {
+      // Example: a short-lived single-session cookie for sensitive operations (admin area, payment flow).
+      // Login functions can return `'short_session'` in the scheme column to sign users in under this scheme.
+      "short_session": {
+        "Type": "Cookies",
+        "Enabled": false,
+        "CookieValid": "1 hour",
+        "CookieMultiSessions": false
+      },
+      // Example: a separate Microsoft bearer-token scheme with a shorter expiration than the main one.
+      // Each scheme can declare its own refresh path; if set, it must be unique across schemes.
+      "api_token": {
+        "Type": "BearerToken",
+        "Enabled": false,
+        "BearerTokenExpire": "30 minutes",
+        "BearerTokenRefreshPath": "/api/api-token/refresh"
+      },
+      // Example: a separate JWT scheme with its own signing secret (different blast radius from the
+      // main JWT) and a much shorter access-token expiration. Inherits any unset JWT field from the
+      // root Auth section. JwtSecret must be ≥32 characters for HS256.
+      "admin_jwt": {
+        "Type": "Jwt",
+        "Enabled": false,
+        "JwtSecret": null,
+        "JwtIssuer": null,
+        "JwtAudience": null,
+        "JwtExpire": "5 minutes",
+        "JwtRefreshExpire": "1 hour",
+        "JwtRefreshPath": "/api/admin-jwt/refresh"
+      }
+    },
+    //
+    // Enable external auth providers
+    //
+    "External": {
+      "Enabled": false,
+      //
+      // sessionStorage key to store the status of the external auth process returned by the signin page.
+      // The value is HTTP status code (200 for success, 401 for unauthorized, 403 for forbidden, etc.)
+      //
+      "BrowserSessionStatusKey": "__external_status",
+      //
+      // sessionStorage key to store the message of the external auth process returned by the signin page.
+      //
+      "BrowserSessionMessageKey": "__external_message",
+      //
+      // Path to the signin page to handle the external auth process. Redirect to this page to start the external auth process.
+      // Format placeholder {0} is the provider name in lowercase (google, linkedin, github, etc.)
+      //
+      "SigninUrl": "/signin-{0}",
+      //
+      // Sign in page template. Format placeholders {0} is the provider name, {1} is the script to redirect to the external auth provider.
+      //
+      "SignInHtmlTemplate": "<!DOCTYPE html><html><head><meta charset=\"utf-8\" /><title>Talking To {0}</title></head><body>Loading...{1}</body></html>",
+      //
+      // URL to redirect after the external auth process is completed. Usually this is resolved from the request automatically. Except when it's not.
+      // 
+      "RedirectUrl": null,
+      //
+      // Path to redirect after the external auth process is completed. 
+      // 
+      "ReturnToPath": "/",
+      //
+      // Query string key to store the path to redirect after the external auth process is completed.
+      // Use this to set dynamic return path. If this query string key is not found, the ReturnToPath value is used.
+      // 
+      "ReturnToPathQueryStringKey": "return_to",
+      //
+      // Login command to execute after the external auth process is completed. There are five positional and optional parameters:
+      //   $1 - external login provider (if parameter exists, type text).
+      //   $2 - external login email (if parameter exists, type text).
+      //   $3 - external login name (if parameter exists, type text).
+      //   $4 - external login JSON data received (if parameter exists, type text, JSON or JSONB).
+      //   $5 - client browser analytics JSON data (if parameter exists, type text, JSON or JSONB).
+      //
+      // The command uses the same rules as the login enabled routine. 
+      // See: "NpgsqlRest.“LoginPath"
+      //
+      "LoginCommand": "select * from external_login($1,$2,$3,$4,$5)",
+      //
+      // Browser client analytics data that will be sent as JSON to external auth command as the 5th parameter if supplied.
+      //
+      "ClientAnalyticsData": "{timestamp:new Date().toISOString(),timezone:Intl.DateTimeFormat().resolvedOptions().timeZone,screen:{width:window.screen.width,height:window.screen.height,colorDepth:window.screen.colorDepth,pixelRatio:window.devicePixelRatio,orientation:screen.orientation.type},browser:{userAgent:navigator.userAgent,language:navigator.language,languages:navigator.languages,cookiesEnabled:navigator.cookieEnabled,doNotTrack:navigator.doNotTrack,onLine:navigator.onLine,platform:navigator.platform,vendor:navigator.vendor},memory:{deviceMemory:navigator.deviceMemory,hardwareConcurrency:navigator.hardwareConcurrency},window:{innerWidth:window.innerWidth,innerHeight:window.innerHeight,outerWidth:window.outerWidth,outerHeight:window.outerHeight},location:{href:window.location.href,hostname:window.location.hostname,pathname:window.location.pathname,protocol:window.location.protocol,referrer:document.referrer},performance:{navigation:{type:performance.navigation?.type,redirectCount:performance.navigation?.redirectCount},timing:performance.timing?{loadEventEnd:performance.timing.loadEventEnd,loadEventStart:performance.timing.loadEventStart,domComplete:performance.timing.domComplete,domInteractive:performance.timing.domInteractive,domContentLoadedEventEnd:performance.timing.domContentLoadedEventEnd}:null}}",
+      //
+      // Client IP address that will be added to the client analytics data under this JSON key.
+      //
+      "ClientAnalyticsIpKey": "ip",
+      //
+      // External providers
+      //
+      "Google": {
+        //
+        // visit https://console.cloud.google.com/apis/ to configure your Google app and get your client id and client secret
+        //
+        "Enabled": false,
+        "ClientId": "",
+        "ClientSecret": "",
+        "AuthUrl": "https://accounts.google.com/o/oauth2/v2/auth?response_type=code&client_id={0}&redirect_uri={1}&scope=openid profile email&state={2}",
+        "TokenUrl": "https://oauth2.googleapis.com/token",
+        "InfoUrl": "https://www.googleapis.com/oauth2/v3/userinfo",
+        "EmailUrl": null
+      },
+      "LinkedIn": {
+        //
+        // visit https://www.linkedin.com/developers/apps/ to configure your LinkedIn app and get your client id and client secret
+        //
+        "Enabled": false,
+        "ClientId": "",
+        "ClientSecret": "",
+        "AuthUrl": "https://www.linkedin.com/oauth/v2/authorization?response_type=code&client_id={0}&redirect_uri={1}&state={2}&scope=r_liteprofile%20r_emailaddress",
+        "TokenUrl": "https://www.linkedin.com/oauth/v2/accessToken",
+        "InfoUrl": "https://api.linkedin.com/v2/me",
+        "EmailUrl": "https://api.linkedin.com/v2/emailAddress?q=members&projection=(elements//(handle~))"
+      },
+      "GitHub": {
+        //
+        // visit https://github.com/settings/developers/ to configure your GitHub app and get your client id and client secret
+        //
+        "Enabled": false,
+        "ClientId": "",
+        "ClientSecret": "",
+        "AuthUrl": "https://github.com/login/oauth/authorize?client_id={0}&redirect_uri={1}&state={2}&allow_signup=false",
+        "TokenUrl": "https://github.com/login/oauth/access_token",
+        "InfoUrl": "https://api.github.com/user",
+        "EmailUrl": null
+      },
+      "Microsoft": {
+        //
+        // visit https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade to configure your Microsoft app and get your client id and client secret
+        // Documentation: https://learn.microsoft.com/en-us/entra/identity-platform/
+        //
+        "Enabled": false,
+        "ClientId": "",
+        "ClientSecret": "",
+        "AuthUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?response_type=code&client_id={0}&redirect_uri={1}&scope=openid%20profile%20email&state={2}",
+        "TokenUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+        "InfoUrl": "https://graph.microsoft.com/oidc/userinfo",
+        "EmailUrl": null
+      },
+      "Facebook": {
+        //
+        // visit https://developers.facebook.com/apps/ to configure your Facebook app and get your client id and client secret
+        // Documentation: https://developers.facebook.com/docs/facebook-login/
+        //
+        "Enabled": false,
+        "ClientId": "",
+        "ClientSecret": "",
+        "AuthUrl": "https://www.facebook.com/v20.0/dialog/oauth?response_type=code&client_id={0}&redirect_uri={1}&scope=public_profile%20email&state={2}",
+        "TokenUrl": "https://graph.facebook.com/v20.0/oauth/access_token",
+        "InfoUrl": "https://graph.facebook.com/me?fields=id,name,email",
+        "EmailUrl": null
+      }
+    },
+    //
+    // WebAuthn/FIDO2 Passkey Authentication
+    // Provides phishing-resistant, passwordless authentication using device-native biometrics or PINs.
+    //
+    "PasskeyAuth": {
+      //
+      // Enable passkey authentication.
+      //
+      "Enabled": false,
+      //
+      // Enable registration endpoints.
+      //
+      "EnableRegister": false,
+      //
+      // Rate limiter policy name to apply to all passkey endpoints.
+      // It is recommended to enable rate limiting on passkey endpoints to protect against brute-force attacks.
+      // Set to the name of a configured rate limiter policy, or null to disable rate limiting.
+      //
+      "RateLimiterPolicy": null,
+      //
+      // Optional connection name for named DataSource or ConnectionString lookup.
+      // If null, uses the default DataSource or ConnectionString from NpgsqlRest options.
+      //
+      "ConnectionName": null,
+      //
+      // Command retry strategy name from CommandRetryOptions.Strategies.
+      // Set to null to disable command retry for passkey endpoints.
+      //
+      "CommandRetryStrategy": "default",
+      //
+      // Relying Party ID (domain name). Should match your application domain (e.g., "example.com").
+      // If null, auto-detected from the request host.
+      // Note: IP addresses are not permitted - use "localhost" for local development.
+      //
+      "RelyingPartyId": null,
+      //
+      // Human-readable Relying Party name displayed to users during registration and authentication.
+      // If null, uses the ApplicationName from configuration.
+      //
+      "RelyingPartyName": null,
+      //
+      // Allowed origins for origin validation (scheme + domain + port).
+      // Example: ["https://example.com", "https://www.example.com"]
+      // If empty, auto-detected from the request.
+      // Note: IP addresses are not permitted - use "http://localhost:port" for local development.
+      //
+      "RelyingPartyOrigins": [],
+      //
+      // Post path for adding a passkey to an existing authenticated user (options).
+      // Post any additional data in the body as JSON (e.g., { "deviceName": "My Phone" }).
+      // Requires authentication. Set to null to disable this endpoint.
+      //
+      "AddPasskeyOptionsPath": "/api/passkey/add/options",
+      //
+      // Post path for adding a passkey to an existing authenticated user (completion).
+      // Post the WebAuthn response data in the body as JSON (challengeId, credentialId, attestationObject, clientDataJSON, transports). 
+      // Additional JSON body fields are userContext passed through to the CompleteAddExistingUserCommand and optional analyticsData.
+      // Requires authentication. Set to null to disable this endpoint.
+      //
+      "AddPasskeyPath": "/api/passkey/add",
+      //
+      // Post path for registration options (new user with passkey).
+      // Post the user registration data the body as JSON (e.g., { "user_name": "...", "user_display_name": "...", "deviceName": "My Phone"  }).
+      // No authentication required. Set to null to disable registration.
+      //
+      "RegistrationOptionsPath": "/api/passkey/register/options",
+      //
+      // Post path for registration completion (new user with passkey).
+      // Post the WebAuthn response data in the body as JSON (challengeId, credentialId, attestationObject, clientDataJSON, transports). 
+      // Additional JSON body fields are userContext passed through to the CompleteAddExistingUserCommand and optional analyticsData.
+      // No authentication required. Set to null to disable registration.
+      //
+      "RegistrationPath": "/api/passkey/register",
+      //
+      // Post path for the login options endpoint.
+      // Post the user login data in the body as JSON (e.g., { "user_name": "..." } ).
+      // Posting the user_name is optional when using discoverable credentials. When discoverable credentials ate not enabled on the authenticator, user_name is required.
+      //
+      "LoginOptionsPath": "/api/passkey/login/options",
+      //
+      // Post path for the login completion endpoint.
+      // Post the WebAuthn response data in the body as JSON (challengeId, credentialId, authenticatorData, clientDataJSON, signature, userHandle) and optional analyticsData.
+      //
+      "LoginPath": "/api/passkey/login",
+      //
+      // Challenge timeout in minutes. Challenges not used within this time will expire.
+      //
+      "ChallengeTimeoutMinutes": 5,
+      //
+      // User verification requirement:
+      // - "preferred": Request UV if available, but allow authentication without it
+      // - "required": Require UV, fail if not available
+      // - "discouraged": Don't request UV (not recommended for most use cases)
+      //
+      // Practical implications:
+      // - "required": User MUST authenticate with biometric (fingerprint, face) or device PIN.
+      //   High security - proves the person is present, not just possession of the device.
+      // - "preferred": Browser will request biometric/PIN if available, but allows passkey
+      //   authentication even if UV isn't supported (e.g., older security keys).
+      // - "discouraged": Just proves device possession, no biometric/PIN prompt. Lower security.
+      //
+      // For most apps, use "preferred". For banking/sensitive apps, use "required".
+      //
+      "UserVerificationRequirement": "required",
+      //
+      // Resident key (discoverable credential) requirement:
+      // - "preferred": Request discoverable credentials if supported
+      // - "required": Require discoverable credentials, fail if not supported
+      // - "discouraged": Request non-discoverable credentials
+      //
+      // Practical implications:
+      // - "required": True passwordless. Browser shows passkey picker with all accounts at login.
+      //   User picks account and authenticates with biometric/PIN. No username input needed.
+      // - "preferred"/"discouraged": User enters username first, then authenticates with passkey.
+      //
+      // For passwordless flows (no username field), set to "required".
+      //
+      "ResidentKeyRequirement": "required",
+      //
+      // Attestation conveyance preference - controls whether the server requests the authenticator
+      // to provide cryptographic proof of its identity (make/model) and security properties during registration.
+      //
+      // Options:
+      // - "none": Don't request attestation. Accept any valid authenticator without verifying its identity.
+      //   Best for most apps - simpler, better user privacy, wider device compatibility. (Recommended)
+      // - "indirect": Request attestation but allow the browser/platform to anonymize it. Rarely useful.
+      // - "direct": Request full attestation certificate chain from the authenticator.
+      //   Use when you need to verify the authenticator vendor/model meets security requirements.
+      // - "enterprise": Request enterprise-specific attestation for managed corporate devices
+      //   where IT needs to verify only organization-approved hardware authenticators are used.
+      //
+      // When to use non-"none" values:
+      // - Banking/financial apps requiring hardware security keys only
+      // - Enterprise environments restricting to specific authenticator models
+      // - Compliance requirements mandating certain security certifications (FIDO2 L1/L2)
+      //
+      // For most consumer applications, "none" is the correct choice - you just want the user
+      // to authenticate securely, not audit their hardware.
+      //
+      "AttestationConveyance": "none",
+      //
+      // Whether to validate and update the signature counter (sign count).
+      // When true, validates that the new sign count is greater than stored, and updates it after authentication.
+      // When false, skips sign count validation and update entirely.
+      // Set to false if authenticators don't support it or you want to simplify your database schema.
+      //
+      "ValidateSignCount": true,
+      //
+      // SQL command to create a challenge when adding a passkey to an existing authenticated user.
+      // Parameters:
+      //   - $1 = claims (json): JSON object with user claims from the authenticated session
+      //   - $2 = body (json): JSON object from request body (e.g., { "deviceName": "My Phone" })
+      // Expected return columns (by name):
+      //   - status (int): HTTP status code. Return 200 to proceed, any other status aborts.
+      //   - message (text): Error message when status != 200.
+      //   - challenge (text): Base64-encoded random challenge bytes (typically 32 bytes).
+      //   - challenge_id: Server-side identifier (uuid, int, bigint, or text).
+      //   - user_handle (text): Base64-encoded random bytes (typically 32 bytes) for WebAuthn user.id.
+      //   - user_name (text): Username displayed in the authenticator UI.
+      //   - user_display_name (text): Display name shown in the authenticator UI.
+      //   - exclude_credentials (text): JSON array of existing credentials.
+      //   - user_context (json): Opaque JSON passed through to CompleteAddExistingUserCommand.
+      // Called by AddPasskeyOptionsPath endpoint
+      //
+      "ChallengeAddExistingUserCommand": "select * from passkey_challenge_add_existing($1,$2)",
+      //
+      // SQL command to create a challenge for standalone registration (new user).
+      // Parameter: $1 = JSON object from request body (e.g., { "user_name": "...", "display_name": "..." })
+      // Expected return columns (by name): Same as ChallengeAddExistingUserCommand
+      //   - user_context should NOT contain "id" field (distinguishes from add-existing-user flow)
+      // Called by StandaloneRegistrationOptionsPath endpoint
+      //
+      "ChallengeRegistrationCommand": "select * from passkey_challenge_registration($1)",
+      //
+      // SQL command to create a challenge for authentication.
+      // Parameters:
+      //   - $1 = user_name (text, optional - null for discoverable credential flow)
+      //   - $2 = body (json): JSON object from request body (e.g., { "deviceInfo": "..." })
+      // Expected return columns (by name): status, message, challenge, challenge_id, allow_credentials
+      // Called by AuthenticationOptionsPath endpoint 
+      //
+      "ChallengeAuthenticationCommand": "select * from passkey_challenge_authentication($1,$2)",
+      //
+      // Used by: Flow 1, Flow 2, Flow 3 (ALL flows)
+      // SQL command to verify and consume a challenge.
+      // Parameters: $1 = challenge_id (uuid, int, bigint, or text), $2 = operation (text: "registration" or "authentication")
+      // Returns: challenge (bytea) - the original challenge bytes, or NULL if not found/expired
+      // Called by all endpoints
+      //
+      "VerifyChallengeCommand": "select * from passkey_verify_challenge($1,$2)",
+      //
+      // SQL command to get credential data for authentication.
+      // Parameter: $1 = credential_id (bytea)
+      // Expected return columns (by name): status, message, public_key, public_key_algorithm, sign_count, user_context
+      // Note: user_context is passed through to CompleteAuthenticateCommand (typically contains user_id)
+      // Called by AuthenticatePath endpoint
+      //
+      "AuthenticateDataCommand": "select * from passkey_authenticate_data($1)",
+      //
+      // SQL command to complete adding a passkey to an existing user account.
+      // Parameters:
+      //   - $1 = credential_id (bytea): Unique credential identifier from authenticator.
+      //   - $2 = user_handle (bytea): WebAuthn user.id from registration options.
+      //   - $3 = public_key (bytea): Public key in COSE format.
+      //   - $4 = algorithm (int): COSE algorithm identifier (-7 for ES256, -257 for RS256).
+      //   - $5 = transports (text[]): Transport hints (e.g., ["internal", "hybrid"]).
+      //   - $6 = backup_eligible (boolean): Whether credential can be backed up/synced.
+      //   - $7 = user_context (json): Opaque JSON from ChallengeAddExistingUserCommand (contains user ID).
+      //   - $8 = analytics_data (json, optional): Client analytics with server-added IP.
+      // Expected return columns (by name): status, message
+      // Called by RegisterPath endpoint
+      //
+      "CompleteAddExistingUserCommand": "select * from passkey_complete_add_existing($1,$2,$3,$4,$5,$6,$7,$8)",
+      //
+      // SQL command to complete standalone passkey registration (creates new user).
+      // Parameters: Same as CompleteAddExistingUserCommand
+      //   - user_context should NOT contain "id" field (creates new user instead of linking to existing)
+      // Expected return columns (by name): status, message
+      // Called by RegisterPath endpoint
+      //
+      "CompleteRegistrationCommand": "select * from passkey_complete_registration($1,$2,$3,$4,$5,$6,$7,$8)",
+      //
+      // Flow 3: Login -> AuthenticatePath endpoint (after signature validation)
+      // SQL command to update sign count and return user claims.
+      // Parameters:
+      //   - $1 = credential_id (bytea)
+      //   - $2 = new_sign_count (bigint)
+      //   - $3 = user_context (json): Opaque JSON from AuthenticateDataCommand
+      //   - $4 = analytics_data (json, optional): Client analytics with server-added IP
+      // Expected return columns (by name): status, user_id, user_name, user_roles (plus any custom claims)
+      // Called by AuthenticatePath endpoint
+      //
+      "CompleteAuthenticateCommand": "select * from passkey_complete_authenticate($1,$2,$3,$4)",
+      //
+      // The JSON key name used to add the client's IP address to the analytics data server-side.
+      // Set to null or empty string to disable IP address collection.
+      //
+      "ClientAnalyticsIpKey": "ip",
+      //
+      // Column name configuration for database responses
+      //
+      "StatusColumnName": "status",
+      "MessageColumnName": "message",
+      "ChallengeColumnName": "challenge",
+      "ChallengeIdColumnName": "challenge_id",
+      "UserNameColumnName": "user_name",
+      "UserDisplayNameColumnName": "user_display_name",
+      "UserHandleColumnName": "user_handle",
+      "ExcludeCredentialsColumnName": "exclude_credentials",
+      "AllowCredentialsColumnName": "allow_credentials",
+      "PublicKeyColumnName": "public_key",
+      "PublicKeyAlgorithmColumnName": "public_key_algorithm",
+      "SignCountColumnName": "sign_count"
+    }
+  },
+
+  //
+  // Serilog settings
+  //
+  "Log": {
+    //
+    // See https://github.com/serilog/serilog/wiki/Configuration-Basics#minimum-level
+    // Verbose, Debug, Information, Warning, Error, Fatal.
+    // Note: NpgsqlRest logger applies to main application logger, which will, by default have the name defined in the ApplicationName setting.
+    //
+    "MinimalLevels": {
+      "NpgsqlRest": "Information",
+      "NpgsqlRestClient": "Information",
+      "System": "Warning",
+      "Microsoft": "Warning"
+    },
+    //
+    // Enable logging to console output.
+    //
+    "ToConsole": true,
+    //
+    // Minimum log level for console output: Verbose, Debug, Information, Warning, Error, Fatal.
+    //
+    "ConsoleMinimumLevel": "Verbose",
+    //
+    // Enable logging to file system.
+    //
+    "ToFile": false,
+    //
+    // File path for log files.
+    //
+    "FilePath": "logs/log.txt",
+    //
+    // Maximum size limit for log files in bytes before rolling to a new file.
+    //
+    "FileSizeLimitBytes": 30000000,
+    //
+    // Minimum log level for file output: Verbose, Debug, Information, Warning, Error, Fatal.
+    //
+    "FileMinimumLevel": "Verbose",
+    //
+    // Maximum number of log files to retain.
+    //
+    "RetainedFileCountLimit": 30,
+    //
+    // Create a new log file when size limit is reached.
+    //
+    "RollOnFileSizeLimit": true,
+    //
+    // Enable logging to PostgreSQL database.
+    //
+    "ToPostgres": false,
+    // $1 - log level text, $2 - message text, $3 - timestamp with tz in utc, $4 - exception text or null, $5 - source context
+    //
+    // PostgreSQL command to execute for database logging. Parameters: $1=level, $2=message, $3=timestamp, $4=exception, $5=source.
+    //
+    "PostgresCommand": "call log($1,$2,$3,$4,$5)",
+    //
+    // Minimum log level for PostgreSQL output: Verbose, Debug, Information, Warning, Error, Fatal.
+    //
+    "PostgresMinimumLevel": "Verbose",
+    //
+    // Enable OpenTelemetry protocol (OTLP) logging output. Requires an OTLP collector endpoint.
+    //
+    "ToOpenTelemetry": false,
+    "OTLPEndpoint": "http://localhost:4317",
+    "OTLPProtocol": "Grpc", // "Grpc" or "HttpProtobuf"
+    "OTLResourceAttributes": {
+        "service.name": "{application}", // application name from the ApplicationName setting
+        "service.version": "1.0", // application version, set to a static value or use a build process to update it
+        "service.environment": "{environment}" // environment name from the EnvironmentName setting
+    },
+    "OTLPHeaders": {},
+    "OTLPMinimumLevel": "Verbose",
+    
+    //
+    // See https://github.com/serilog/serilog/wiki/Formatting-Output
+    //
+    "OutputTemplate": "[{Timestamp:HH:mm:ss.fff} {Level:u3}] {Message:lj} [{SourceContext}]{NewLine}{Exception}"
+  },
+
+  //
+  // Response compression settings
+  //
+  "ResponseCompression": {
+    //
+    // Enable response compression for HTTP responses.
+    //
+    "Enabled": false,
+    //
+    // Enable response compression for HTTPS responses.
+    //
+    "EnableForHttps": false,
+    //
+    // Use Brotli compression algorithm when supported by client.
+    //
+    "UseBrotli": true,
+    //
+    // Use Gzip compression as fallback when Brotli is not supported.
+    //
+    "UseGzipFallback": true,
+    //
+    // Compression level: Optimal, Fastest, NoCompression, SmallestSize.
+    //
+    "CompressionLevel": "Optimal",
+    //
+    // MIME types to include for compression.
+    //
+    "IncludeMimeTypes": [
+      "text/plain",
+      "text/css",
+      "application/javascript",
+      "text/javascript",
+      "text/html",
+      "application/xml",
+      "text/xml",
+      "application/json",
+      "text/json",
+      "image/svg+xml",
+      "font/woff",
+      "font/woff2",
+      "application/font-woff",
+      "application/font-woff2"
+    ],
+    //
+    // MIME types to exclude from compression.
+    //
+    "ExcludeMimeTypes": []
+  },
+
+  //
+  // Antiforgery Token Configuration: Protects against Cross-Site Request Forgery (CSRF/XSRF) attacks.
+  // CSRF attacks occur when a malicious site tricks a user's browser into making unwanted requests to your application
+  // using the user's authenticated session (cookies).
+  //
+  // How it works:
+  // 1. Server generates a unique token for each session/request
+  // 2. Token is embedded in forms (hidden field) or sent via header (for AJAX)
+  // 3. On state-changing requests (POST, PUT, DELETE), server validates the token
+  // 4. Requests without valid tokens are rejected (400 Bad Request)
+  //
+  // Usage in HTML forms:
+  //   <form method="post">
+  //     <input type="hidden" name="__RequestVerificationToken" value="{antiForgeryToken}" />
+  //     ...
+  //   </form>
+  //
+  // Usage in AJAX/JavaScript:
+  //   fetch('/api/endpoint', {
+  //     method: 'POST',
+  //     headers: { 'RequestVerificationToken': tokenValue },
+  //     body: JSON.stringify(data)
+  //   });
+  //
+  // Note: Antiforgery automatically sets the X-Frame-Options: SAMEORIGIN header to help prevent clickjacking.
+  // If you're using the SecurityHeaders middleware with X-Frame-Options, the Antiforgery header takes precedence
+  // (SecurityHeaders will skip X-Frame-Options when Antiforgery is enabled).
+  //
+  // Reference: https://learn.microsoft.com/en-us/aspnet/core/security/anti-request-forgery
+  //
+  "Antiforgery": {
+    //
+    // Enable antiforgery token validation for state-changing requests.
+    //
+    "Enabled": false,
+    //
+    // Name of the cookie that stores the antiforgery token.
+    // Set to null to use the ASP.NET Core default (unique per application, starts with ".AspNetCore.Antiforgery.").
+    // Custom names are useful when running multiple applications on the same domain.
+    //
+    "CookieName": null,
+    //
+    // Name of the hidden form field that contains the request verification token.
+    // This must match the name used in your HTML forms.
+    //
+    "FormFieldName": "__RequestVerificationToken",
+    //
+    // Name of the HTTP header that can contain the antiforgery token.
+    // Useful for AJAX requests where adding a form field is not possible.
+    // JavaScript can read the token from a cookie or meta tag and send it in this header.
+    //
+    "HeaderName": "RequestVerificationToken",
+    //
+    // When true, the server will NOT look for the token in the form body.
+    // Forces header-only validation - useful for pure API scenarios where all requests use headers.
+    // When false (default), server checks both form field and header.
+    //
+    "SuppressReadingTokenFromFormBody": false,
+    //
+    // When true, prevents the automatic X-Frame-Options: SAMEORIGIN header from being set.
+    // X-Frame-Options helps prevent clickjacking attacks by blocking the page from being embedded in iframes.
+    // Only set to true if:
+    //   - You need your pages to be embedded in iframes from other origins, OR
+    //   - You're setting X-Frame-Options elsewhere (e.g., in SecurityHeaders or at the proxy level)
+    // Default: false (header is set for security)
+    //
+    "SuppressXFrameOptionsHeader": false
+  },
+
+  //
+  // Static files settings 
+  //
+  "StaticFiles": {
+    "Enabled": false,
+    "RootPath": "wwwroot",
+    //
+    // List of static file patterns that will require authorization.
+    // File paths are relative to the RootPath property and pattern matching is case-insensitive.
+    // Pattern can include wildcards (* matches any chars, ** matches recursively including /, ? matches single char).
+    // For example: *.html, /user/*, /admin/**/*.html
+    //
+    "AuthorizePaths": [],
+    "UnauthorizedRedirectPath": "/",
+    "UnauthorizedReturnToQueryParameter": "return_to",
+    "ParseContentOptions": {
+      //
+      // Enable or disable the parsing of the static files.
+      // When enabled, the static files will be parsed and the tags will be replaced with the values from the claims collection.
+      // The tags are in the format: {claimType} where claimType is the name of the claim that will be replaced with the value from the claims collection.
+      //
+      "Enabled": false,
+      //
+      // List of claims types used. These will be parsed to NULL if not found in the claims collection or user is not authenticated.
+      // Accepts an array of claim names ["name","email"] or an object of name->default {"name":"guest"} where the default is used when the claim is absent.
+      //
+      "AvailableClaims": [],
+      //
+      // List of environment variable names whose values are templated into static content (the same {NAME} tag syntax as claims).
+      // Resolved once at startup. Accepts an array ["BUILD_LABEL"] (missing -> empty string) or an object {"DEMO_FLAG":"false"} with per-name defaults.
+      // SECURITY: every listed value is served to any client - never list a secret (DB password, API key, signing token).
+      //
+      "AvailableEnvVars": [],
+      //
+      // Set to true to cache the parsed files in memory. This will improve the performance of the static files. It only applies to parsed content.
+      // Note: caching will occur before parsing, it applies only to templates, not parsed content.
+      //
+      "CacheParsedFile": true,
+      //
+      // Headers to be added to the response for static files. Set to null or empty array to ignore.
+      //
+      "Headers": [ "Cache-Control: no-store, no-cache, must-revalidate", "Pragma: no-cache", "Expires: 0" ],
+      //
+      // List of static file patterns that will parse the content and replace the tags with the values from the claims collection.
+      // File paths are relative to the RootPath property and pattern matching is case-insensitive.
+      // Pattern can include wildcards (* matches any chars, ** matches recursively including /, ? matches single char).
+      // For example: *.html, *.htm, *.txt, /pages/**/*.html
+      // 
+      "FilePaths": [ "*.html" ],
+      //
+      // Name of the configured Antiforgery form field name to be used in the static files (see Antiforgery FormFieldName setting).
+      //
+      "AntiforgeryFieldName": "antiForgeryFieldName",
+      //
+      // Value of the Antiforgery token if Antiforgery is enabled.
+      //
+      "AntiforgeryToken": "antiForgeryToken"
+    }
+  },
+
+  //
+  // Cross-origin resource sharing 
+  //
+  "Cors": {
+    //
+    // Enable Cross-Origin Resource Sharing (CORS) support.
+    //
+    "Enabled": false,
+    //
+    // List of allowed origins for CORS requests. Empty array allows no origins.
+    //
+    "AllowedOrigins": [],
+    //
+    // List of allowed HTTP methods for CORS requests.
+    //
+    "AllowedMethods": [
+      "*"
+    ],
+    //
+    // List of allowed headers for CORS requests.
+    //
+    "AllowedHeaders": [
+      "*"
+    ],
+    //
+    // Allow credentials (cookies, authorization headers) in CORS requests.
+    // Disabled by default: credentials must be enabled deliberately and only together with
+    // an explicit AllowedOrigins list (never with wildcard origins).
+    //
+    "AllowCredentials": false,
+    //
+    // Maximum age in seconds for preflight request caching (10 minutes).
+    //
+    "PreflightMaxAgeSeconds": 600
+  },
+
+  //
+  // Security Headers: Adds HTTP security headers to all responses to protect against common web vulnerabilities.
+  // These headers instruct browsers how to handle your content securely.
+  // Note: X-Frame-Options is automatically handled by the Antiforgery middleware when enabled (see Antiforgery.SuppressXFrameOptionsHeader).
+  // Reference: https://owasp.org/www-project-secure-headers/
+  //
+  "SecurityHeaders": {
+    //
+    // Enable security headers middleware. When enabled, configured headers are added to all HTTP responses.
+    //
+    "Enabled": false,
+    //
+    // X-Content-Type-Options: Prevents browsers from MIME-sniffing a response away from the declared content-type.
+    // Recommended value: "nosniff"
+    // Set to null to not include this header.
+    //
+    "XContentTypeOptions": "nosniff",
+    //
+    // X-Frame-Options: Controls whether the browser should allow the page to be rendered in a <frame>, <iframe>, <embed> or <object>.
+    // Values: "DENY" (never allow), "SAMEORIGIN" (allow from same origin only)
+    // Note: This header is SKIPPED if Antiforgery is enabled (Antiforgery already sets X-Frame-Options: SAMEORIGIN by default).
+    // Set to null to not include this header.
+    //
+    "XFrameOptions": "DENY",
+    //
+    // Referrer-Policy: Controls how much referrer information should be included with requests.
+    // Values: "no-referrer", "no-referrer-when-downgrade", "origin", "origin-when-cross-origin",
+    //         "same-origin", "strict-origin", "strict-origin-when-cross-origin", "unsafe-url"
+    // Recommended: "strict-origin-when-cross-origin" (send origin for cross-origin requests, full URL for same-origin)
+    // Set to null to not include this header.
+    //
+    "ReferrerPolicy": "strict-origin-when-cross-origin",
+    //
+    // Content-Security-Policy: Defines approved sources of content that the browser may load.
+    // Helps prevent XSS, clickjacking, and other code injection attacks.
+    // Example: "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'"
+    // Reference: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
+    // Set to null to not include this header (recommended to configure based on your application needs).
+    //
+    "ContentSecurityPolicy": null,
+    //
+    // Permissions-Policy: Controls which browser features and APIs can be used.
+    // Example: "geolocation=(), microphone=(), camera=()" disables these features entirely.
+    // Example: "geolocation=(self), microphone=()" allows geolocation only from same origin.
+    // Reference: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy
+    // Set to null to not include this header.
+    //
+    "PermissionsPolicy": null,
+    //
+    // Cross-Origin-Opener-Policy: Controls how your document is shared with cross-origin popups.
+    // Values: "unsafe-none", "same-origin-allow-popups", "same-origin"
+    // Set to null to not include this header.
+    //
+    "CrossOriginOpenerPolicy": null,
+    //
+    // Cross-Origin-Embedder-Policy: Prevents a document from loading cross-origin resources that don't explicitly grant permission.
+    // Values: "unsafe-none", "require-corp", "credentialless"
+    // Required for SharedArrayBuffer and high-resolution timers (along with COOP: same-origin).
+    // Set to null to not include this header.
+    //
+    "CrossOriginEmbedderPolicy": null,
+    //
+    // Cross-Origin-Resource-Policy: Indicates how the resource should be shared cross-origin.
+    // Values: "same-site", "same-origin", "cross-origin"
+    // Set to null to not include this header.
+    //
+    "CrossOriginResourcePolicy": null
+  },
+
+  //
+  // Forwarded Headers: Enables the application to read proxy headers (X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host).
+  // CRITICAL: Required when running behind a reverse proxy (nginx, Apache, Azure App Service, AWS ALB, Cloudflare, etc.)
+  // Without this, the application sees the proxy's IP instead of the client's real IP, and HTTP instead of HTTPS.
+  // Security Warning: Only enable if you're behind a trusted proxy. Malicious clients can spoof these headers.
+  // Reference: https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/proxy-load-balancer
+  //
+  "ForwardedHeaders": {
+    //
+    // Enable forwarded headers middleware (automatically placed first in the middleware pipeline).
+    //
+    "Enabled": false,
+    //
+    // Limits the number of proxy entries that will be processed from X-Forwarded-For.
+    // Default is 1 (trust only the immediate proxy). Increase if you have multiple proxies in a chain.
+    // Set to null to process all entries (not recommended for security).
+    //
+    "ForwardLimit": 1,
+    //
+    // List of IP addresses of known proxies to accept forwarded headers from.
+    // Example: ["10.0.0.1", "192.168.1.1"]
+    // If empty and KnownNetworks is also empty, forwarded headers are accepted from any source (less secure).
+    //
+    "KnownProxies": [],
+    //
+    // List of CIDR network ranges of known proxies.
+    // Example: ["10.0.0.0/8", "192.168.0.0/16", "172.16.0.0/12"] for private networks
+    // Useful when proxy IPs are dynamically assigned within a known range.
+    //
+    "KnownNetworks": [],
+    //
+    // List of allowed values for the X-Forwarded-Host header.
+    // Example: ["example.com", "www.example.com"]
+    // If empty, any host is allowed (less secure). Helps prevent host header injection attacks.
+    //
+    "AllowedHosts": []
+  },
+
+  //
+  // Health Checks: Provides endpoints for monitoring application health, used by container orchestrators (Kubernetes, Docker Swarm),
+  // load balancers, and monitoring systems to determine if the application is running correctly.
+  // Three types of checks are supported:
+  //   - /health: Overall health status (combines all checks)
+  //   - /health/ready: Readiness probe - is the app ready to accept traffic? (includes database connectivity)
+  //   - /health/live: Liveness probe - is the app process running? (always returns healthy if app responds)
+  // Reference: https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks
+  //
+  "HealthChecks": {
+    //
+    // Enable health check endpoints.
+    //
+    "Enabled": false,
+    //
+    // Cache health check responses server-side in memory for the specified duration.
+    // Cached responses are served without re-executing the endpoint.
+    // Value is in PostgreSQL interval format (e.g., '5 seconds', '1 minute', '30s', '1min').
+    // Set to null to disable caching. Query strings are ignored to prevent cache-busting.
+    //
+    "CacheDuration": "5 seconds",
+    //
+    // Path for the main health check endpoint that reports overall status.
+    // Returns "Healthy", "Degraded", or "Unhealthy" with HTTP 200 (healthy/degraded) or 503 (unhealthy).
+    //
+    "Path": "/health",
+    //
+    // Path for the readiness probe endpoint.
+    // Kubernetes uses this to know when a pod is ready to receive traffic.
+    // Includes database connectivity check when IncludeDatabaseCheck is true.
+    // Returns 503 Service Unavailable if database is unreachable.
+    //
+    "ReadyPath": "/health/ready",
+    //
+    // Path for the liveness probe endpoint.
+    // Kubernetes uses this to know when to restart a pod.
+    // Always returns Healthy (200) if the application process is responding.
+    // Does NOT check database - a slow database shouldn't trigger a container restart.
+    //
+    "LivePath": "/health/live",
+    //
+    // Include PostgreSQL database connectivity in health checks.
+    // When true, the readiness probe will fail if the database is unreachable.
+    //
+    "IncludeDatabaseCheck": true,
+    //
+    // Name for the database health check (appears in detailed health reports).
+    //
+    "DatabaseCheckName": "postgresql",
+    //
+    // Require authentication for health check endpoints.
+    // When true, all health endpoints require a valid authenticated user.
+    // Security Consideration: Health endpoints can reveal information about your infrastructure
+    // (database connectivity, service status). Enable this if your health endpoints are publicly accessible.
+    // Note: Kubernetes/Docker health probes may need to authenticate if this is enabled.
+    //
+    "RequireAuthorization": false,
+    //
+    // Apply a rate limiter policy to health check endpoints.
+    // Specify the name of a policy defined in RateLimiterOptions.Policies.
+    // Security Consideration: Prevents denial-of-service attacks targeting health endpoints.
+    // Set to null to disable rate limiting on health endpoints.
+    // Example: "fixed" or "bucket" (must match a policy name from RateLimiterOptions).
+    //
+    "RateLimiterPolicy": null
+  },
+
+  //
+  // PostgreSQL Statistics Endpoints
+  // Exposes PostgreSQL statistics through HTTP endpoints for monitoring and debugging.
+  // Provides access to pg_stat_user_functions, pg_stat_user_tables, pg_stat_user_indexes, and pg_stat_activity.
+  //
+  "Stats": {
+    //
+    // Enable PostgreSQL statistics endpoints.
+    //
+    "Enabled": false,
+    //
+    // Cache stats responses server-side in memory for the specified duration.
+    // Cached responses are served without re-executing the endpoint.
+    // Value is in PostgreSQL interval format (e.g., '5 seconds', '1 minute', '30s', '1min').
+    // Set to null to disable caching. Query strings are ignored to prevent cache-busting.
+    //
+    "CacheDuration": "5 seconds",
+    //
+    // Apply a rate limiter policy to stats endpoints.
+    // Specify the name of a policy defined in RateLimiterOptions.Policies.
+    // Set to null to disable rate limiting on stats endpoints.
+    //
+    "RateLimiterPolicy": null,
+    //
+    // Use a specific named connection for stats queries.
+    // When null, uses the default connection string.
+    // Useful when you want to query stats from a different database or use read-only credentials.
+    //
+    "ConnectionName": null,
+    //
+    // Require authentication for stats endpoints.
+    // Security Consideration: Stats endpoints can reveal sensitive information about your database
+    // (table sizes, query patterns, active sessions). Enable this for production environments.
+    //
+    "RequireAuthorization": false,
+    //
+    // Restrict access to specific roles.
+    // When null or empty, any authenticated user can access (if RequireAuthorization is true).
+    // Example: ["admin", "dba"] - only users with admin or dba role can access.
+    //
+    "AuthorizedRoles": [],
+    //
+    // Output format for stats endpoints: "json" or "html".
+    // - json: JSON array
+    // - html: HTML table, Excel-compatible for direct browser copy-paste (default)
+    // Can be overridden per-request with the ?format= query string parameter (e.g. ?format=json).
+    //
+    "OutputFormat": "html",
+    //
+    // Filter schemas using PostgreSQL SIMILAR TO pattern.
+    // When null, all schemas are included.
+    // Example: "public|myapp%" - includes 'public' and schemas starting with 'myapp'.
+    //
+    "SchemaSimilarTo": null,
+    //
+    // Path for routine (function/procedure) performance statistics.
+    // Returns data from pg_stat_user_functions including call counts and execution times.
+    // Note: Requires track_functions = 'pl' or 'all' in postgresql.conf.
+    // Enable with: alter system set track_functions = 'all'; select pg_reload_conf();
+    // Or set track_functions = 'all' directly in postgresql.conf and restart/reload.
+    //
+    "RoutinesStatsPath": "/stats/routines",
+    //
+    // Path for table statistics.
+    // Returns data from pg_stat_user_tables including tuple counts, sizes, scan counts, and vacuum info.
+    //
+    "TablesStatsPath": "/stats/tables",
+    //
+    // Path for index statistics.
+    // Returns data from pg_stat_user_indexes including scan counts and index definitions.
+    //
+    "IndexesStatsPath": "/stats/indexes",
+    //
+    // Path for current database activity.
+    // Returns data from pg_stat_activity showing active sessions, queries, and wait events.
+    // Security Consideration: Shows currently running queries which may contain sensitive data.
+    //
+    "ActivityPath": "/stats/activity"
+  },
+
+  //
+  // Command retry strategies and options for client and middleware commands.
+  //
+  "CommandRetryOptions": {
+    "Enabled": true,
+    "DefaultStrategy": "default",
+    "Strategies": {
+      "default": {
+        //
+        // Retry sequence in seconds. Accepts decimal numbers (0.25 is quarter of a second). The length of the array determines the maximum number of retries.
+        //
+        "RetrySequenceSeconds": [0, 1, 2, 5, 10],
+        //
+        // Error codes that will trigger a retry when executing a command. See https://www.postgresql.org/docs/current/errcodes-appendix.html
+        //
+        "ErrorCodes": [
+          // Serialization failures (MUST retry for correctness)
+          "40001", // serialization_failure 
+          "40P01", // deadlock_detected
+          // Connection issues (Class 08)
+          "08000", // connection_exception
+          "08003", // connection_does_not_exist
+          "08006", // connection_failure  
+          "08001", // sqlclient_unable_to_establish_sqlconnection
+          "08004", // sqlserver_rejected_establishment_of_sqlconnection
+          "08007", // transaction_resolution_unknown
+          "08P01", // protocol_violation
+          // Resource constraints (Class 53)
+          "53000", // insufficient_resources
+          "53100", // disk_full
+          "53200", // out_of_memory
+          "53300", // too_many_connections
+          "53400", // configuration_limit_exceeded
+          // System errors (Class 58) 
+          "57P01", // admin_shutdown
+          "57P02", // crash_shutdown  
+          "57P03", // cannot_connect_now
+          "58000", // system_error
+          "58030", // io_error
+          // Lock acquisition issues (Class 55)
+          "55P03", // lock_not_available
+          "55006", // object_in_use
+          "55000"  // object_not_in_prerequisite_state
+        ]
+      }
+    }
+  },
+  
+  //
+  // Caching options for routines that support caching. Currently, routines that return a single result set can be cached. Returning table or "setof" cannot be cached.
+  // To enable caching for a routine, add the following comment annotation to the routine:
+  // cached [ param1, param2, param3 [, ...] ] - parameters are optional, if no parameters are specified, all parameters are used for cache key.
+  // cache_expires [ value ] or cache_expires_in [ value ] - accepts PostgreSQL interval format (for example: '5 minutes' or '5min', '1 second' or '1s', etc.). Default is forever (no expiration).
+  // 
+  "CacheOptions": {
+    "Enabled": false,
+    //
+    // Cache type: Memory, Redis, or Hybrid
+    // - Memory: In-process memory cache (fastest, single instance only)
+    // - Redis: Distributed Redis cache (slower, shared across instances)
+    // - Hybrid: Uses Microsoft.Extensions.Caching.Hybrid which provides:
+    //   - Automatic stampede protection to prevent multiple concurrent requests from hitting the database
+    //   - Optional Redis L2 backend (enable with HybridCacheUseRedisBackend: true) for sharing cache across instances
+    //   - Without Redis, works as in-memory cache with stampede protection
+    //
+    "Type": "Memory",
+    //
+    // When memory cache is used, this value determines how often the cache will be pruned for expired items (in seconds).
+    //
+    "MemoryCachePruneIntervalSeconds": 60,
+    //
+    // Redis configuration string. Used when Type is "Redis", or when Type is "Hybrid" with UseRedisBackend: true.
+    // See: https://stackexchange.github.io/StackExchange.Redis/Configuration.html
+    //
+    "RedisConfiguration": "localhost:6379,abortConnect=false,ssl=false,connectTimeout=10000,syncTimeout=5000,connectRetry=3",
+    //
+    // Maximum number of rows that can be cached for set-returning functions.
+    // If a result set exceeds this limit, it will not be cached (but will still be returned).
+    // Set to 0 to disable caching for sets entirely. Set to null for unlimited (use with caution).
+    //
+    "MaxCacheableRows": 1000,
+    //
+    // When true, cache keys longer than HashKeyThreshold characters are hashed to a fixed-length SHA256 string (64 characters).
+    // This reduces memory usage for long cache keys and improves Redis performance with large keys.
+    // Recommended for Redis cache or when caching routines with many/large parameters.
+    //
+    "UseHashedCacheKeys": false,
+    //
+    // Cache keys longer than this threshold (in characters) will be hashed when UseHashedCacheKeys is true.
+    // Keys shorter than this threshold are stored as-is for better debuggability.
+    //
+    "HashKeyThreshold": 256,
+    //
+    // When set, creates an additional invalidation endpoint for each cached endpoint.
+    // The invalidation endpoint has the same path with this suffix appended.
+    // For example, if a cached endpoint is /api/my-endpoint/ and this is set to "invalidate",
+    // an invalidation endpoint /api/my-endpoint/invalidate will be created.
+    // Calling the invalidation endpoint with the same parameters removes the cached entry.
+    //
+    "InvalidateCacheSuffix": null,
+    //
+    // --- Hybrid Cache specific options (only used when Type is "Hybrid") ---
+    //
+    // When true, uses Redis as the L2 (secondary/distributed) cache backend.
+    // When false (default), HybridCache uses in-memory only but still provides stampede protection.
+    // Stampede protection prevents multiple concurrent requests from hitting the database when cache expires.
+    //
+    "HybridCacheUseRedisBackend": false,
+    //
+    // Maximum length of cache keys in characters. Keys longer than this will be rejected.
+    // Default: 1024
+    //
+    "HybridCacheMaximumKeyLength": 1024,
+    //
+    // Maximum size of cached payloads in bytes.
+    // Default: 1048576 (1 MB)
+    //
+    "HybridCacheMaximumPayloadBytes": 1048576,
+    //
+    // Default expiration for cached entries (both L1 and L2). Accepts PostgreSQL interval format.
+    // Examples: '5 minutes', '1 hour', '30 seconds'
+    // If not set, individual endpoint cache_expires annotations are used, or entries don't expire.
+    //
+    "HybridCacheDefaultExpiration": null,
+    //
+    // Expiration for L1 (in-memory) cache. If not set, uses DefaultExpiration value.
+    // Set this shorter than DefaultExpiration to refresh local cache more frequently from Redis.
+    // Accepts PostgreSQL interval format.
+    //
+    "HybridCacheLocalCacheExpiration": null,
+    //
+    // Named caching profiles. Endpoints opt into a profile via the `cache_profile <name>` comment annotation;
+    // the profile then supplies the cache backend, default expiration, default key parameters, and per-parameter
+    // skip-cache conditions. Endpoints WITHOUT `cache_profile` continue to use the root cache configured above.
+    //
+    // Each profile object supports:
+    //   - "Enabled" (bool, default false): set to true to register the profile. Disabled profiles are ignored.
+    //   - "Type": "Memory" | "Redis" | "Hybrid" (required when enabled). Backends are pooled — all profiles of the
+    //     same type share one instance (one Memory cache, one Redis connection, one HybridCache singleton).
+    //     A backend is only instantiated if its type is used by the root or some enabled profile.
+    //   - "Expiration": PostgreSQL interval (e.g. "30 seconds", "5 minutes"); used as the default when the
+    //     endpoint has no `cache_expires` annotation. The annotation overrides this.
+    //   - "Parameters": cache-key parameter list with three semantics:
+    //       null/missing  → use ALL routine parameters (different requests → different entries).
+    //       []            → URL-only cache (one entry per endpoint, regardless of inputs).
+    //       ["x", "y"]    → use only these named parameters as the key.
+    //     The endpoint's `cached p1, p2` annotation overrides this list.
+    //   - "When": optional list of conditional rules. Each rule has:
+    //       - "Parameter": routine parameter name to inspect.
+    //       - "Value": scalar (exact match) or array (OR over entries). JSON null matches .NET null/DBNull (NOT empty string).
+    //       - "Then": "skip" → bypass the cache for this request; or a PostgreSQL interval like "30 seconds" → use this
+    //                 as the TTL override when writing.
+    //     Rules are evaluated in declaration order; first match wins. No match → fall through to "Expiration" above.
+    //     A rule's Parameter must be in the profile's "Parameters" list (or in the endpoint's @cached annotation),
+    //     otherwise the rule is dropped at startup with a Warning.
+    //
+    // Common patterns:
+    //   - Skip cache when a date is null (always-fresh data):
+    //       "When": [ { "Parameter": "to", "Value": null, "Then": "skip" } ]
+    //   - Tiered TTL by user role:
+    //       "When": [
+    //         { "Parameter": "tier", "Value": "free", "Then": "5 minutes" },
+    //         { "Parameter": "tier", "Value": "pro",  "Then": "1 hour" }
+    //       ]
+    //
+    // Unknown profile names referenced by `@cache_profile` cause startup to fail with a single error listing all
+    // typos and the offending endpoints. Unused profiles (registered but not referenced) log an Information warning.
+    //
+    // Three disabled example profiles below show all three Types and all four profile fields. Flip "Enabled": true
+    // on the one(s) you want to use.
+    //
+    "Profiles": {
+      "fast_memory": {
+        "Enabled": false,
+        "Type": "Memory",
+        "Expiration": "30 seconds",
+        "Parameters": ["user_id"]
+      },
+      "shared_redis": {
+        "Enabled": false,
+        "Type": "Redis",
+        "Expiration": "1 hour"
+      },
+      "date_range_hybrid": {
+        "Enabled": false,
+        "Type": "Hybrid",
+        "Expiration": "5 minutes",
+        "Parameters": ["from", "to"],
+        "When": [
+          { "Parameter": "to", "Value": null, "Then": "skip" }
+        ]
+      }
+    }
+  },
+
+  //
+  // Parameter validation options for validating endpoint parameters before database execution.
+  // Validation rules can be referenced in comment annotations using "validate _param using rule_name" syntax.
+  //
+  "ValidationOptions": {
+    "Enabled": true,
+    //
+    // Named validation rules that can be referenced in comment annotations.
+    // Default rules: not_null, not_empty, required, email
+    //
+    // Each rule can have:
+    // - Type: NotNull, NotEmpty, Required, Regex, MinLength, MaxLength
+    // - Pattern: Regular expression pattern for Regex type
+    // - MinLength: Minimum length for MinLength type
+    // - MaxLength: Maximum length for MaxLength type
+    // - Message: Error message with placeholders {0}=original name, {1}=converted name, {2}=rule name
+    // - StatusCode: HTTP status code to return (default: 400)
+    //
+    "Rules": {
+      "not_null": {
+        "Type": "NotNull",
+        "Message": "Parameter '{0}' cannot be null",
+        "StatusCode": 400
+      },
+      "not_empty": {
+        "Type": "NotEmpty",
+        "Message": "Parameter '{0}' cannot be empty",
+        "StatusCode": 400
+      },
+      "required": {
+        "Type": "Required",
+        "Message": "Parameter '{0}' is required",
+        "StatusCode": 400
+      },
+      "email": {
+        "Type": "Regex",
+        "Pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+        "Message": "Parameter '{0}' must be a valid email address",
+        "StatusCode": 400
+      }
+    }
+  },
+
+  //
+  // Rate Limiter settings to limit the number of requests from clients.
+  //
+  "RateLimiterOptions": {
+    "Enabled": false,
+    // Global defaults for rejected (rate-limited) requests. Each policy below may override either of these
+    // independently via its own "StatusCode"/"StatusMessage" — useful when one policy guards logins and
+    // another guards a public API and each needs its own message. A policy that omits them inherits these.
+    "StatusCode": 429,
+    "StatusMessage": "Too many requests. Please try again later.",
+    "DefaultPolicy": null,
+    //
+    // Named rate-limiter policies. The object key is the policy name (referenced from endpoints via the
+    // `rate_limiter_policy <name>` comment annotation, or used as `DefaultPolicy` above).
+    //
+    // Each policy has a `Type` of FixedWindow, SlidingWindow, TokenBucket, or Concurrency, and a set of
+    // type-specific tuning fields. Set `"Enabled": true` to register the policy at startup.
+    //
+    // Each policy may also set its own `StatusCode` and/or `StatusMessage` to override the global values
+    // above for requests rejected by that specific policy. Omit either to inherit the global default. The
+    // "fixed" policy below shows the commented-out fields.
+    //
+    // **Breaking change in 3.13.0**: this section was previously an array of objects with explicit `"Name"`
+    // properties. It is now an object keyed by policy name, matching `ValidationOptions:Rules` and
+    // `CacheOptions:Profiles`. Migrate by moving each policy's `Name` value to be the JSON key and dropping
+    // the `Name` field.
+    //
+    "Policies": {
+      // see https://learn.microsoft.com/en-us/aspnet/core/performance/rate-limit#fixed
+      "fixed": {
+        "Type": "FixedWindow",
+        "Enabled": false,
+        "PermitLimit": 100,
+        "WindowSeconds": 60,
+        "QueueLimit": 10,
+        "AutoReplenishment": true
+        // Override the global rejection response for this policy only (omit to inherit the global values):
+        // "StatusCode": 429,
+        // "StatusMessage": "Too many requests for this endpoint. Please slow down.",
+        //
+        // To partition this policy (per-user, per-IP, etc.) so each request gets its own bucket
+        // instead of sharing a single global one, add a "Partition" block. See the "per_user"
+        // policy below for a complete example.
+      },
+      // see https://learn.microsoft.com/en-us/aspnet/core/performance/rate-limit#sliding-window-limiter
+      "sliding": {
+        "Type": "SlidingWindow",
+        "Enabled": false,
+        "PermitLimit": 100,
+        "WindowSeconds": 60,
+        "SegmentsPerWindow": 6,
+        "QueueLimit": 10,
+        "AutoReplenishment": true
+      },
+      // see https://learn.microsoft.com/en-us/aspnet/core/performance/rate-limit#token-bucket-limiter
+      "bucket": {
+        "Type": "TokenBucket",
+        "Enabled": false,
+        "TokenLimit": 100,
+        "TokensPerPeriod": 10,
+        "ReplenishmentPeriodSeconds": 10,
+        "QueueLimit": 10,
+        "AutoReplenishment": true
+      },
+      // see https://learn.microsoft.com/en-us/aspnet/core/performance/rate-limit#concurrency-limiter
+      "concurrency": {
+        "Type": "Concurrency",
+        "Enabled": false,
+        "PermitLimit": 10,
+        "QueueLimit": 5,
+        "OldestFirst": true
+      },
+      //
+      // Example of a partitioned policy. With "Partition" set, each request resolves a partition key
+      // (per-user, per-IP, etc.) and gets its own bucket. Without "Partition", all requests under a
+      // policy share a single global bucket. Any of the four limiter Types above can be partitioned —
+      // FixedWindow is shown here only because it is the most common.
+      //
+      // Sources (ordered) — first source returning a non-empty key wins. Fallback "unpartitioned"
+      // is used if no source matches. Source types:
+      //   { "Type": "Claim",     "Name": "<claim type>" }
+      //   { "Type": "IpAddress" }
+      //   { "Type": "Header",    "Name": "<header name>" }
+      //   { "Type": "Static",    "Value": "<literal key>" }   ← terminal fallback
+      //
+      // BypassAuthenticated (bool, default false) — when true, authenticated users skip rate
+      // limiting entirely. Evaluated before Sources, useful for "throttle anonymous only".
+      //
+      "per_user": {
+        "Type": "FixedWindow",
+        "Enabled": false,
+        "PermitLimit": 100,
+        "WindowSeconds": 60,
+        "QueueLimit": 10,
+        "AutoReplenishment": true,
+        "Partition": {
+          "Sources": [
+            { "Type": "Claim",     "Name": "name_identifier" },
+            { "Type": "IpAddress" },
+            { "Type": "Static",    "Value": "anonymous" }
+          ],
+          "BypassAuthenticated": false
+        }
+      },
+      //
+      // Ready-to-use login throttle: 10 attempts per minute per client IP, with its own rejection
+      // message. Apply it to a login endpoint with `rate_limiter login_throttle` (or set it as
+      // DefaultPolicy). Set "Enabled": true to activate.
+      //
+      "login_throttle": {
+        "Type": "FixedWindow",
+        "Enabled": false,
+        "PermitLimit": 10,
+        "WindowSeconds": 60,
+        "QueueLimit": 0,
+        "AutoReplenishment": true,
+        "StatusMessage": "Too many login attempts. Please wait a minute and try again.",
+        "Partition": {
+          "Sources": [
+            { "Type": "IpAddress" }
+          ],
+          "BypassAuthenticated": false
+        }
+      }
+    }
+  },
+  
+  //
+  // Error handling options for NpgsqlRest middleware
+  //
+  "ErrorHandlingOptions": {
+    // Remove Type URL from error responses. Middleware automatically sets a default Type URL based on the HTTP status code that points to the RFC documentation.
+    "RemoveTypeUrl": false,
+    // Remove TraceId field from error responses. Useful in development and debugging scenarios to correlate logs with error responses.
+    "RemoveTraceId": true,
+    //
+    // Default policy name to use from the ErrorCodePolicies section.
+    //
+    "DefaultErrorCodePolicy": "Default",
+    //
+    // Timeout error mapping when command timeout occurs (see NpgsqlRest CommandTimeout setting).
+    //
+    "TimeoutErrorMapping": {"StatusCode": 504, "Title": "Command execution timed out", "Details": null, "Type": null}, // timeout error case -> 504 Gateway Timeout
+    //
+    // Named policies for mapping of PostgreSQL error codes to HTTP Status Codes.
+    //
+    // If routine raises these PostgreSQL error codes, endpoint will return these HTTP Status Codes.
+    // See https://www.postgresql.org/docs/current/errcodes-appendix.html
+    // Exception is timeout, which is not a PostgreSQL error code, but a special case when command timeout occurs.
+    //
+    // - StatusCode: HTTP status code to return.
+    // - Title: Optional title field in response JSON. When null, actual error message is used.
+    // - Details: Optional details field in response JSON. When null, PostgreSQL Error Code is used.
+    // - Type: Optional types field in response JSON. A URI reference [RFC3986] that identifies the problem type. Set to null to use default. Or RemoveTypeUrl to true to disable.
+    //
+    "ErrorCodePolicies": [{
+      "Name": "Default",
+      "ErrorCodes": {
+        "42501": {"StatusCode": 403, "Title": "Insufficient Privilege", "Details": null, "Type": null},   // query_canceled      -> 403 Forbidden
+        "57014": {"StatusCode": 205, "Title": "Cancelled", "Details": null, "Type": null},                // query_canceled      -> 205 Reset Content
+        "P0001": {"StatusCode": 400, "Title": null, "Details": null, "Type": null},                       // raise_exception     -> 400 Bad Request
+        "P0004": {"StatusCode": 400, "Title": null, "Details": null, "Type": null}                        // assert_failure      -> 400 Bad Request
+      }
+    }]
+  },
+  
+  //
+  // NpgsqlRest HTTP Middleware General Configuration
+  //
+  "NpgsqlRest": {
+    //
+    // Connection name to be used from the ConnectionStrings section or NULL to use the first available connection string.
+    //
+    "ConnectionName": null,
+    //
+    // Allow using multiple connections from the ConnectionStrings section. When set to true, the connection name can be set for individual Routines.
+    // Some routines might use the primary database connection string, while others might want to use a read-only connection string from the replica servers.
+    //
+    "UseMultipleConnections": false,
+    //
+    // Command timeout, after which the command will be cancelled and default timeout error policy will be applied. (see ErrorCodePolicies) 
+    // Value is in PostgreSQL interval format (for example: '30 seconds' or '30s', '1 minute' or '1min', etc.) or `null` to use the default timeout of 30 seconds.
+    //
+    "CommandTimeout": null,
+    //
+    // Filter schema names similar to this parameter or `null` to ignore this parameter.
+    //
+    "SchemaSimilarTo": null,
+    //
+    // Filter schema names NOT similar to this parameter or `null` to ignore this parameter.
+    //
+    "SchemaNotSimilarTo": null,
+    //
+    // List of schema names to be included or `null` to ignore this parameter.
+    //
+    "IncludeSchemas": null,
+    //
+    // List of schema names to be excluded or `null` to ignore this parameter.
+    //
+    "ExcludeSchemas": null,
+    //
+    // Filter names similar to this parameter or `null` to ignore this parameter.
+    //
+    "NameSimilarTo": null,
+    //
+    // Filter names NOT similar to this parameter or `null` to ignore this parameter.
+    //
+    "NameNotSimilarTo": null,
+    //
+    // List of names to be included or `null` to ignore this parameter.
+    //
+    "IncludeNames": null,
+    //
+    // List of names to be excluded or `null` to ignore this parameter.
+    //
+    "ExcludeNames": null,
+    //
+    // Configure how comment annotations behave and which routines become endpoints. `Ignore` creates all endpoints and ignores annotations. `ParseAll` creates all endpoints and parses annotations. `OnlyAnnotated` (default) creates only routines whose comment has a recognized exposure tag — an `HTTP` tag, or a plugin annotation that requests an endpoint (e.g. `mcp`); modifier-only comments (e.g. just `authorize`) create nothing. `OnlyWithHttpTag` is a backward-compatible alias of `OnlyAnnotated` (identical behavior; existing configs keep working).
+    //
+    "CommentsMode": "OnlyAnnotated",
+    //
+    // The URL prefix string for every URL created by the default URL builder or `null` to ignore the URL prefix.
+    //
+    "UrlPathPrefix": "/api",
+    //
+    // Convert all URL paths to kebab-case from the original PostgreSQL names.
+    //
+    "KebabCaseUrls": true,
+    //
+    // Convert all parameter names to camel case from the original PostgreSQL paramater names.
+    //
+    "CamelCaseNames": true,
+    //
+    // When set to true, it will force all created endpoints to require authorization. Authorization requirements for individual endpoints can be changed with the `EndpointCreated` function callback, or by using comment annotations.
+    //
+    "RequiresAuthorization": true,
+    //
+    // When this value is true, all connection events are logged (depending on the level). This is usually triggered by the PostgreSQL RAISE statements. 
+    // Set to false to turn off logging these events.
+    //
+    "LogConnectionNoticeEvents": true,
+    //
+    // MessageOnly - Log only connection messages. FirstStackFrameAndMessage - Log first stack frame and the message. FullStackAndMessage - Log full stack trace and message.
+    //
+    "LogConnectionNoticeEventsMode": "FirstStackFrameAndMessage",
+    //
+    // Set this option to true to log information for every executed command and query (including parameters and parameter values) in debug level.
+    //
+    "LogCommands": false,
+    //
+    // Set this option to true to include parameter values when logging commands. This only applies when `LogCommands` is true.
+    //
+    "LogCommandParameters": false,
+    //
+    // Set this option to false to suppress debug-level logs when endpoints are created.
+    // When true (default), debug logs are emitted for each endpoint creation showing URL and method.
+    //
+    "DebugLogEndpointCreateEvents": true,
+    //
+    // Set this option to false to suppress debug-level logs when comment annotations are parsed.
+    // When true (default), debug logs are emitted for each comment annotation that is successfully processed.
+    //
+    "DebugLogCommentAnnotationEvents": true,
+    //
+    // When not null, forces a method type for all created endpoints. Method types are `GET`, `PUT`, `POST`, `DELETE`, `HEAD`, `OPTIONS`, `TRACE`, `PATCH` or `CONNECT`. When this value is null (default), the method type is always `GET` when the routine volatility option is not volatile or the routine name starts with, `get_`, contains `_get_` or ends with `_get` (case-insensitive). Otherwise, it is `POST`. This option for individual endpoints can be changed with the `EndpointCreated` function callback, or by using comment annotations.
+    //
+    "DefaultHttpMethod": null,
+    //
+    // When not null, sets the request parameter position (request parameter types) for all created endpoints. Values are `QueryString` (parameters are sent using query string) or `BodyJson` (parameters are sent using JSON request body). When this value is null (default), request parameter type is `QueryString` for all `GET` and `DELETE` endpoints, otherwise, request parameter type is `BodyJson`. This option for individual endpoints can be changed with the `EndpointCreated` function callback, or by using comment annotations.
+    //
+    "DefaultRequestParamType": null,
+    //
+    // Sets the default behavior for handling NULL values in query string parameters.
+    // - `Ignore` (default): No special handling - empty strings stay as empty strings, "null" literal stays as "null" string.
+    // - `EmptyString`: Empty query string values are interpreted as NULL values. This limits sending empty strings via query strings.
+    // - `NullLiteral`: Literal string "null" (case insensitive) is interpreted as NULL value.
+    // This option for individual endpoints can be changed with the `EndpointCreated` function callback, or by using comment annotations.
+    //
+    "QueryStringNullHandling": "Ignore",
+    //
+    // Sets the default behavior for plain text responses when the execution returns NULL from the database.
+    // - `EmptyString` (default): Returns an empty string response with status code 200 OK.
+    // - `NullLiteral`: Returns a string literal "NULL" with status code 200 OK.
+    // - `NoContent`: Returns status code 204 NO CONTENT.
+    // This option for individual endpoints can be changed with the `EndpointCreated` function callback, or by using comment annotations.
+    //
+    "TextResponseNullHandling": "EmptyString",
+    //
+    // Configure how to send request headers to PostgreSQL routines execution: 
+    // - `Ignore` (default) don't send any request headers to routines. 
+    // - `Context` sets a context variable for the current session `context.headers` containing JSON string with current request headers. This executes `set_config('context.headers', headers, false)` before any routine executions. 
+    // - `Parameter` sends request headers to the routine parameter defined with the `RequestHeadersParameterName` option. Parameter with this name must exist, must be one of the JSON or text types and must have the default value defined. This option for individual endpoints can be changed with the `EndpointCreated` function callback, or by using comment annotations.
+    //
+    "RequestHeadersMode": "Parameter",
+    //
+    // Name of the context variable that will receive the request headers when RequestHeadersMode is set to Context.
+    //
+    "RequestHeadersContextKey": "request.headers",
+    //
+    // Sets a parameter name that will receive a request headers JSON when the `Parameter` value is used in `RequestHeadersMode` options. A parameter with this name must exist, must be one of the JSON or text types and must have the default value defined. This option for individual endpoints can be changed with the `EndpointCreated` function callback, or by using comment annotations.
+    //
+    "RequestHeadersParameterName": "_headers",
+    //
+    // When true, EVERY request is wrapped in an explicit BEGIN/COMMIT, and all `set_config` calls switch to the
+    // transaction-local form (`is_local=true`).
+    // Required when using a connection pooler in transaction mode (PgBouncer transaction-pool, AWS RDS Proxy in transaction mode,
+    // Supabase Pooler) — without this, the backend can be reused across unrelated requests, allowing GUC state (and the routine
+    // call itself) to leak or split mid-request. Default false to preserve existing behavior; safe to leave off when using Npgsql's native pool only.
+    //
+    "WrapInTransaction": false,
+    //
+    // Controls how JSON datetime strings are interpreted when bound to timestamp / timestamptz / time / timetz parameters.
+    // When true (default since 3.16.0), Z- and offset-bearing strings are converted to UTC, and naive strings (no offset, no Z)
+    // are assumed UTC. Stored values are then identical regardless of the host process's TZ environment.
+    // When false, the legacy pre-3.16.0 behavior is restored: DateTime.TryParse interprets the string in the host's local time
+    // zone, which silently shifts stored values by the host's UTC offset on non-UTC hosts. Only set to false if you have callers
+    // that depend on host-local interpretation of naive datetime strings and you cannot update them to send Z-suffixed values.
+    //
+    "JsonTimestampsAreUtc": true,
+    //
+    // SQL commands executed after any context is set but before the main routine call. Run in the same batch as the
+    // context `set_config` calls (no extra round-trip). Each entry can be either:
+    //   - A raw SQL string (always runs, no parameters), or
+    //   - An object with `Enabled`, `Sql`, and optional `Parameters`. Object entries are gated by `Enabled` (default false) —
+    //     set `"Enabled": true` to activate.
+    // Each parameter has a `Source` (Claim, RequestHeader, or IpAddress) and an optional `Name` (claim type or header name;
+    // ignored for IpAddress). Values are bound at request time via parameterized SQL.
+    // Common use case: setting `search_path` from a tenant claim for multi-tenant deployments.
+    // Combine with `WrapInTransaction = true` for transaction-local scoping (required for connection poolers in transaction mode).
+    //
+    "BeforeRoutineCommands": [
+      {
+        "Enabled": false,
+        "Sql": "select set_config('search_path', $1, true)",
+        "Parameters": [
+          { "Source": "Claim", "Name": "tenant_id" }
+        ]
+      }
+    ],
+    //
+    // Add the unique NpgsqlRest instance id request header with this name to the response or set to null to ignore.
+    //
+    "InstanceIdRequestHeaderName": null,
+    //
+    // Custom request headers dictionary that will be added to NpgsqlRest requests. Note: these values are added to the request headers dictionary before they are sent as a context or parameter to the PostgreSQL routine and as such not visible to the browser debugger.
+    //
+    "CustomRequestHeaders": {
+    },
+    //
+    // Allowlist of environment variable names available to {name} placeholder substitution in comment annotation values (response headers, custom parameters, HTTP custom type calls), alongside the routine's parameters. Resolved once at startup (a value change requires a restart). Array form lists names (a missing variable becomes the empty string); object form maps name -> default {"WEATHER_API_KEY":""} where the default is used when the variable is absent. Names are matched case-insensitively, and a routine parameter of the same name takes precedence. SECURITY: a value used in a RESPONSE header is sent to the client - reserve secrets (API keys, tokens) for outbound HTTP custom type calls, and use response headers only for non-secret values (e.g. server/environment name).
+    //
+    "AvailableEnvVars": [],
+    //
+    // Name of the request ID header that will be used to track requests. This is used to correlate requests with server event streaming connection ids.
+    //
+    "ExecutionIdHeaderName": "X-NpgsqlRest-ID",
+    //
+    // Default server-sent event notice message level: INFO, NOTICE, WARNING.
+    // When SSE path is set, generate SSE events for PostgreSQL notice messages with this level or higher.
+    // This can be overridden for individual endpoints using comment annotations.
+    //
+    "DefaultServerSentEventsEventNoticeLevel": "INFO",
+    //
+    // Collection of custom server-sent events response headers that will be added to the response when connected to the endpoint that is configured to return server-sent events.
+    //
+    "ServerSentEventsResponseHeaders": {
+    },
+    //
+    // When true (default), log a one-time warning per endpoint when a RAISE at the configured SSE notice level fires inside a routine
+    // that has no @sse or @sse_publish annotation. Notices are logged but NOT broadcast to SSE subscribers; the warning surfaces the
+    // likely missing annotation. Inactive when no endpoint in the build participates in SSE publishing — projects that don't use SSE
+    // pay zero overhead and see no warnings.
+    //
+    "WarnUnboundServerSentEventsNotices": true,
+    //
+    // Options for handling PostgreSQL routines (functions and procedures)
+    //
+    "RoutineOptions": {
+      //
+      // Set to false to disable the routine source (PostgreSQL functions and procedures). Default is true.
+      //
+      "Enabled": true,
+      //
+      // Name separator for parameter names when using custom type parameters. 
+      // Parameter names will be in the format: {ParameterName}{CustomTypeParameterSeparator}{CustomTypeFieldName}. When NULL, default underscore is used.
+      // This is used when using custom types for parameters. For example: with "create type custom_type1 as (value text);" and parameter "_p custom_type1", this name will be merged into "_p_value"
+      //
+      "CustomTypeParameterSeparator": null,
+      //
+      // List of PostgreSQL routine language names to include. If NULL, all languages are included. Names are case-insensitive.
+      //
+      "IncludeLanguages": null,
+      //
+      // List of PostgreSQL routine language names to exclude. If NULL, "C" and "INTERNAL" are excluded by default. Names are case-insensitive.
+      //
+      "ExcludeLanguages": null,
+      //
+      // When true, composite type columns in return tables are serialized as nested JSON objects.
+      // For example, a table column "req" of type "my_request(id int, name text)" becomes {"req": {"id": 1, "name": "test"}}
+      // instead of the default flat structure {"id": 1, "name": "test"}.
+      // Default is false for backward compatibility.
+      //
+      "NestedJsonForCompositeTypes": false,
+      //
+      // When true, nested composite types and arrays of composite types within composite fields
+      // are serialized as JSON objects/arrays instead of PostgreSQL tuple strings.
+      // For example, a nested composite "(1,x)" becomes {"id":1,"name":"x"} and
+      // an array of composites ["(1,a)","(2,b)"] becomes [{"id":1,"name":"a"},{"id":2,"name":"b"}].
+      // Default is true.
+      //
+      "ResolveNestedCompositeTypes": true
+    },
+
+    //
+    // Options for different upload handlers and general upload settings
+    //
+    "UploadOptions": {
+      "Enabled": false,
+      "LogUploadEvent": true,
+      "LogUploadParameters": false,
+      //
+      // Handler that will be used when upload handler or handlers are not specified.
+      //
+      "DefaultUploadHandler": "large_object",
+      //
+      // Gets or sets a value indicating whether the default upload metadata parameter should be used.
+      //
+      "UseDefaultUploadMetadataParameter": false,
+      //
+      // Name of the default upload metadata parameter. This parameter is used to pass metadata to the upload handler. The metadata is passed as a JSON object.
+      //
+      "DefaultUploadMetadataParameterName": "_upload_metadata",
+      //
+      // Gets or sets a value indicating whether the default upload metadata context key should be used.
+      //
+      "UseDefaultUploadMetadataContextKey": false,
+      //
+      // Name of the default upload metadata context key. This key is used to pass the metadata to the upload handler. The metadata is passed as a JSON object.
+      //
+      "DefaultUploadMetadataContextKey": "request.upload_metadata",
+      //
+      // Upload handlers specific settings.
+      //
+      "UploadHandlers": {
+        //
+        // General settings for all upload handlers
+        //
+        "StopAfterFirstSuccess": false,
+        // csv string containing mime type patters, set to null to ignore
+        "IncludedMimeTypePatterns": null,
+        // csv string containing mime type patters, set to null to ignore
+        "ExcludedMimeTypePatterns": null,
+        "BufferSize": 8192, // Buffer size for the upload handlers file_system and large_object, in bytes. Default is 8192 bytes (8 KB).
+        "TextTestBufferSize": 4096, // Buffer sample size for testing textual content, in bytes. Default is 4096 bytes (4 KB).
+        "TextNonPrintableThreshold": 5, // Threshold for non-printable characters in the text buffer. Default is 5 non-printable characters.
+        "AllowedImageTypes": "jpeg, png, gif, bmp, tiff, webp", // Comma-separated list of allowed image types when checking images.
+        //
+        // When set, authenticated user claims are included in the row metadata JSON parameter ($4) under this key name.
+        // Set to null or empty string to disable adding claims to row metadata. Example: "claims" adds {"claims": {...}} to metadata.
+        // Access in SQL: (_meta->'claims'->>'name_identifier')
+        //
+        "RowCommandUserClaimsKey": "claims",
+        //
+        // Enables upload handlers for the NpgsqlRest endpoints that uses PostgreSQL Large Objects API
+        //
+        "LargeObjectEnabled": true,
+        "LargeObjectKey": "large_object",
+        "LargeObjectCheckText": false,
+        "LargeObjectCheckImage": false,
+        //
+        // Enables upload handlers for the NpgsqlRest endpoints that uses file system
+        //
+        "FileSystemEnabled": true,
+        "FileSystemKey": "file_system",
+        "FileSystemPath": "/tmp/uploads",
+        "FileSystemUseUniqueFileName": true,
+        "FileSystemCreatePathIfNotExists": true,
+        "FileSystemCheckText": false,
+        "FileSystemCheckImage": false,
+        //
+        // Enables upload handlers for the NpgsqlRest endpoints that uploads CSV files to a row command
+        //
+        "CsvUploadEnabled": true,
+        "CsvUploadKey": "csv",
+        "CsvUploadCheckFileStatus": true,
+        "CsvUploadDelimiterChars": ",",
+        "CsvUploadHasFieldsEnclosedInQuotes": true,
+        "CsvUploadSetWhiteSpaceToNull": true,
+        //
+        // $1 - row index (1-based), $2 - parsed value text array, $3 - result of previous row command, $4 - JSON metadata for upload
+        //
+        "CsvUploadRowCommand": "call process_csv_row($1,$2,$3,$4)",
+        //
+        // Enables upload handlers for the NpgsqlRest endpoints that uploads Excel files to a row command
+        //
+        "ExcelUploadEnabled": true,
+        "ExcelKey": "excel",
+        "ExcelSheetName": null, // null to use the first available
+        "ExcelAllSheets": false,
+        "ExcelTimeFormat": "HH:mm:ss",
+        "ExcelDateFormat": "yyyy-MM-dd",
+        "ExcelDateTimeFormat": "yyyy-MM-dd HH:mm:ss",
+        "ExcelRowDataAsJson": false,
+        //
+        // $1 - row index (1-based), $2 - parsed value text array, $3 - result of previous row command, $4 - JSON metadata for upload
+        //
+        "ExcelUploadRowCommand": "call process_excel_row($1,$2,$3,$4)"
+      }
+    },
+
+    //
+    // Table format handlers for custom rendering of set/record results.
+    // When an endpoint has @table_format = <name> custom parameter, the matching handler renders the response.
+    //
+    "TableFormatOptions": {
+      //
+      // Enable or disable table format handlers. When false, @table_format annotations are ignored.
+      //
+      "Enabled": false,
+      //
+      // Built-in HTML table handler. Renders results as an HTML table for easy copy-paste to Excel.
+      // Activated by @table_format = html annotation on PostgreSQL functions.
+      //
+      "HtmlEnabled": true,
+      //
+      // The key name used to match @table_format = <key> annotation. Default is "html".
+      //
+      "HtmlKey": "html",
+      //
+      // Content written before the HTML table. Typically a CSS style block.
+      // Set to null to omit.
+      //
+      "HtmlHeader": "<style>table{font-family:Calibri,Arial,sans-serif;font-size:11pt;border-collapse:collapse}th,td{border:1px solid #d4d4d4;padding:4px 8px}th{background-color:#f5f5f5;font-weight:600}</style>",
+      //
+      // Content written after the closing HTML table tag.
+      // Set to null to omit.
+      //
+      "HtmlFooter": null,
+      //
+      // Built-in Excel (.xlsx) handler using SpreadCheetah. Renders results as an Excel spreadsheet download.
+      // Activated by @table_format = excel annotation on PostgreSQL functions.
+      //
+      "ExcelEnabled": true,
+      //
+      // The key name used to match @table_format = <key> annotation. Default is "excel".
+      //
+      "ExcelKey": "excel",
+      //
+      // Worksheet name. When null, uses the routine name.
+      //
+      "ExcelSheetName": null,
+      //
+      // Excel Format Code for DateTime cells. When null, uses SpreadCheetah default (yyyy-MM-dd HH:mm:ss).
+      // Uses Excel Format Codes (not .NET format strings). Examples: "yyyy-mm-dd", "dd/mm/yyyy hh:mm", "m/d/yy h:mm".
+      //
+      "ExcelDateTimeFormat": null,
+      //
+      // Excel Format Code for numeric cells. When null, uses Excel default (General).
+      // Uses Excel Format Codes (not .NET format strings). Examples: "#,##0.00", "0.00", "#,##0".
+      //
+      "ExcelNumericFormat": null
+    },
+
+    //
+    // Authentication options for NpgsqlRest endpoints
+    //
+    "AuthenticationOptions": {
+      //
+      // Authentication type used with the Login endpoints to set the authentication type for the new `ClaimsIdentity` created by the login. This value must be set to non-null when using login endpoints, otherwise, the following error will raise: `SignInAsync when principal.Identity.IsAuthenticated is false is not allowed when AuthenticationOptions.RequireAuthenticatedSignIn is true.` If the value is not set and the login endpoint is present, it will automatically get the database name from the connection string.
+      //
+      "DefaultAuthenticationType": null,
+
+      //
+      // The default column name in the data reader which will be used to read the value to determine the success or failure of the login operation. If this column is not present, the success is when the endpoint returns any records. If this column is present, it must be either a boolean to indicate success or a numeric value to indicate the HTTP Status Code to return. If this column is present and retrieves a numeric value, that value is assigned to the HTTP Status Code and the login will authenticate only when this value is 200.
+      //
+      "StatusColumnName": "status",
+      //
+      // The default column name in the data reader which will be used to read the value of the authentication scheme of the login process. If this column is not present in the login response the default authentication scheme is used. Return new value to use a different authentication scheme with the login endpoint.
+      //
+      "SchemeColumnName": "scheme",
+      //
+      // The default column name in the data reader which will return a response body message for the login operation where writing to body is possible.
+      //
+      "BodyColumnName": "body",
+      //
+      // The default column name in the data reader which will set the response content type for the login operation where writing to body is possible.
+      //
+      "ResponseTypeColumnName": "application/json",
+      //
+      // The default column name in the data reader which will be used to read the value of the hash of the password. 
+      // If this column is present, the value will be used to verify the password from the password parameter. 
+      // Password parameter is the first parameter which name contains the value of PasswordParameterNameContains. 
+      // If verification fails, the login will fail and the HTTP Status Code will be set to 404 Not Found.
+      //
+      "HashColumnName": "hash",
+      //
+      // The default name of the password parameter. 
+      // The first parameter which name contains this value will be used as the password parameter. 
+      // This is used to verify the password from the password parameter when login endpoint returns a hash of the password (see HashColumnName).
+      //
+      "PasswordParameterNameContains": "pass",
+      //
+      // Default claim type for user id.
+      //
+      "DefaultUserIdClaimType": "user_id",
+      //
+      // Default claim type for username.
+      //
+      "DefaultNameClaimType": "user_name",
+      //
+      // Default claim type for user roles.
+      //
+      "DefaultRoleClaimType": "user_roles",
+      //
+      // Default claim type for user display name.
+      //
+      "DefaultDisplayNameClaimType": "display_name",
+      //
+      // If true, return any response from auth endpoints (login and logout) if response hasn't been written by auth handler. For cookie auth, this will return full record to response as returned by the routine. For bearer token auth, this will be ignored because bearer token auth writes its own response (with tokens). This option will also be ignored if message column is present (see BodyColumnName option).
+      //
+      "SerializeAuthEndpointsResponse": false,
+      //
+      // Don't write real parameter values when logging parameters from auth endpoints and obfuscate instead. This prevents user credentials including password from ending up in application logs.
+      //
+      "ObfuscateAuthParameterLogValues": true,
+      //
+      // Command that is executed when the password verification fails. There are three positional and optional parameters: 
+      // - $1: Authentication scheme used for the login (if parameter exists, type text).
+      // - $2: User id used for the login (if parameter exists, type text).
+      // - $3: Username used for the login (if parameter exists, type text).
+      //
+      "PasswordVerificationFailedCommand": null,
+      //
+      // Command that is executed when the password verification succeeds. There are three positional and optional parameters:
+      // - $1: authentication scheme used for the login (if parameter exists, type text).
+      // - $2: user id used for the login (if parameter exists, type text).
+      // - $3: username used for the login (if parameter exists, type text).
+      //
+      "PasswordVerificationSucceededCommand": null,
+      //
+      // Enable setting authenticated user claims to context variables automatically. See ContextKeyClaimsMapping and ClaimsJsonContextKey options. You can set this individually for each request by using UserContext endpoint property or user_context comment annotation.
+      // Note: For proxy endpoints, when user_context is enabled, these values are also forwarded as HTTP headers to the upstream proxy using the context key names.
+      //
+      "UseUserContext": false,
+      //
+      // Mapping of context keys to user claim names. Keys are the context variable names and values are the user claim names. When <see cref="UseUserContext"/> is enabled, the user claims from will be automatically mapped to the context variables.
+      //
+      "ContextKeyClaimsMapping": {
+        "request.user_id": "user_id",
+        "request.user_name": "user_name",
+        "request.user_roles": "user_roles"
+      },
+      //
+      // Context key that is used to set context variable for all available user claims. When this option is not null, and user is authenticated, the user claims will be serialized to JSON value and set to the context variable.
+      //
+      "ClaimsJsonContextKey": null,
+      //
+      // IP address context key that is used to set context variable for the IP address. When this option is not null, the IP address will be set to the context variable when <see cref="UseUserContext"/> is enabled and even when user is not authenticated.
+      //
+      "IpAddressContextKey": "request.ip_address",
+      //
+      // Enable mapping authenticated user claims to parameters by name automatically. See ParameterNameClaimsMapping and ClaimsJsonParameterName options. You can set this individually for each request by using UseUserParameters endpoint property or user_parameters comment annotation.
+      // Note: For proxy endpoints, when user_params is enabled, these values are also forwarded as query string parameters to the upstream proxy.
+      //
+      "UseUserParameters": false,
+      //
+      // Mapping of parameter names to user claim names. Keys are the parameter names and values are the user claim names. When <see cref="UseUserParameters"/> is enabled, the user claims from will be automatically mapped to the parameters.
+      //
+      "ParameterNameClaimsMapping": {
+        "_user_id": "user_id",
+        "_user_name": "user_name",
+        "_user_roles": "user_roles"
+      },
+      //
+      // Parameter name that is used to set value for all available user claims. When this option is not null, and user is authenticated, the user claims will be serialized to JSON value and set to the parameter with this name.
+      //
+      "ClaimsJsonParameterName": "_user_claims",
+      //
+      // IP address parameter name that is used to set parameter value for the IP address. When this option is not null, the IP address will be set to the parameter when <see cref="UseUserContext"/> is enabled and even when user is not authenticated.
+      //
+      "IpAddressParameterName": "_ip_address",
+      //
+      // Url path that will be used for the login endpoint. If NULL, the login endpoint will not be created.
+      // Login endpoint expects a PostgreSQL command that will be executed to authenticate the user that follow this convention:
+      //
+      // - Must return at least one record when authentication is successful. If no records are returned endpoint will return 401 Unauthorized.
+      // - If record is returned, the authentication is successful, if not set in StatusColumnName column otherwise.
+      // - All records will be added to user principal claim collection where column name is claim type and column value is claim value, 
+      //   except for four special columns defined in StatusColumnName, SchemeColumnName, BodyColumnName and HashColumnName options:
+      //
+      // - If "StatusColumnName" is present in the returned record, it must be either boolean (true for success, false for failure) or numeric (HTTP Status Code, 200 for success, anything else for failure). If not present, the success is when the endpoint returns any records.
+      // - If "SchemeColumnName" is present in the returned record, it must be text value that defines the authentication scheme to use for the login.
+      // - If "BodyColumnName" is present in the returned record, it must be text value that defines the message to return to the client as response body where possible. This only works for authentication that doesn't write response body (cookie authentication).
+      // - If "HashColumnName" is present in the returned record, it must be text value that defines the hash of the password. Password parameter is the first parameter which name contains the value of PasswordParameterNameContains option. If verification fails, the login will fail and the HTTP Status Code will be set to 404 Not Found.
+      //
+      "LoginPath": null,
+      //
+      // Url path that will be used for the logout endpoint. If NULL, the logout endpoint will not be created.
+      // Login endpoint expects a PostgreSQL command that performs the logout or the sign-out operation.
+      //
+      // If the routine doesn't return any data, the default authorization scheme is signed out. 
+      // Any values returned will be interpreted as scheme names (converted to string) to sign out.
+      //
+      "LogoutPath": null,
+      //
+      // Settings for basic authentication support.
+      // Basic authentication is a simple authentication scheme built into the HTTP protocol.
+      // It expects request header `Authorization: Basic base64(username:password)` where username and password are the credentials for the user.
+      //
+      "BasicAuth": {
+        //
+        // Enable or disable the Basic Authentication support.
+        //
+        "Enabled": false,
+        //
+        // The default realm for the Basic Authentication. If not set, "NpgsqlRest" will be used.
+        //
+        "Realm": null,
+        //
+        // Default users dictionary for the Basic Authentication. Key is the username and value is the password or password hash depending on the UseDefaultPasswordHasher option.
+        // Users can be set on individual endpoints using multiple annotations: basic_authentication [ username ] [ password ]
+        //
+        "Users": { },
+        //
+        // When using Basic Authentication, set this to Required to enforce SSL/TLS connection. 
+        // Use Warning to issue a warning in the log when connection is not secure.
+        // Use Ignore to allow Basic Authentication (debug level log will show a warning).
+        //
+        "SslRequirement": "Required", // Ignore, Warning, Required
+        //
+        // Use default password hasher for Basic Authentication to verify the password when Password is set on endpoint or options.
+        // When this is true, Password set in configuration, endpoint or header (depending on PasswordHashLocation) is expected to be a hashed with default hasher.
+        //
+        "UseDefaultPasswordHasher": true,
+        //
+        // PostgreSQL command executed when the Basic Authentication is challenged. 
+        // Same convention applies as with "LoginPath" command. See "NpgsqlRest.LoginPath" option for details.
+        // Use this command to validate the username and password and/or return user claims.
+        // 
+        // Positional parameters:
+        // - $1: Username from basic authentication header (if parameter exists, type text).
+        // - $2: Password from basic authentication header (if parameter exists, type text).
+        // - $3: Password is valid, true or false. If endpoint or configuration has a password defined, it will be validated. 
+        //       This the result of that validation or NULL of no password is defined. 
+        //       This allows for password to be validated before the command and use command for additional user claims. (if parameter exists, type boolean).
+        // - $4: Basic authentication realm (if parameter exists, type text).
+        // - $5: Endpoint path (if parameter exists, type text).
+        //
+        "ChallengeCommand": null
+      }
+    },
+    
+    //
+    // Enable or disable the generation of HTTP files for NpgsqlRest endpoints.
+    // See more on HTTP files at: 
+    // https://marketplace.visualstudio.com/items?itemName=humao.rest-client or 
+    // https://learn.microsoft.com/en-us/aspnet/core/test/http-files?view=aspnetcore-8.0
+    //
+    "HttpFileOptions": {
+      "Enabled": false,
+      //
+      // Options for HTTP file generation:
+      // - File: Generate HTTP files in the file system.
+      // - Endpoint: Generate Endpoint(s) with HTTP file(s) content.
+      // - Both: Generate HTTP files in the file system and Endpoint(s) with HTTP file(s) content.
+      //
+      "Option": "File",
+      //
+      // File name. If not set, the database name will be used if connection string is set. 
+      // If neither ConnectionString nor Name is set, the file name will be "npgsqlrest".
+      //
+      "Name": null,
+      //
+      // The pattern to use when generating file names. {0} is database name, {1} is schema suffix with underline when FileMode is set to Schema.
+      // Use this property to set a custom file name.
+      // .http extension will be added automatically.
+      //
+      "NamePattern": "{0}_{1}",
+      //
+      // Adds comment header to above request based on PostgreSQL routine.
+      // - None: skip.
+      // - Simple: Add name, parameters and return values to comment header. This default.
+      // - Full: Add the entire routine code as comment header.
+      //
+      "CommentHeader": "Simple",
+      //
+      // When CommentHeader is set to Simple or Full, set to true to include routine comments in comment header.
+      //
+      "CommentHeaderIncludeComments": true,
+      //
+      // - Database: to create one http file for entire database.
+      // - Schema: to create one http file for each schema.
+      //
+      "FileMode": "Schema",
+      //
+      // Set to true to overwrite existing files.
+      //
+      "FileOverwrite": true
+    },
+
+    //
+    // Enable or disable the generation of OpenAPI files for NpgsqlRest endpoints.
+    //
+    "OpenApiOptions": {
+      "Enabled": false,
+      //
+      // File name for the generated OpenAPI file. Set to null to skip the file generation.
+      //
+      "FileName": "npgsqlrest_openapi.json",
+      //
+      // URL path for the OpenAPI endpoint. Set to null to skip the endpoint generation.
+      //
+      "UrlPath": "/openapi.json",
+      //
+      // Set to true to overwrite existing files.
+      //
+      "FileOverwrite": true,
+      //
+      // The title of the OpenAPI document. This appears in the "info" section of the OpenAPI specification.
+      // If not set, the database name from the ConnectionString will be used.
+      //
+      "DocumentTitle": null,
+      //
+      // The version of the OpenAPI document. This appears in the "info" section of the OpenAPI specification.
+      // When null, default is "1.0.0".
+      //
+      "DocumentVersion": "1.0.0",
+      //
+      // Optional description of the API. This appears in the "info" section of the OpenAPI specification.
+      //
+      "DocumentDescription": null,
+      //
+      // Include current server information in the "servers" section of the OpenAPI document.
+      //
+      "AddCurrentServer": true,
+      //
+      // Additional server entries to add to the "servers" section of the OpenAPI document.
+      // Each server entry must have "Url" property and optional "Description" property.
+      //
+      "Servers": [/*{"Url": "https://api.example.com", "Description": "Production server"}*/],
+      //
+      // Security schemes to include in the OpenAPI document.
+      // If not specified, a default Bearer authentication scheme will be added for endpoints requiring authorization.
+      // Supported types: "Http" (for Bearer/Basic auth) and "ApiKey" (for Cookie/Header/Query auth).
+      // Examples:
+      // - Bearer token: {"Name": "bearerAuth", "Type": "Http", "Scheme": "Bearer", "BearerFormat": "JWT"}
+      // - Cookie auth: {"Name": "cookieAuth", "Type": "ApiKey", "In": ".AspNetCore.Cookies", "ApiKeyLocation": "Cookie"}
+      // - Basic auth: {"Name": "basicAuth", "Type": "Http", "Scheme": "Basic"}
+      //
+      "SecuritySchemes": [
+        /*{
+          "Name": "bearerAuth",
+          "Type": "Http",
+          "Scheme": "Bearer",
+          "BearerFormat": "JWT",
+          "Description": "JWT Bearer token authentication"
+        },
+        {
+          "Name": "cookieAuth",
+          "Type": "ApiKey",
+          "In": ".AspNetCore.Cookies",
+          "ApiKeyLocation": "Cookie",
+          "Description": "Cookie-based authentication"
+        }*/
+      ],
+      //
+      // Filters that control which endpoints appear in the OpenAPI document. The HTTP endpoints
+      // themselves are unaffected — only their inclusion in the generated spec is. Combine with
+      // the per-routine `openapi hide` / `openapi tag <name>` comment annotations for fine-grained
+      // control. Use case: expose a partner-facing document that hides the internal anonymous
+      // surface (health, login, probes) and the internal-only schemas.
+      //
+      // Schema allow-list. When non-empty, only endpoints whose routine schema appears here are
+      // documented. Empty array (default) = document every schema.
+      //
+      "IncludeSchemas": [/* "partner" */],
+      //
+      // Schema deny-list. Any endpoint whose routine schema appears here is skipped. Applied
+      // alongside IncludeSchemas — both must pass. Empty array (default) = no schema exclusions.
+      //
+      "ExcludeSchemas": [/* "internal" */],
+      //
+      // PostgreSQL-style SIMILAR TO pattern matched against the routine NAME. When set, only
+      // routines whose name matches are documented. `_` matches one char, `%` matches any
+      // sequence; the rest of SIMILAR TO syntax (`|`, `*`, `+`, `?`, `(...)`, `[...]`) is
+      // supported. Anchored (must cover the whole name). Default null = no name filter.
+      //
+      "NameSimilarTo": null,
+      //
+      // PostgreSQL-style SIMILAR TO pattern matched against the routine NAME for EXCLUSION.
+      // Matches are skipped. Same syntax as NameSimilarTo. Applied alongside it — both must
+      // pass. Default null = no name exclusion.
+      //
+      "NameNotSimilarTo": null,
+      //
+      // When true, only authenticated endpoints (those that require authorization) are
+      // documented. Anonymous endpoints — typically health, login, probes — are omitted. Useful
+      // for partner-facing documents. Default false = document everything.
+      //
+      "RequiresAuthorizationOnly": false
+    },
+    //
+    // Enable or disable the MCP (Model Context Protocol) server endpoint. Disabled by default. Tools are NEVER auto-exposed: only routines explicitly opted in with the `mcp` comment annotation become MCP tools. Implements MCP specification 2025-11-25.
+    //
+    "McpOptions": {
+      "Enabled": false,
+      //
+      // URL path for the MCP endpoint (Streamable HTTP, single JSON-RPC endpoint).
+      //
+      "UrlPath": "/mcp",
+      //
+      // serverInfo.name reported in the MCP initialize handshake. When null, the database name from the connection string is used (falling back to "NpgsqlRest").
+      //
+      "ServerName": null,
+      //
+      // serverInfo.version reported in the MCP initialize handshake.
+      //
+      "ServerVersion": "1.0.0",
+      //
+      // Optional server-level instructions returned in the MCP initialize handshake (high-level guidance for the agent).
+      //
+      "Instructions": null,
+      //
+      // Optional text appended to every MCP tool description. Null = no-op. Use for short shared context the agent should always see (e.g. "Read-only Acme CRM."); for longer server-wide guidance prefer Instructions.
+      //
+      "ToolDescriptionSuffix": null,
+      //
+      // Name of an ASP.NET rate-limiter policy applied to the whole /mcp endpoint. Null = no limiting. A routine's own rate_limiter annotation does not carry to MCP (tools/call bypasses route middleware), so this is how MCP traffic is throttled. The named policy must be registered on the host (AddRateLimiter + UseRateLimiter); an unregistered name surfaces as the framework's error when a request hits the endpoint.
+      //
+      "RateLimiterPolicy": null,
+      //
+      // Allowed values of the HTTP Origin header (DNS-rebinding protection for the Streamable HTTP transport). A request whose Origin is present but matches neither this list nor the server's own origin is rejected with 403. Requests without an Origin header (e.g. server-to-server) are allowed. Empty = only same-origin browser requests pass.
+      //
+      "AllowedOrigins": [],
+      //
+      // OAuth 2.1 Resource Server settings. Token validation reuses the host's bearer authentication; these keys configure the transport gate and the Protected Resource Metadata document (RFC 9728). NpgsqlRest is not an Authorization Server — point AuthorizationServers at an external IdP.
+      //
+      "Authorization": {
+        //
+        // When true, every MCP request requires an authenticated principal. When false (default), anonymous is allowed and a tool's own `authorize` annotation still gates it per call.
+        //
+        "RequireAuthorization": false,
+        //
+        // Authorization Server issuer URL(s) advertised in the Protected Resource Metadata. When empty, no PRM document is served.
+        //
+        "AuthorizationServers": [],
+        //
+        // Optional scopes advertised in the Protected Resource Metadata (scopes_supported).
+        //
+        "ScopesSupported": [],
+        //
+        // Canonical resource URI tokens must target (RFC 8707 audience) and the PRM "resource" value. Null = derived from the request (scheme + host + UrlPath).
+        //
+        "Audience": null,
+        //
+        // Path the Protected Resource Metadata document is served at. Null = the RFC 9728 well-known path derived from UrlPath.
+        //
+        "ProtectedResourceMetadataPath": null,
+        //
+        // When true, tools/list hides tools the calling principal could not run (their routine's authorize/role check would deny it). When false (default), every opted-in tool is listed (discoverable) and authorization is enforced on tools/call.
+        //
+        "FilterToolsByRole": false
+      }
+    },
+
+    //
+    // Enable or disable the generation of TypeScript/Javascript client source code files for NpgsqlRest endpoints.
+    //
+    "ClientCodeGen": {
+      "Enabled": false,
+      //
+      // File path for the generated code. Set to null to skip the code generation. Use {0} to set schema name when BySchema is true
+      //
+      "FilePath": null,
+      //
+      //  Force file overwrite.
+      //
+      "FileOverwrite": true,
+      //
+      // Include current host information in the URL prefix.
+      //
+      "IncludeHost": true,
+      //
+      // Set the custom host prefix information.
+      //
+      "CustomHost": null,
+      //
+      // Adds comment header to above request based on PostgreSQL routine
+      // Set None to skip.
+      // Set Simple (default) to add name, parameters and return values to comment header.
+      // Set Full to add the entire routine code as comment header.
+      //
+      "CommentHeader": "Simple",
+      //
+      // When CommentHeader is set to Simple or Full, set to true to include routine comments in comment header.
+      //
+      "CommentHeaderIncludeComments": true,
+      //
+      // Create files by PostgreSQL schema. File name will use formatted FilePath where {0} is the schema name in pascal case.
+      //
+      "BySchema": true,
+      //
+      // Set to true to include status code in response: {status: response.status, response: model}
+      //
+      "IncludeStatusCode": true,
+      //
+      // Create separate file with global types {name}Types.d.ts
+      //
+      "CreateSeparateTypeFile": true,
+      //
+      // Emit interfaces with the `export` keyword so they can be imported by other modules. When true and CreateSeparateTypeFile is true, the separate type file becomes an importable module ({name}Types.ts) instead of an ambient {name}Types.d.ts, and the client file imports the named types from it. No effect when SkipTypes is true.
+      //
+      "ExportTypes": false,
+      //
+      // Module name to import "baseUrl" constant, instead of defining it in a module.
+      //
+      "ImportBaseUrlFrom": null,
+      //
+      // Module name to import "parseQuery" function, instead of defining it in a module.
+      //
+      "ImportParseQueryFrom": null,
+      //
+      // Include optional parameter `parseUrl: (url: string) => string = url=>url` that will parse the constructed URL.
+      //
+      "IncludeParseUrlParam": false,
+      //
+      // Include optional parameter `parseRequest: (request: RequestInit) => RequestInit = request=>request` that will parse the constructed request.
+      //
+      "IncludeParseRequestParam": false,
+      //
+      // Header lines on each auto-generated source file. Default is ["// autogenerated at {0}", "", ""] where {0} is the current timestamp.
+      //
+      "HeaderLines": [
+        "// autogenerated at {0}",
+        ""
+      ],
+      //
+      // Array of routine names to skip (without schema)
+      //
+      "SkipRoutineNames": [],
+      //
+      // Array of generated function names to skip (without schema)
+      //
+      "SkipFunctionNames": [],
+      //
+      // Array of url paths to skip
+      //
+      "SkipPaths": [],
+      //
+      // Array of schema names to skip
+      //
+      "SkipSchemas": [],
+      //
+      // Default TypeScript type for JSON types
+      //
+      "DefaultJsonType": "any",
+      //
+      // Use routine name instead of endpoint name when generating function names.
+      //
+      "UseRoutineNameInsteadOfEndpoint": false,
+      //
+      // Export URLs as constants in the generated code.
+      //
+      "ExportUrls": false,
+      //
+      // Skip generating types and produce pure JavaScript code. Setting this to true will also change the .ts extension to .js where applicable.
+      //
+      "SkipTypes": false,
+      //
+      // Keep TypeScript models unique, meaning models with the same fields and types will be merged into one model with the name of the last model. This significantly reduces the number of generated models.
+      //
+      "UniqueModels": false,
+      //
+      // Name of the XSRF Token Header (Anti-forgery Token). This is used in FORM POSTS to the server when Anti-forgery is enabled. Currently, only Upload requests use FORM POST.
+      //
+      "XsrfTokenHeaderName": null,
+      //
+      // Export event sources create functions for streaming events.
+      //
+      "ExportEventSources": true,
+      //
+      // List of custom imports to add to the generated code. It adds line to a file. Use full expression like `import { MyType } from './my-type';`
+      //
+      "CustomImports": [],
+      //
+      // Dictionary of custom headers to add to each request in generated code. Header key is automatically quoted if it doesn't contain quotes.
+      //
+      "CustomHeaders": {},
+      //
+      // When true, include PostgreSQL schema name in the generated type names to avoid name collisions. Set to false to simplify type names when no name collisions are expected.
+      //
+      "IncludeSchemaInNames": true,
+      //
+      // Expression to parse error response. Only used when IncludeStatusCode is true.
+      //
+      "ErrorExpression": "await response.json()",
+      //
+      // TypeScript type for error response. Only used when IncludeStatusCode is true.
+      //
+      "ErrorType": "{status: number; title: string; detail?: string | null} | undefined"
+    },
+
+    //
+    // HTTP client functionality for annotated composite types.
+    // Allows PostgreSQL functions to make HTTP requests by using specially annotated types as parameters.
+    //
+    "HttpClientOptions": {
+      //
+      // Enable HTTP client functionality for annotated types.
+      //
+      "Enabled": false,
+      //
+      // Default name for the response status code field within annotated types.
+      //
+      "ResponseStatusCodeField": "status_code",
+      //
+      // Default name for the response body field within annotated types.
+      //
+      "ResponseBodyField": "body",
+      //
+      // Default name for the response headers field within annotated types.
+      //
+      "ResponseHeadersField": "headers",
+      //
+      // Default name for the response content type field within annotated types.
+      //
+      "ResponseContentTypeField": "content_type",
+      //
+      // Default name for the response success field within annotated types.
+      //
+      "ResponseSuccessField": "success",
+      //
+      // Default name for the response error message field within annotated types.
+      //
+      "ResponseErrorMessageField": "error_message",
+      //
+      // Global kill switch for HTTP type response caching. When false, the '@cache' directive on
+      // individual types is ignored and every request fires a fresh outbound call. Caching is opt-in
+      // per type via the '@cache <interval>' type-comment directive.
+      //
+      "CacheEnabled": true,
+      //
+      // Maximum number of distinct cached HTTP responses held in memory. Once full, new responses are
+      // not cached (existing entries are still served and expire normally).
+      //
+      "MaxCacheEntries": 10000,
+      //
+      // Interval in seconds at which expired cached HTTP responses are pruned from memory.
+      //
+      "CachePruneIntervalSeconds": 60
+    },
+
+    //
+    // Reverse proxy functionality for NpgsqlRest endpoints.
+    // When an endpoint is marked with 'proxy' annotation, incoming requests are forwarded to another URL.
+    //
+    "ProxyOptions": {
+      //
+      // Enable proxy functionality for annotated endpoints.
+      //
+      "Enabled": false,
+      //
+      // Base URL (host) for proxy requests (e.g., "https://api.example.com").
+      // When set, proxy endpoints will forward requests to this host + the original path.
+      //
+      "Host": null,
+      //
+      // Default timeout for all proxy requests. Format: "HH:MM:SS" or PostgreSQL interval.
+      //
+      "DefaultTimeout": "00:00:30",
+      //
+      // When true, original request headers are forwarded to the proxy target.
+      //
+      "ForwardHeaders": true,
+      //
+      // Headers to exclude from forwarding to the proxy target.
+      //
+      "ExcludeHeaders": ["Host", "Content-Length", "Transfer-Encoding"],
+      //
+      // When true, forward response headers from proxy back to client.
+      //
+      "ForwardResponseHeaders": true,
+      //
+      // Response headers to exclude from forwarding back to client.
+      //
+      "ExcludeResponseHeaders": ["Transfer-Encoding", "Content-Length"],
+      //
+      // Default name for the proxy response status code parameter.
+      //
+      "ResponseStatusCodeParameter": "_proxy_status_code",
+      //
+      // Default name for the proxy response body parameter.
+      //
+      "ResponseBodyParameter": "_proxy_body",
+      //
+      // Default name for the proxy response headers parameter.
+      //
+      "ResponseHeadersParameter": "_proxy_headers",
+      //
+      // Default name for the proxy response content type parameter.
+      //
+      "ResponseContentTypeParameter": "_proxy_content_type",
+      //
+      // Default name for the proxy response success parameter.
+      //
+      "ResponseSuccessParameter": "_proxy_success",
+      //
+      // Default name for the proxy response error message parameter.
+      //
+      "ResponseErrorMessageParameter": "_proxy_error_message",
+      //
+      // When true, for upload endpoints marked as proxy, the raw multipart/form-data content is forwarded directly to the upstream proxy instead of being processed locally. This allows the upstream service to handle file uploads. When false (default), upload endpoints with proxy annotation will process uploads locally and upload metadata will not be available to the proxy.
+      //
+      "ForwardUploadContent": false
+    },
+
+    //
+    // SQL file source for generating REST API endpoints from .sql files.
+    // Each SQL file must contain exactly one statement.
+    //
+    "SqlFileSource": {
+      //
+      // Enable or disable SQL file source endpoints. Default is false.
+      //
+      "Enabled": false,
+      //
+      // Glob pattern for SQL files, e.g. "sql/**/*.sql", "queries/*.sql".
+      // Supports * (any chars), ** (recursive, any including /), ? (single char).
+      // Empty string disables the feature.
+      //
+      "FilePattern": "",
+      //
+      // How comment annotations are processed for SQL file endpoints.
+      // Possible values: Ignore, ParseAll, OnlyAnnotated, OnlyWithHttpTag.
+      // OnlyAnnotated (default; OnlyWithHttpTag is a back-compat alias) requires an explicit
+      // HTTP annotation (e.g., "-- HTTP GET") for a SQL file to become an endpoint.
+      //
+      "CommentsMode": "OnlyAnnotated",
+      //
+      // Which comments in the SQL file to parse as annotations.
+      // Possible values: All (default), Header (only comments before the first statement).
+      //
+      "CommentScope": "All",
+      //
+      // Behavior when a SQL file fails to parse or describe.
+      // Possible values: Skip (default — log error, continue), Throw (halt startup).
+      //
+      "ErrorMode": "Exit",
+      //
+      // Prefix for result keys in multi-command JSON responses.
+      // Default keys are "result1", "result2", etc.
+      // Override per-result with the positional @result annotation in the SQL file.
+      //
+      "ResultPrefix": "result",
+      //
+      // When true, queries returning a single column produce a flat JSON array of values
+      // (e.g., ["a", "b", "c"]) instead of an array of objects (e.g., [{"col": "a"}, {"col": "b"}]).
+      // This matches the behavior of PostgreSQL functions returning setof single values.
+      //
+      "UnnamedSingleColumnSet": true,
+      //
+      // When true, composite type columns in return results are serialized as nested JSON objects.
+      // For example, a column "data" of type "my_type(id int, name text)" becomes {"data": {"id": 1, "name": "test"}}
+      // instead of the default flat structure {"id": 1, "name": "test"}.
+      // Default is false for backward compatibility. Can also be enabled per-endpoint with the 'nested' annotation.
+      //
+      "NestedJsonForCompositeTypes": false,
+      //
+      // When true, non-query commands (BEGIN, COMMIT, SET, DO blocks, etc.) in multi-command SQL files
+      // are still executed but excluded from the JSON response result keys.
+      // Default is true.
+      //
+      "SkipNonQueryCommands": true,
+      //
+      // When true, multi-command SQL file endpoints include the full SQL text in command logs.
+      // When false (default), only the file path and statement count are logged.
+      // Single-command SQL files always log the SQL text regardless of this setting.
+      // This only applies when LogCommands is true.
+      //
+      "LogCommandText": false
+    }
+  }
+}
diff --git a/NpgsqlRest/Proxy/ProxyRequestHandler.cs b/NpgsqlRest/Proxy/ProxyRequestHandler.cs
index 856982ae..eedd8d81 100644
--- a/NpgsqlRest/Proxy/ProxyRequestHandler.cs
+++ b/NpgsqlRest/Proxy/ProxyRequestHandler.cs
@@ -1,5 +1,6 @@
 using System.Diagnostics;
 using System.Text;
+using System.Text.Json.Nodes;
 using Npgsql;
 using NpgsqlRest.HttpClientType;
 
@@ -69,12 +70,49 @@ public static async Task<ProxyResponse> InvokeAsync(
 
         // Build the target URL with user claim parameters
         var targetUrl = isSelfCall && _selfClient is not null
-            ? BuildSelfTargetUrl(host, context.Request, parameters)
-            : BuildTargetUrl(host, context.Request, parameters);
+            ? BuildSelfTargetUrl(host)
+            : BuildTargetUrl(host, context.Request);
 
         // Determine HTTP method
         var method = endpoint.ProxyMethod?.ToString().ToUpperInvariant() ?? context.Request.Method;
 
+        // Forward server-filled HTTP Custom Type field params to the upstream the same way the
+        // endpoint takes its own parameters. Placement mirrors the endpoint, NOT the HTTP verb:
+        //  - a param designated as the body parameter (@body_parameter_name) carries the raw body;
+        //  - otherwise RequestParamType decides: BodyJson -> merged JSON body (when the proxy method
+        //    can physically carry a JSON body), QueryString -> query string.
+        // Additive — the verbatim incoming request is still forwarded; this only adds filled values.
+        string? effectiveBody = requestBody;
+        var forwardParams = GetForwardableParams(endpoint, parameters);
+        if (forwardParams is not null)
+        {
+            var bodyParam = FindForwardableBodyParam(endpoint, forwardParams);
+            if (bodyParam is not null)
+            {
+                if (bodyParam.Value is not null && bodyParam.Value != DBNull.Value)
+                {
+                    effectiveBody = bodyParam.Value.ToString();
+                }
+                forwardParams.Remove(bodyParam);
+            }
+
+            if (forwardParams.Count > 0)
+            {
+                bool mergeIntoBody = bodyParam is null
+                    && endpoint.RequestParamType == RequestParamType.BodyJson
+                    && HasRequestBody(method)
+                    && IsJsonContentType(context.Request.ContentType);
+                if (mergeIntoBody)
+                {
+                    effectiveBody = MergeParamsIntoJsonBody(effectiveBody, forwardParams);
+                }
+                else
+                {
+                    targetUrl = AppendParamsToQuery(targetUrl, forwardParams);
+                }
+            }
+        }
+
         Logger?.LogDebug("Proxy starting {Method} request to '{Url}'", method, targetUrl);
 
         try
@@ -108,7 +146,7 @@ public static async Task<ProxyResponse> InvokeAsync(
                     method,
                     targetUrl,
                     proxyHeaders,
-                    requestBody,
+                    effectiveBody,
                     context.Request.ContentType,
                     cancellationToken);
 
@@ -127,7 +165,7 @@ public static async Task<ProxyResponse> InvokeAsync(
                 };
             }
 
-            using var request = await CreateRequestAsync(context, method, targetUrl, requestBody, proxyOptions, userContextHeaders);
+            using var request = await CreateRequestAsync(context, method, targetUrl, effectiveBody, proxyOptions, userContextHeaders);
             using var cts = CreateTimeoutCancellationTokenSource(proxyOptions.DefaultTimeout, cancellationToken);
 
             var client = isSelfCall && _selfClient is not null ? _selfClient : SharedClient;
@@ -171,56 +209,178 @@ public static async Task<ProxyResponse> InvokeAsync(
     /// <summary>
     /// Build target URL for self-referencing proxy calls. Uses the host as the full path (no appending of request path).
     /// </summary>
-    private static string BuildSelfTargetUrl(string host, HttpRequest request, NpgsqlParameterCollection? parameters)
+    private static string BuildSelfTargetUrl(string host)
     {
         // For self-calls, host IS the full relative path (e.g., /api/hello-world)
         // Don't append the incoming request path
         return host;
     }
 
-    private static string BuildTargetUrl(string host, HttpRequest request, NpgsqlParameterCollection? parameters)
+    private static string BuildTargetUrl(string host, HttpRequest request)
     {
         // Ensure host doesn't end with /
         host = host.TrimEnd('/');
 
-        // Get the path and query string
+        // Get the path and query string. Automatic (server-filled) parameters — user claims, IP,
+        // HTTP Custom Type fields, resolved-parameter expressions — are appended consistently by the
+        // unified forwarding step in InvokeAsync (query string or JSON body, per the endpoint shape).
         var path = request.Path.Value ?? "";
         var queryString = request.QueryString.Value ?? "";
 
-        // Append user claim and IP address parameters to query string
-        if (parameters is not null)
+        return $"{host}{path}{queryString}";
+    }
+
+    private static bool IsJsonContentType(string? contentType) =>
+        contentType is not null && contentType.Contains("json", StringComparison.OrdinalIgnoreCase);
+
+    /// <summary>
+    /// True when a parameter is filled by the server (not supplied by the client) and so should be
+    /// forwarded to the proxy upstream the same way the endpoint receives it. All automatic parameter
+    /// sources are treated consistently: user claims, IP address, HTTP Custom Type fields (the expanded
+    /// per-field params on DB functions), and resolved-parameter expressions. Single-composite HTTP
+    /// params (SQL-file shape, CustomTypeName null) are not forwarded.
+    /// </summary>
+    private static bool IsAutomaticParam(RoutineEndpoint endpoint, NpgsqlRestParameter p)
+    {
+        if (p.IsFromUserClaims || p.IsIpAddress)
         {
-            var additionalParams = new StringBuilder();
-            foreach (NpgsqlParameter param in parameters)
+            return true;
+        }
+        if (p.TypeDescriptor.CustomType is not null
+            && p.TypeDescriptor.CustomTypeName is not null
+            && HttpClientTypes.Definitions.ContainsKey(p.TypeDescriptor.CustomType))
+        {
+            return true;
+        }
+        if (endpoint.ResolvedParameterExpressions is not null
+            && (endpoint.ResolvedParameterExpressions.ContainsKey(p.ActualName)
+                || endpoint.ResolvedParameterExpressions.ContainsKey(p.ConvertedName)))
+        {
+            return true;
+        }
+        return false;
+    }
+
+    /// <summary>
+    /// The forwardable parameter (if any) designated as the request body parameter
+    /// (<c>@body_parameter_name</c>) — it carries the raw request body rather than a query/JSON field.
+    /// </summary>
+    private static NpgsqlRestParameter? FindForwardableBodyParam(RoutineEndpoint endpoint, List<NpgsqlRestParameter> parameters)
+    {
+        if (!endpoint.HasBodyParameter)
+        {
+            return null;
+        }
+        foreach (var p in parameters)
+        {
+            if (string.Equals(endpoint.BodyParameterName, p.ConvertedName, StringComparison.Ordinal)
+                || string.Equals(endpoint.BodyParameterName, p.ActualName, StringComparison.Ordinal))
             {
-                if (param is NpgsqlRestParameter restParam &&
-                    (restParam.IsFromUserClaims || restParam.IsIpAddress) &&
-                    restParam.Value is not null && restParam.Value != DBNull.Value)
-                {
-                    if (additionalParams.Length > 0)
-                    {
-                        additionalParams.Append('&');
-                    }
-                    additionalParams.Append(Uri.EscapeDataString(restParam.ConvertedName));
-                    additionalParams.Append('=');
-                    additionalParams.Append(Uri.EscapeDataString(restParam.Value.ToString() ?? ""));
-                }
+                return p;
             }
+        }
+        return null;
+    }
 
-            if (additionalParams.Length > 0)
+    /// <summary>
+    /// Collects all server-filled (automatic) parameters to forward to the proxy upstream.
+    /// </summary>
+    private static List<NpgsqlRestParameter>? GetForwardableParams(RoutineEndpoint endpoint, NpgsqlParameterCollection? parameters)
+    {
+        if (parameters is null)
+        {
+            return null;
+        }
+        List<NpgsqlRestParameter>? result = null;
+        for (var i = 0; i < parameters.Count; i++)
+        {
+            if (parameters[i] is NpgsqlRestParameter rp && IsAutomaticParam(endpoint, rp))
             {
-                if (string.IsNullOrEmpty(queryString))
-                {
-                    queryString = "?" + additionalParams.ToString();
-                }
-                else
-                {
-                    queryString = queryString + "&" + additionalParams.ToString();
-                }
+                (result ??= []).Add(rp);
             }
         }
+        return result;
+    }
 
-        return $"{host}{path}{queryString}";
+    private static string AppendParamsToQuery(string url, List<NpgsqlRestParameter> parameters)
+    {
+        var sb = new StringBuilder();
+        foreach (var p in parameters)
+        {
+            if (p.Value is null || p.Value == DBNull.Value)
+            {
+                continue;
+            }
+            if (sb.Length > 0)
+            {
+                sb.Append('&');
+            }
+            sb.Append(Uri.EscapeDataString(p.ConvertedName));
+            sb.Append('=');
+            sb.Append(Uri.EscapeDataString(p.Value.ToString() ?? ""));
+        }
+        if (sb.Length == 0)
+        {
+            return url;
+        }
+        return url.Contains('?') ? $"{url}&{sb}" : $"{url}?{sb}";
+    }
+
+    private static string MergeParamsIntoJsonBody(string? body, List<NpgsqlRestParameter> parameters)
+    {
+        JsonObject obj;
+        if (string.IsNullOrWhiteSpace(body))
+        {
+            obj = [];
+        }
+        else
+        {
+            try
+            {
+                obj = JsonNode.Parse(body) as JsonObject ?? [];
+            }
+            catch
+            {
+                obj = [];
+            }
+        }
+        foreach (var p in parameters)
+        {
+            obj[p.ConvertedName] = ToJsonNode(p);
+        }
+        return obj.ToJsonString();
+    }
+
+    // Typed JSON value for a server-filled HTTP-type field, following the field's declared type:
+    // numeric/boolean fields become JSON numbers/bools, json fields are embedded as JSON, the rest
+    // become JSON strings. The value was already typed by the HTTP-type fill (asText vs native).
+    private static JsonNode? ToJsonNode(NpgsqlRestParameter p)
+    {
+        var v = p.Value;
+        if (v is null || v == DBNull.Value)
+        {
+            return null;
+        }
+        if (p.TypeDescriptor.IsJson)
+        {
+            var s = v.ToString();
+            if (string.IsNullOrEmpty(s))
+            {
+                return null;
+            }
+            try { return JsonNode.Parse(s); }
+            catch { return JsonValue.Create(s); }
+        }
+        return v switch
+        {
+            bool b => JsonValue.Create(b),
+            int i => JsonValue.Create(i),
+            long l => JsonValue.Create(l),
+            short sh => JsonValue.Create((int)sh),
+            decimal dec => JsonValue.Create(dec),
+            double d => JsonValue.Create(d),
+            _ => JsonValue.Create(v.ToString())
+        };
     }
 
     private static async Task<HttpRequestMessage> CreateRequestAsync(
diff --git a/NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs b/NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs
new file mode 100644
index 00000000..d29fac17
--- /dev/null
+++ b/NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs
@@ -0,0 +1,272 @@
+using WireMock.Server;
+using WireMock.RequestBuilders;
+using WireMock.ResponseBuilders;
+using WireMock;
+using WireMock.Types;
+using WireMock.Util;
+
+namespace NpgsqlRestTests;
+
+public static partial class Database
+{
+    public static void ProxyHttpTypeProbeTest()
+    {
+        // Functions that have BOTH an HTTP Custom Type parameter AND a (passthrough) @proxy.
+        // The HTTP type points at the HttpClientType WireMock (port 50953); the @proxy (no host)
+        // forwards to ProxyOptions.Host = http://localhost:50954, preserving the incoming path.
+        // The function bodies raise, to prove they are NOT executed (passthrough).
+        script.Append($@"
+        create type proxy_httptype_probe as (
+            body text,
+            status_code int,
+            success boolean,
+            error_message text
+        );
+        comment on type proxy_httptype_probe is 'GET http://localhost:{WireMockFixture.Port}/httptype-source';
+
+        -- GET endpoint: server-filled HTTP-type fields are forwarded on the proxy QUERY STRING.
+        create function proxy_with_httptype(
+            _response proxy_httptype_probe default null
+        )
+        returns void
+        language plpgsql
+        as
+        $$
+        begin
+            raise exception 'passthrough proxy must NOT execute the function';
+        end;
+        $$;
+        comment on function proxy_with_httptype(proxy_httptype_probe) is 'HTTP GET
+allow_anonymous
+proxy';
+
+        -- POST endpoint: server-filled HTTP-type fields are merged into the proxy JSON BODY,
+        -- alongside the client's original body fields.
+        create function proxy_post_with_httptype(
+            _payload text default null,
+            _response proxy_httptype_probe default null
+        )
+        returns void
+        language plpgsql
+        as
+        $$
+        begin
+            raise exception 'passthrough proxy must NOT execute the function';
+        end;
+        $$;
+        comment on function proxy_post_with_httptype(text, proxy_httptype_probe) is 'HTTP POST
+allow_anonymous
+proxy';
+
+        -- POST endpoint, but params come from the QUERY STRING (param_type query). Placement must
+        -- follow RequestParamType, not the verb: the HTTP-type fields go to the proxy QUERY even
+        -- though the method is POST and a JSON body is sent.
+        create function proxy_post_query_with_httptype(
+            _response proxy_httptype_probe default null
+        )
+        returns void
+        language plpgsql
+        as
+        $$
+        begin
+            raise exception 'passthrough proxy must NOT execute the function';
+        end;
+        $$;
+        comment on function proxy_post_query_with_httptype(proxy_httptype_probe) is 'HTTP POST
+allow_anonymous
+param_type query
+proxy';
+
+        -- Resolved-parameter expression: _token is filled server-side from a DB lookup. It is an
+        -- automatic parameter and must be forwarded to the proxy just like claims / IP / HTTP-type.
+        create table proxy_resolved_tokens (user_name text primary key, api_token text not null);
+        insert into proxy_resolved_tokens values ('alice', 'TOKEN-ALICE-123');
+
+        create function proxy_resolved_param(
+            _name text,
+            _token text default null
+        )
+        returns void
+        language plpgsql
+        as
+        $$
+        begin
+            raise exception 'passthrough proxy must NOT execute the function';
+        end;
+        $$;
+        comment on function proxy_resolved_param(text, text) is 'HTTP GET
+allow_anonymous
+_token = select api_token from proxy_resolved_tokens where user_name = {{_name}}
+proxy';
+");
+    }
+}
+
+[Collection("TestFixture")]
+public class ProxyHttpTypeProbeTest : IClassFixture<WireMockFixture>, IClassFixture<ProxyWireMockFixture>
+{
+    private readonly TestFixture _test;
+    private readonly WireMockServer _httpTypeServer;  // 50953 — the HTTP Custom Type target
+    private readonly WireMockServer _proxyServer;     // 50954 — the @proxy target
+
+    public ProxyHttpTypeProbeTest(TestFixture test, WireMockFixture httpType, ProxyWireMockFixture proxy)
+    {
+        _test = test;
+        _httpTypeServer = httpType.Server;
+        _proxyServer = proxy.Server;
+        _httpTypeServer.Reset();
+        _proxyServer.Reset();
+    }
+
+    // GET proxy: the auto-filled HTTP-type fields are forwarded on the proxy's QUERY STRING,
+    // alongside the client's original query — "same signature, sent upstream".
+    [Fact]
+    public async Task HttpType_fields_are_forwarded_on_proxy_query_for_get()
+    {
+        int httpTypeCalls = 0;
+        _httpTypeServer
+            .Given(Request.Create().WithPath("/httptype-source").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                Interlocked.Increment(ref httpTypeCalls);
+                return new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = "FETCHED-FROM-HTTPTYPE", DetectedBodyType = BodyType.String }
+                };
+            }));
+
+        // Proxy target echoes the exact URL (incl. query) it received.
+        _proxyServer
+            .Given(Request.Create().WithPath("/api/proxy-with-httptype/").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+                new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = $"PROXY-URL:[{req.Url}]", DetectedBodyType = BodyType.String }
+                }));
+
+        using var response = await _test.Client.GetAsync("/api/proxy-with-httptype/?clientParam=XYZ");
+        var content = await response.Content.ReadAsStringAsync();
+
+        response.StatusCode.Should().Be(HttpStatusCode.OK);   // proxy response (function never ran)
+        content.Should().StartWith("PROXY-URL:[");
+        httpTypeCalls.Should().Be(1);                          // HTTP-type call fired
+
+        // The proxy received the client's original query …
+        content.Should().Contain("clientParam=XYZ");
+        // … AND the auto-filled HTTP-type fields:
+        content.Should().Contain("responseBody=FETCHED-FROM-HTTPTYPE");
+        content.Should().Contain("responseStatusCode=200");
+    }
+
+    // POST proxy: the auto-filled HTTP-type fields are merged into the proxy JSON BODY, alongside the
+    // client's original body fields — and a large body field never ends up in the URL.
+    [Fact]
+    public async Task HttpType_fields_are_merged_into_proxy_json_body_for_post()
+    {
+        int httpTypeCalls = 0;
+        _httpTypeServer
+            .Given(Request.Create().WithPath("/httptype-source").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                Interlocked.Increment(ref httpTypeCalls);
+                return new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = "FETCHED-FROM-HTTPTYPE", DetectedBodyType = BodyType.String }
+                };
+            }));
+
+        // Proxy target echoes the exact body it received.
+        _proxyServer
+            .Given(Request.Create().WithPath("/api/proxy-post-with-httptype/").UsingPost())
+            .RespondWith(Response.Create().WithCallback(req =>
+                new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = $"PROXY-BODY:[{req.Body}]", DetectedBodyType = BodyType.String }
+                }));
+
+        using var response = await _test.Client.PostAsync(
+            "/api/proxy-post-with-httptype/",
+            new StringContent("{\"payload\": \"CLIENT\"}", System.Text.Encoding.UTF8, "application/json"));
+        var content = await response.Content.ReadAsStringAsync();
+
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+        httpTypeCalls.Should().Be(1);
+
+        // The client's original body field is preserved …
+        content.Should().Contain("\"payload\":\"CLIENT\"");
+        // … and the auto-filled HTTP-type fields are merged in, typed (string / number / bool):
+        content.Should().Contain("\"responseBody\":\"FETCHED-FROM-HTTPTYPE\"");
+        content.Should().Contain("\"responseStatusCode\":200");
+        content.Should().Contain("\"responseSuccess\":true");
+    }
+
+    // Placement follows RequestParamType, NOT the HTTP verb. This POST endpoint is configured with
+    // `param_type query`, so even though the method is POST and the client sends a JSON body, the
+    // HTTP-type fields must go to the proxy QUERY STRING — not merged into the body.
+    [Fact]
+    public async Task HttpType_fields_follow_request_param_type_not_verb()
+    {
+        int httpTypeCalls = 0;
+        _httpTypeServer
+            .Given(Request.Create().WithPath("/httptype-source").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                Interlocked.Increment(ref httpTypeCalls);
+                return new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = "FETCHED-FROM-HTTPTYPE", DetectedBodyType = BodyType.String }
+                };
+            }));
+
+        // Proxy target echoes both the URL and the body it received.
+        _proxyServer
+            .Given(Request.Create().WithPath("/api/proxy-post-query-with-httptype/").UsingPost())
+            .RespondWith(Response.Create().WithCallback(req =>
+                new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = $"URL:[{req.Url}] BODY:[{req.Body}]", DetectedBodyType = BodyType.String }
+                }));
+
+        using var response = await _test.Client.PostAsync(
+            "/api/proxy-post-query-with-httptype/",
+            new StringContent("{\"ignored\": \"CLIENTBODY\"}", System.Text.Encoding.UTF8, "application/json"));
+        var content = await response.Content.ReadAsStringAsync();
+
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+        httpTypeCalls.Should().Be(1);
+
+        // HTTP-type fields forwarded on the QUERY (param_type query), in query form …
+        content.Should().Contain("responseBody=FETCHED-FROM-HTTPTYPE");
+        // … and NOT merged into the JSON body (which is forwarded verbatim).
+        content.Should().NotContain("\"responseBody\":");
+        content.Should().Contain("CLIENTBODY");
+    }
+
+    // Consistency: a resolved-parameter expression is an automatic parameter too, so it is forwarded
+    // to the proxy exactly like claims / IP / HTTP-type fields (here: a GET → query string).
+    [Fact]
+    public async Task Resolved_param_is_forwarded_to_proxy_consistently()
+    {
+        _proxyServer
+            .Given(Request.Create().WithPath("/api/proxy-resolved-param/").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+                new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = $"PROXY-URL:[{req.Url}]", DetectedBodyType = BodyType.String }
+                }));
+
+        using var response = await _test.Client.GetAsync("/api/proxy-resolved-param/?name=alice");
+        var content = await response.Content.ReadAsStringAsync();
+
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+        content.Should().Contain("name=alice");             // client query forwarded verbatim
+        content.Should().Contain("token=TOKEN-ALICE-123");  // resolved (automatic) param forwarded
+    }
+}
diff --git a/README.md b/README.md
index dc80d3f1..e5d2c3c0 100644
--- a/README.md
+++ b/README.md
@@ -140,6 +140,22 @@ Same pattern for PostgreSQL functions via `comment on function ... is '...'`. No
 
 **[npgsqlrest.github.io](https://npgsqlrest.github.io/)** — getting started, configuration, annotations, examples.
 
+## Claude Code skill
+
+A [Claude Code](https://claude.com/claude-code) skill that teaches the agent how to build with NpgsqlRest — both endpoint sources (database functions/procedures/tables/views and `.sql` files), the full annotation set, configuration, HTTP custom types, proxy, caching, auth, SSE, and MCP. It lives in [`.claude/skills/npgsqlrest/`](.claude/skills/npgsqlrest/) and bundles a complete annotation reference and a full annotated `appsettings.json`.
+
+Install it for your own NpgsqlRest projects — per-user (available everywhere):
+
+```bash
+mkdir -p "$HOME/.claude/skills/npgsqlrest"
+for f in SKILL.md annotations-reference.md configuration-reference.jsonc; do
+  curl -fsSL "https://raw.githubusercontent.com/NpgsqlRest/NpgsqlRest/master/.claude/skills/npgsqlrest/$f" \
+    -o "$HOME/.claude/skills/npgsqlrest/$f"
+done
+```
+
+…or scope it to a single project by copying those three files into `<your-project>/.claude/skills/npgsqlrest/`. The agent then loads it automatically when you work on NpgsqlRest SQL, annotations, or config. The two reference files are generated from `npgsqlrest --annotations` and `npgsqlrest --config`; regenerate them with those commands if your installed version differs.
+
 ## About
 
 NpgsqlRest is built and maintained by [Vedran Bilopavlović](https://www.linkedin.com/in/vb-software/). The C# library, parser, codegen, and runtime are hand-written, covered by 1,800+ integration tests, and battle-tested in production.
diff --git a/changelog/v3.18.0.md b/changelog/v3.18.0.md
index 33042a0a..aa6c08b0 100644
--- a/changelog/v3.18.0.md
+++ b/changelog/v3.18.0.md
@@ -1,6 +1,6 @@
 # Changelog v3.18.0
 
-## Version [3.18.0](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.18.0)
+## Version [3.18.0](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.18.0) (2026-06-23)
 
 [Full Changelog](https://github.com/NpgsqlRest/NpgsqlRest/compare/3.17.0...3.18.0)
 
diff --git a/changelog/v3.18.1.md b/changelog/v3.18.1.md
new file mode 100644
index 00000000..6719cbe8
--- /dev/null
+++ b/changelog/v3.18.1.md
@@ -0,0 +1,40 @@
+# Changelog v3.18.1
+
+## Version [3.18.1](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.18.1) (2026-06-23)
+
+[Full Changelog](https://github.com/NpgsqlRest/NpgsqlRest/compare/3.18.0...3.18.1)
+
+Patch release that makes **all automatic (server-filled) parameters forward to proxy endpoints consistently**, in the endpoint's native parameter shape.
+
+## What changed
+
+When an endpoint is a proxy, the parameters that NpgsqlRest fills server-side are now forwarded to the upstream **uniformly**, regardless of source:
+
+- **user claims** (claim-mapped parameters),
+- **IP address** parameter,
+- **HTTP Custom Type** fields (the auto-filled `responseBody` / `responseStatusCode` / … on a routine with an HTTP Custom Type parameter),
+- **resolved-parameter expressions** (values looked up server-side via SQL).
+
+All of them follow the **same placement rule**, which mirrors how the endpoint itself receives parameters — **not** the HTTP verb:
+
+- The parameter designated as the body parameter (`@body_parameter_name`) carries the **raw request body**.
+- Otherwise placement follows the endpoint's **`RequestParamType`**: `QueryString` → appended to the proxy **query string**; `BodyJson` → merged into the proxy **JSON body** (typed: numbers, booleans, embedded JSON, or strings), when the proxy method can carry a JSON body.
+
+This is **additive**: the verbatim incoming request is still forwarded; the automatic parameters are added on top, so the upstream receives the same parameter set the routine would have.
+
+### Why
+
+Previously the behavior was inconsistent: user-claim and IP parameters were always appended to the query string, HTTP Custom Type fields and resolved parameters were not forwarded at all, and a passthrough proxy discarded the auto-filled values entirely (the outbound HTTP Custom Type call fired but its result went nowhere). Now every automatic parameter behaves the same way.
+
+### Behavior change to note
+
+User-claim and IP parameters now follow `RequestParamType` like every other automatic parameter. For a `QueryString` endpoint (the default for GET) they remain in the query string, exactly as before. For a `BodyJson` endpoint they are now merged into the JSON body rather than forced onto the query string. Method does not decide placement — `RequestParamType` does (a POST endpoint can use `param_type query` and its parameters then go to the query string).
+
+### Notes
+
+- Body merging applies only when the forwarded request carries a **JSON** content type; multipart and non-JSON bodies are forwarded verbatim.
+- Only the expanded per-field HTTP Custom Type parameters (DB-function shape) are forwarded; single-composite HTTP parameters (SQL-file shape) are not.
+
+## Tests
+
+`NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs` covers, via a WireMock proxy target that echoes the received URL / body: HTTP-type fields forwarded on the query (GET) and merged into the JSON body (POST, typed); placement following `RequestParamType` rather than the verb (a `param_type query` POST forwards to the query, not the body); and a resolved-parameter expression forwarded consistently. Existing user-claim / IP proxy tests continue to pass unchanged (GET → query string). Full suite green (2288).
diff --git a/npm/package.json b/npm/package.json
index 621ecdbe..6fd5bf82 100644
--- a/npm/package.json
+++ b/npm/package.json
@@ -1,6 +1,6 @@
 {
   "name": "npgsqlrest",
-  "version": "3.18.0",
+  "version": "3.18.1",
   "description": "Automatic REST API for PostgreSQL Databases Client Build",
   "scripts": {
     "postinstall": "node postinstall.js",
diff --git a/version.txt b/version.txt
index ae561550..10724e0b 100644
--- a/version.txt
+++ b/version.txt
@@ -1 +1 @@
-3.18.0
\ No newline at end of file
+3.18.1
\ No newline at end of file

From 62ef5cff2f52f86dd1cc5828837383b165631764 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Fri, 26 Jun 2026 13:37:23 +0200
Subject: [PATCH 07/25] fix(proxy): cap oversized forwarded query params; match
 @body_parameter_name by any param name

Two fixes for proxy endpoints that forward auto-filled parameters (v3.18.1),
surfaced by combining @proxy with an HTTP Custom Type parameter.

- ProxyOptions.MaxForwardedQueryParamLength (default 2048): a server-filled
  value longer than the limit is skipped with a warning instead of being
  percent-encoded into the upstream query string, which overflowed the request
  line (HTTP 414/431 / connection reset). Wired through Builder, ConfigDefaults,
  ConfigSchemaGenerator, ConfigTemplate, and appsettings.json.

- @body_parameter_name now matches case-insensitively and accepts any of a
  parameter's names. For an HTTP Custom Type field expanded from a composite,
  the converted name (responseBody), the expanded signature name
  (_response_body, via the new NpgsqlRestParameter.ExpandedName alias), and the
  shared base name (_response) all resolve. ActualName is unchanged so the
  fields still reassemble into the single composite SQL argument.

Tests: ProxyHttpTypeProbeTest adds converted-name redirect, expanded-name
redirect, and oversized-field-skipped cases. Full suite green (2291).

See changelog/v3.18.2.md. version.txt / npm not bumped yet.
---
 .../BodyParameterNameHandler.cs               |  15 +-
 NpgsqlRest/Defaults/DefaultCommentParser.cs   |   2 +-
 NpgsqlRest/NpgsqlRestEndpoint.cs              |   5 +-
 NpgsqlRest/NpgsqlRestParameter.cs             |  10 ++
 NpgsqlRest/Options/ProxyOptions.cs            |  11 ++
 NpgsqlRest/Proxy/ProxyRequestHandler.cs       |  21 ++-
 NpgsqlRest/RoutineSource.cs                   |   8 +
 NpgsqlRestClient/Builder.cs                   |   3 +-
 NpgsqlRestClient/ConfigDefaults.cs            |   3 +-
 NpgsqlRestClient/ConfigSchemaGenerator.cs     |   1 +
 NpgsqlRestClient/ConfigTemplate.cs            |   6 +-
 NpgsqlRestClient/appsettings.json             |   6 +-
 .../ProxyTests/ProxyHttpTypeProbeTest.cs      | 158 ++++++++++++++++++
 changelog/v3.18.2.md                          |  38 +++++
 14 files changed, 272 insertions(+), 15 deletions(-)
 create mode 100644 changelog/v3.18.2.md

diff --git a/NpgsqlRest/Defaults/CommentParsers/BodyParameterNameHandler.cs b/NpgsqlRest/Defaults/CommentParsers/BodyParameterNameHandler.cs
index d3590d1d..37eb163d 100644
--- a/NpgsqlRest/Defaults/CommentParsers/BodyParameterNameHandler.cs
+++ b/NpgsqlRest/Defaults/CommentParsers/BodyParameterNameHandler.cs
@@ -6,7 +6,9 @@ internal static partial class DefaultCommentParser
     /// Annotation: body_parameter_name | body_param_name
     /// Syntax: body_parameter_name [name]
     ///
-    /// Description: Set the name of the body parameter.
+    /// Description: Set the name of the body parameter. The name is matched case-insensitively
+    /// against either the parameter's actual (database) name or its converted (API) name, so an
+    /// HTTP Custom Type field can be targeted by its converted name (e.g. "responseBody").
     /// </summary>
     private static readonly string[] BodyParameterNameKey = [
         "body_parameter_name",
@@ -15,17 +17,20 @@ internal static partial class DefaultCommentParser
 
     private static void HandleBodyParameterName(
         RoutineEndpoint endpoint,
-        string[] wordsLower,
+        string[] words,
         int len,
         string description)
     {
         if (len == 2)
         {
-            if (!string.Equals(endpoint.BodyParameterName, wordsLower[1]))
+            // Preserve the original case the user wrote: the name is matched case-insensitively at
+            // request time, but matching against the camelCase converted name (e.g. "responseBody")
+            // only works when the stored value is not force-lowercased.
+            if (!string.Equals(endpoint.BodyParameterName, words[1]))
             {
-                CommentLogger?.CommentSetBodyParamName(description, wordsLower[1]);
+                CommentLogger?.CommentSetBodyParamName(description, words[1]);
             }
-            endpoint.BodyParameterName = wordsLower[1];
+            endpoint.BodyParameterName = words[1];
         }
     }
 }
diff --git a/NpgsqlRest/Defaults/DefaultCommentParser.cs b/NpgsqlRest/Defaults/DefaultCommentParser.cs
index fe83fffa..62b9cb52 100644
--- a/NpgsqlRest/Defaults/DefaultCommentParser.cs
+++ b/NpgsqlRest/Defaults/DefaultCommentParser.cs
@@ -194,7 +194,7 @@ internal static partial class DefaultCommentParser
                 // body_param_name name
                 else if (haveTag is true && StrEqualsToArray(wordsLower[0], BodyParameterNameKey))
                 {
-                    HandleBodyParameterName(routineEndpoint, wordsLower, len, description);
+                    HandleBodyParameterName(routineEndpoint, words, len, description);
                     TrackAnnotation(line);
                 }
 
diff --git a/NpgsqlRest/NpgsqlRestEndpoint.cs b/NpgsqlRest/NpgsqlRestEndpoint.cs
index 85ab7914..3a48e272 100644
--- a/NpgsqlRest/NpgsqlRestEndpoint.cs
+++ b/NpgsqlRest/NpgsqlRestEndpoint.cs
@@ -442,8 +442,9 @@ public async Task InvokeAsync(HttpContext context, IServiceProvider serviceProvi
                     // body parameter
                     if (parameter.Value is null && endpoint.HasBodyParameter &&
                         (
-                        string.Equals(endpoint.BodyParameterName, parameter.ConvertedName, StringComparison.Ordinal) ||
-                        string.Equals(endpoint.BodyParameterName, parameter.ActualName, StringComparison.Ordinal)
+                        string.Equals(endpoint.BodyParameterName, parameter.ConvertedName, StringComparison.OrdinalIgnoreCase) ||
+                        string.Equals(endpoint.BodyParameterName, parameter.ActualName, StringComparison.OrdinalIgnoreCase) ||
+                        (parameter.ExpandedName is not null && string.Equals(endpoint.BodyParameterName, parameter.ExpandedName, StringComparison.OrdinalIgnoreCase))
                         )
                     )
                     {
diff --git a/NpgsqlRest/NpgsqlRestParameter.cs b/NpgsqlRest/NpgsqlRestParameter.cs
index d0c61dcb..7095b9c3 100644
--- a/NpgsqlRest/NpgsqlRestParameter.cs
+++ b/NpgsqlRest/NpgsqlRestParameter.cs
@@ -28,6 +28,16 @@ public class NpgsqlRestParameter : NpgsqlParameter
     /// </summary>
     public string[]? CompositeFieldNames { get; set; }
 
+    /// <summary>
+    /// For an HTTP Custom Type field expanded out of a composite parameter, the per-field name as it
+    /// appears in the generated signature / .http file (base parameter name + separator + field name,
+    /// e.g. "_response_body"). Unlike <see cref="ActualName"/> — which stays the shared composite base
+    /// (e.g. "_response") so the fields reassemble into the single SQL argument — this is unique per
+    /// field. Used only as an additional alias when matching annotations such as @body_parameter_name,
+    /// so the name a user sees in the signature also resolves. Null for non-expanded parameters.
+    /// </summary>
+    public string? ExpandedName { get; set; }
+
     public ParamType ParamType { get; set; } = default!;
     public StringValues? QueryStringValues { get; set; } = null;
     public JsonNode? JsonBodyNode { get; set; } = null;
diff --git a/NpgsqlRest/Options/ProxyOptions.cs b/NpgsqlRest/Options/ProxyOptions.cs
index 257fa339..df6c6492 100644
--- a/NpgsqlRest/Options/ProxyOptions.cs
+++ b/NpgsqlRest/Options/ProxyOptions.cs
@@ -108,4 +108,15 @@ public class ProxyOptions
     /// Example: "http://localhost:5000"
     /// </summary>
     public string? SelfBaseUrl { get; set; }
+
+    /// <summary>
+    /// Maximum length (in characters) of a single automatic parameter value that may be appended
+    /// to the proxy upstream query string. Server-filled parameters (user claims, IP address, HTTP
+    /// Custom Type fields, resolved-parameter expressions) whose value exceeds this length are
+    /// skipped (and a warning is logged) instead of being percent-encoded into the URL, which would
+    /// produce an unusable request line (HTTP 414/431, or a connection reset). A value of 0 or less
+    /// disables the guard (no limit). To forward a large value to the upstream, use a body-carrying
+    /// proxy method (POST/PUT/PATCH) so it goes into the request body instead of the query string.
+    /// </summary>
+    public int MaxForwardedQueryParamLength { get; set; } = 2048;
 }
diff --git a/NpgsqlRest/Proxy/ProxyRequestHandler.cs b/NpgsqlRest/Proxy/ProxyRequestHandler.cs
index eedd8d81..4d5f66b5 100644
--- a/NpgsqlRest/Proxy/ProxyRequestHandler.cs
+++ b/NpgsqlRest/Proxy/ProxyRequestHandler.cs
@@ -273,8 +273,9 @@ private static bool IsAutomaticParam(RoutineEndpoint endpoint, NpgsqlRestParamet
         }
         foreach (var p in parameters)
         {
-            if (string.Equals(endpoint.BodyParameterName, p.ConvertedName, StringComparison.Ordinal)
-                || string.Equals(endpoint.BodyParameterName, p.ActualName, StringComparison.Ordinal))
+            if (string.Equals(endpoint.BodyParameterName, p.ConvertedName, StringComparison.OrdinalIgnoreCase)
+                || string.Equals(endpoint.BodyParameterName, p.ActualName, StringComparison.OrdinalIgnoreCase)
+                || (p.ExpandedName is not null && string.Equals(endpoint.BodyParameterName, p.ExpandedName, StringComparison.OrdinalIgnoreCase)))
             {
                 return p;
             }
@@ -304,6 +305,7 @@ private static bool IsAutomaticParam(RoutineEndpoint endpoint, NpgsqlRestParamet
 
     private static string AppendParamsToQuery(string url, List<NpgsqlRestParameter> parameters)
     {
+        var maxLen = Options.ProxyOptions.MaxForwardedQueryParamLength;
         var sb = new StringBuilder();
         foreach (var p in parameters)
         {
@@ -311,13 +313,26 @@ private static string AppendParamsToQuery(string url, List<NpgsqlRestParameter>
             {
                 continue;
             }
+            var value = p.Value.ToString() ?? "";
+            // Guard: a large value (typically an HTTP Custom Type body/text field) cannot be carried
+            // in a query string — percent-encoding it produces an unusable request line that the
+            // upstream rejects (HTTP 414/431) or resets. Skip it and warn rather than build a doomed URL.
+            // To forward such a value, use a body-carrying proxy method (POST/PUT/PATCH).
+            if (maxLen > 0 && value.Length > maxLen)
+            {
+                Logger?.LogWarning(
+                    "Proxy: skipping forwarded query parameter '{Name}' — value length {Length} exceeds ProxyOptions.MaxForwardedQueryParamLength ({Max}). " +
+                    "Large values cannot be carried in a query string; use a body-carrying proxy method (POST/PUT/PATCH) to forward them in the request body.",
+                    p.ConvertedName, value.Length, maxLen);
+                continue;
+            }
             if (sb.Length > 0)
             {
                 sb.Append('&');
             }
             sb.Append(Uri.EscapeDataString(p.ConvertedName));
             sb.Append('=');
-            sb.Append(Uri.EscapeDataString(p.Value.ToString() ?? ""));
+            sb.Append(Uri.EscapeDataString(value));
         }
         if (sb.Length == 0)
         {
diff --git a/NpgsqlRest/RoutineSource.cs b/NpgsqlRest/RoutineSource.cs
index ecf51d90..09d8b1e8 100644
--- a/NpgsqlRest/RoutineSource.cs
+++ b/NpgsqlRest/RoutineSource.cs
@@ -433,6 +433,14 @@ public class RoutineSource(
                             convertedName: convertedName,
                             actualName: originalParameterName,
                             typeDescriptor: descriptor);
+                        // For an expanded composite field, ActualName stays the shared base
+                        // (originalParameterName, e.g. "_response"); record the unique per-field name
+                        // (paramName, e.g. "_response_body") as an alias so annotations that reference
+                        // the name shown in the signature (e.g. @body_parameter_name) still resolve.
+                        if (customTypeName != null)
+                        {
+                            parameters[i].ExpandedName = paramName;
+                        }
                     }
                     simpleDefinition.AppendLine(")");
                 }
diff --git a/NpgsqlRestClient/Builder.cs b/NpgsqlRestClient/Builder.cs
index d38119aa..4610183a 100644
--- a/NpgsqlRestClient/Builder.cs
+++ b/NpgsqlRestClient/Builder.cs
@@ -2842,7 +2842,8 @@ public ProxyOptions BuildProxyOptions()
             ResponseContentTypeParameter = _config.GetConfigStr("ResponseContentTypeParameter", cfg) ?? "_proxy_content_type",
             ResponseSuccessParameter = _config.GetConfigStr("ResponseSuccessParameter", cfg) ?? "_proxy_success",
             ResponseErrorMessageParameter = _config.GetConfigStr("ResponseErrorMessageParameter", cfg) ?? "_proxy_error_message",
-            ForwardUploadContent = _config.GetConfigBool("ForwardUploadContent", cfg)
+            ForwardUploadContent = _config.GetConfigBool("ForwardUploadContent", cfg),
+            MaxForwardedQueryParamLength = _config.GetConfigInt("MaxForwardedQueryParamLength", cfg) ?? 2048
         };
 
         // Parse ExcludeHeaders from array config
diff --git a/NpgsqlRestClient/ConfigDefaults.cs b/NpgsqlRestClient/ConfigDefaults.cs
index cbdeff67..11579ac7 100644
--- a/NpgsqlRestClient/ConfigDefaults.cs
+++ b/NpgsqlRestClient/ConfigDefaults.cs
@@ -1068,7 +1068,8 @@ private static JsonObject GetProxyOptionsDefaults()
             ["ResponseContentTypeParameter"] = "_proxy_content_type",
             ["ResponseSuccessParameter"] = "_proxy_success",
             ["ResponseErrorMessageParameter"] = "_proxy_error_message",
-            ["ForwardUploadContent"] = false
+            ["ForwardUploadContent"] = false,
+            ["MaxForwardedQueryParamLength"] = 2048
         };
     }
 
diff --git a/NpgsqlRestClient/ConfigSchemaGenerator.cs b/NpgsqlRestClient/ConfigSchemaGenerator.cs
index 114082cb..9aa37e79 100644
--- a/NpgsqlRestClient/ConfigSchemaGenerator.cs
+++ b/NpgsqlRestClient/ConfigSchemaGenerator.cs
@@ -511,6 +511,7 @@ public static partial class ConfigSchemaGenerator
         ["NpgsqlRest:ProxyOptions:ResponseSuccessParameter"] = "Default name for the proxy response success parameter.",
         ["NpgsqlRest:ProxyOptions:ResponseErrorMessageParameter"] = "Default name for the proxy response error message parameter.",
         ["NpgsqlRest:ProxyOptions:ForwardUploadContent"] = "When true, for upload endpoints marked as proxy, the raw multipart/form-data content is forwarded directly to the upstream proxy instead of being processed locally. This allows the upstream service to handle file uploads. When false (default), upload endpoints with proxy annotation will process uploads locally and upload metadata will not be available to the proxy.",
+        ["NpgsqlRest:ProxyOptions:MaxForwardedQueryParamLength"] = "Maximum length (characters) of a single automatic parameter value appended to the proxy upstream query string. Server-filled values (claims, IP, HTTP Custom Type fields, resolved-parameter expressions) longer than this are skipped with a warning instead of producing an unusable request line (HTTP 414/431). 0 or less disables the guard. To forward a large value, use a body-carrying proxy method (POST/PUT/PATCH). Default is 2048.",
         ["NpgsqlRest:SqlFileSource"] = "SQL file source for generating REST API endpoints from .sql files.",
         ["NpgsqlRest:SqlFileSource:Enabled"] = "Enable or disable SQL file source endpoints. Default is false.",
         ["NpgsqlRest:SqlFileSource:FilePattern"] = "Glob pattern for SQL files, e.g. \"sql/**/*.sql\", \"queries/*.sql\".\nSupports * (any chars), ** (recursive, any including /), ? (single char).\nEmpty string disables the feature.",
diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index df4b51c6..fe416ab1 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -2882,7 +2882,11 @@ public static partial class ConfigSchemaGenerator
           //
           // When true, for upload endpoints marked as proxy, the raw multipart/form-data content is forwarded directly to the upstream proxy instead of being processed locally. This allows the upstream service to handle file uploads. When false (default), upload endpoints with proxy annotation will process uploads locally and upload metadata will not be available to the proxy.
           //
-          "ForwardUploadContent": false
+          "ForwardUploadContent": false,
+          //
+          // Maximum length (characters) of a single automatic parameter value appended to the proxy upstream query string. Server-filled values (claims, IP, HTTP Custom Type fields, resolved-parameter expressions) longer than this are skipped with a warning instead of producing an unusable request line (HTTP 414/431). 0 or less disables the guard. To forward a large value, use a body-carrying proxy method (POST/PUT/PATCH). Default is 2048.
+          //
+          "MaxForwardedQueryParamLength": 2048
         },
     
         //
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index 9b19fb5d..f36adda4 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -2873,7 +2873,11 @@
       //
       // When true, for upload endpoints marked as proxy, the raw multipart/form-data content is forwarded directly to the upstream proxy instead of being processed locally. This allows the upstream service to handle file uploads. When false (default), upload endpoints with proxy annotation will process uploads locally and upload metadata will not be available to the proxy.
       //
-      "ForwardUploadContent": false
+      "ForwardUploadContent": false,
+      //
+      // Maximum length (characters) of a single automatic parameter value appended to the proxy upstream query string. Server-filled values (claims, IP, HTTP Custom Type fields, resolved-parameter expressions) longer than this are skipped with a warning instead of producing an unusable request line (HTTP 414/431). 0 or less disables the guard. To forward a large value, use a body-carrying proxy method (POST/PUT/PATCH). Default is 2048.
+      //
+      "MaxForwardedQueryParamLength": 2048
     },
 
     //
diff --git a/NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs b/NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs
index d29fac17..20e5cd20 100644
--- a/NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs
+++ b/NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs
@@ -40,6 +40,45 @@ comment on function proxy_with_httptype(proxy_httptype_probe) is 'HTTP GET
 allow_anonymous
 proxy';
 
+        -- GET endpoint, but @proxy POST + @body_parameter_name redirects ONE expanded HTTP-type field
+        -- (targeted by its converted/API name 'responseBody') into the upstream POST BODY, while the
+        -- remaining small fields still go to the proxy QUERY STRING. Proves case-insensitive matching
+        -- of the body-param name against the converted name of a custom-type-expanded field.
+        create function proxy_bodyparam_with_httptype(
+            _response proxy_httptype_probe default null
+        )
+        returns void
+        language plpgsql
+        as
+        $$
+        begin
+            raise exception 'passthrough proxy must NOT execute the function';
+        end;
+        $$;
+        comment on function proxy_bodyparam_with_httptype(proxy_httptype_probe) is 'HTTP GET
+allow_anonymous
+proxy POST
+body_parameter_name responseBody';
+
+        -- Same as above, but the body param is targeted by the per-field name shown in the generated
+        -- signature / .http file ('_response_body'). That name is the composite base + field, and is
+        -- matched via the ExpandedName alias (ActualName stays the shared base '_response').
+        create function proxy_bodyparam_expanded_with_httptype(
+            _response proxy_httptype_probe default null
+        )
+        returns void
+        language plpgsql
+        as
+        $$
+        begin
+            raise exception 'passthrough proxy must NOT execute the function';
+        end;
+        $$;
+        comment on function proxy_bodyparam_expanded_with_httptype(proxy_httptype_probe) is 'HTTP GET
+allow_anonymous
+proxy POST
+body_parameter_name _response_body';
+
         -- POST endpoint: server-filled HTTP-type fields are merged into the proxy JSON BODY,
         -- alongside the client's original body fields.
         create function proxy_post_with_httptype(
@@ -269,4 +308,123 @@ public async Task Resolved_param_is_forwarded_to_proxy_consistently()
         content.Should().Contain("name=alice");             // client query forwarded verbatim
         content.Should().Contain("token=TOKEN-ALICE-123");  // resolved (automatic) param forwarded
     }
+
+    // @body_parameter_name targets an expanded HTTP-type field by its converted (API) name. The match
+    // is case-insensitive, so "responseBody" resolves to the body field even though its database
+    // (actual) name is the shared composite base "_response". The field becomes the upstream POST body
+    // (not the query), while the remaining small fields are still forwarded on the query string.
+    [Fact]
+    public async Task BodyParam_redirects_httptype_field_to_proxy_body_by_converted_name()
+    {
+        int httpTypeCalls = 0;
+        _httpTypeServer
+            .Given(Request.Create().WithPath("/httptype-source").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                Interlocked.Increment(ref httpTypeCalls);
+                return new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = "FETCHED-FROM-HTTPTYPE", DetectedBodyType = BodyType.String }
+                };
+            }));
+
+        // @proxy POST: the upstream call is POST even though the client called GET. Echo URL + body.
+        _proxyServer
+            .Given(Request.Create().WithPath("/api/proxy-bodyparam-with-httptype/").UsingPost())
+            .RespondWith(Response.Create().WithCallback(req =>
+                new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = $"URL:[{req.Url}] BODY:[{req.Body}]", DetectedBodyType = BodyType.String }
+                }));
+
+        using var response = await _test.Client.GetAsync("/api/proxy-bodyparam-with-httptype/");
+        var content = await response.Content.ReadAsStringAsync();
+
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+        httpTypeCalls.Should().Be(1);
+
+        // The body field is the raw POST body …
+        content.Should().Contain("BODY:[FETCHED-FROM-HTTPTYPE]");
+        // … and is NOT in the query string (it was redirected to the body).
+        content.Should().NotContain("responseBody=");
+        // The remaining small fields still go to the query.
+        content.Should().Contain("responseStatusCode=200");
+    }
+
+    // Same redirect, but the body param targets the per-field name from the generated signature
+    // ('_response_body'). ActualName is the shared composite base '_response'; this resolves via the
+    // ExpandedName alias, and is unique per field (so it targets the body field unambiguously).
+    [Fact]
+    public async Task BodyParam_redirects_httptype_field_to_proxy_body_by_expanded_name()
+    {
+        int httpTypeCalls = 0;
+        _httpTypeServer
+            .Given(Request.Create().WithPath("/httptype-source").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+            {
+                Interlocked.Increment(ref httpTypeCalls);
+                return new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = "FETCHED-FROM-HTTPTYPE", DetectedBodyType = BodyType.String }
+                };
+            }));
+
+        _proxyServer
+            .Given(Request.Create().WithPath("/api/proxy-bodyparam-expanded-with-httptype/").UsingPost())
+            .RespondWith(Response.Create().WithCallback(req =>
+                new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = $"URL:[{req.Url}] BODY:[{req.Body}]", DetectedBodyType = BodyType.String }
+                }));
+
+        using var response = await _test.Client.GetAsync("/api/proxy-bodyparam-expanded-with-httptype/");
+        var content = await response.Content.ReadAsStringAsync();
+
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+        httpTypeCalls.Should().Be(1);
+
+        // The body field (targeted by its expanded signature name) is the raw POST body, not the query.
+        content.Should().Contain("BODY:[FETCHED-FROM-HTTPTYPE]");
+        content.Should().NotContain("responseBody=");
+        content.Should().Contain("responseStatusCode=200");
+    }
+
+    // Guard: an oversized automatic value (here the HTTP-type body field) cannot be carried in a query
+    // string. It is skipped (with a warning) instead of producing an unusable request line, while the
+    // small fields are still forwarded. Default ProxyOptions.MaxForwardedQueryParamLength is 2048.
+    [Fact]
+    public async Task Oversized_httptype_field_is_skipped_from_proxy_query()
+    {
+        var largeBody = new string('X', 3000); // exceeds the default MaxForwardedQueryParamLength (2048)
+        _httpTypeServer
+            .Given(Request.Create().WithPath("/httptype-source").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+                new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = largeBody, DetectedBodyType = BodyType.String }
+                }));
+
+        _proxyServer
+            .Given(Request.Create().WithPath("/api/proxy-with-httptype/").UsingGet())
+            .RespondWith(Response.Create().WithCallback(req =>
+                new ResponseMessage
+                {
+                    StatusCode = 200,
+                    BodyData = new BodyData { BodyAsString = $"PROXY-URL:[{req.Url}]", DetectedBodyType = BodyType.String }
+                }));
+
+        using var response = await _test.Client.GetAsync("/api/proxy-with-httptype/");
+        var content = await response.Content.ReadAsStringAsync();
+
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+        // The oversized body field is skipped from the query (guard) …
+        content.Should().NotContain("responseBody=");
+        // … while the small fields are still forwarded.
+        content.Should().Contain("responseStatusCode=200");
+    }
 }
diff --git a/changelog/v3.18.2.md b/changelog/v3.18.2.md
new file mode 100644
index 00000000..9402cc14
--- /dev/null
+++ b/changelog/v3.18.2.md
@@ -0,0 +1,38 @@
+# Changelog v3.18.2
+
+## Version [3.18.2](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.18.2) (2026-06-26)
+
+[Full Changelog](https://github.com/NpgsqlRest/NpgsqlRest/compare/3.18.1...3.18.2)
+
+Patch release with two fixes for **proxy endpoints that forward auto-filled parameters** (v3.18.1), surfaced by combining a `@proxy` with an HTTP Custom Type parameter.
+
+## What changed
+
+### 1. Large auto-filled values no longer break the proxy query string
+
+New option **`ProxyOptions.MaxForwardedQueryParamLength`** (default `2048`). When a server-filled parameter is appended to the proxy upstream **query string**, a value longer than this limit is now **skipped with a warning** instead of being percent-encoded into the URL.
+
+Previously, an HTTP Custom Type whose `body` field held a large payload (e.g. a scraped HTML page) was percent-encoded into the upstream query string, producing an oversized request line that the upstream rejected (HTTP 414 / 431) or that reset the connection. To forward such a value, use a body-carrying proxy method (POST/PUT/PATCH) so it travels in the request body instead. Set the option to `0` to disable the guard.
+
+### 2. `@body_parameter_name` reliably matches HTTP Custom Type fields
+
+`@body_parameter_name` now matches **case-insensitively** and accepts any of the parameter's names. For an HTTP Custom Type field expanded out of a composite parameter, all of these now resolve to the same field:
+
+- the **converted (API) name** — e.g. `responseBody`
+- the **expanded signature name** — e.g. `_response_body` (the name shown in the generated signature / `.http` file)
+- the **base composite name** — e.g. `_response` (shared by all expanded fields; resolves to the first one)
+
+Previously the annotation value was force-lowercased and compared case-sensitively, so the camelCase converted name never matched, and the expanded signature name (`_response_body`) matched nothing at all — it is stored as neither the actual nor the converted name. This made it impossible to redirect a single expanded HTTP-type field (such as the response body) into the proxy request body.
+
+### Why these go together
+
+The pattern "fetch with an HTTP Custom Type, then `@proxy` to an upstream" now works cleanly: redirect the (large) body field into the upstream request body with `@body_parameter_name`, while the remaining small fields travel on the query string under the new length guard.
+
+## Notes
+
+- `ProxyOptions.MaxForwardedQueryParamLength` is wired through the client config (`appsettings.json`, JSON schema, and the `--config` template).
+- No parameter `ActualName` semantics changed: expanded HTTP-type fields still share the composite base name so they reassemble into the single SQL argument; the per-field name is matched via an internal alias only.
+
+## Tests
+
+`NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs` adds three cases (WireMock proxy target echoing the received URL / body): body redirect by converted name (`responseBody`), body redirect by expanded signature name (`_response_body`), and an oversized HTTP-type body field skipped from the proxy query string. Full suite green (2291).

From 673624cfaf67bb6a6d2bb0e76bfbc0da7691ee9a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Fri, 26 Jun 2026 13:57:59 +0200
Subject: [PATCH 08/25] fix(tsclient): correct generated client for
 @body_parameter_name endpoints
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The TypeScript client generator was broken for any endpoint using
@body_parameter_name:

- It emitted "body: request.<name>?" — the TS optional "?" suffix (added for
  parameters with a default or a custom type) leaked into the runtime property
  name, a syntax error. The query-exclusion key was likewise ["<name>?"], so the
  body parameter was not stripped from the query string. Now the bare converted
  name is used for both the body expression and the exclusion key.

- It emitted a fetch body even for GET, which fetch forbids. A body is now only
  emitted for methods that can carry one (not GET); a GET body parameter (e.g. a
  server-filled HTTP Custom Type field forwarded by a proxy POST) is simply
  excluded from the query and not sent.

- It matched @body_parameter_name only against the converted and actual names,
  so the expanded HTTP-type field name (e.g. _response_body) was ignored — the
  parameter leaked into the query and no body was emitted, even though the server
  resolved it. The generator now also matches the ExpandedName alias, consistent
  with the server-side body-parameter resolution.

Tests: NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs covers a GET endpoint
(converted name) and a POST HTTP-Custom-Type endpoint targeted by the expanded
name _response_body. Full suite green (2293).

See changelog/v3.18.2.md. version.txt / npm not bumped yet.
---
 .../TsClientTests/BodyParamGetTests.cs        | 202 ++++++++++++++++++
 changelog/v3.18.2.md                          |  14 +-
 plugins/NpgsqlRest.TsClient/TsClient.cs       |  18 +-
 3 files changed, 229 insertions(+), 5 deletions(-)
 create mode 100644 NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs

diff --git a/NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs b/NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs
new file mode 100644
index 00000000..f5f2d528
--- /dev/null
+++ b/NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs
@@ -0,0 +1,202 @@
+namespace NpgsqlRestTests
+{
+    public static partial class Database
+    {
+        public static void TsClientBodyParamGetTests()
+        {
+            // GET endpoint with @body_parameter_name targeting a defaulted parameter (so it carries the
+            // TS optional "?" suffix in the interface). Regression for three TsClient bugs:
+            //  1) the body expression emitted "request.payload?" (trailing "?" — a syntax error),
+            //  2) the query-exclusion key was ["payload?"] (with "?") so the param was NOT stripped,
+            //  3) a fetch body was emitted for a GET (fetch forbids a body on GET).
+            script.Append("""
+create schema if not exists tsclient_test;
+create function tsclient_test.bodyparam_get(_keyword text, _payload text default null)
+returns text
+language sql
+as $$
+select coalesce(_keyword, '') || coalesce(_payload, '');
+$$;
+comment on function tsclient_test.bodyparam_get(text, text) is '
+HTTP GET
+tsclient_module=bodyparam_get
+body_parameter_name payload';
+
+-- POST endpoint with an HTTP Custom Type whose body field is targeted by @body_parameter_name using
+-- its EXPANDED signature name (_response_body). The generator must match that name (via ExpandedName)
+-- the same way the server does, emit the body with the bare converted name (request.responseBody),
+-- and exclude it from the query string. Regression for the generator only matching converted/actual
+-- names. The HTTP type points at an unused port; it never fires during code generation.
+create type tsclient_test.tsc_http_probe as (
+    body text,
+    status_code int,
+    success boolean,
+    error_message text
+);
+comment on type tsclient_test.tsc_http_probe is 'GET http://localhost:1/tsc-dummy';
+
+create function tsclient_test.bodyparam_expanded(_response tsclient_test.tsc_http_probe default null)
+returns text
+language plpgsql
+as $$ begin return ''; end; $$;
+comment on function tsclient_test.bodyparam_expanded(tsclient_test.tsc_http_probe) is '
+HTTP POST
+tsclient_module=bodyparam_expanded
+body_parameter_name _response_body';
+""");
+        }
+    }
+}
+
+namespace NpgsqlRestTests.TsClientTests
+{
+    [Collection("TestFixture")]
+    public class BodyParamGetTests
+    {
+        private const string Expected = """
+const baseUrl = "";
+const parseQuery = (query: Record<any, any>) => "?" + Object.keys(query ? query : {})
+    .map(key => {
+        const value = (query[key] != null ? query[key] : "") as string;
+        if (Array.isArray(value)) {
+            return value.map((s: string) => s ? `${key}=${encodeURIComponent(s)}` : `${key}=`).join("&");
+        }
+        return `${key}=${encodeURIComponent(value)}`;
+    })
+    .join("&");
+
+interface ITsclientTestBodyparamGetRequest {
+    keyword: string | null;
+    payload?: string | null;
+}
+
+
+/**
+* function tsclient_test.bodyparam_get(
+*     _keyword text,
+*     _payload text DEFAULT NULL::text
+* )
+* returns text
+*
+* @remarks
+* comment on function tsclient_test.bodyparam_get is 'HTTP GET
+* tsclient_module=bodyparam_get
+* body_parameter_name payload';
+*
+* @param request - Object containing request parameters.
+* @returns {string}
+*
+* @see FUNCTION tsclient_test.bodyparam_get
+*/
+export async function tsclientTestBodyparamGet(
+    request: ITsclientTestBodyparamGetRequest
+) : Promise<string> {
+    const response = await fetch(baseUrl + "/api/tsclient-test/bodyparam-get" + parseQuery((({ ["payload"]: _1, ...rest }) => rest)(request)), {
+        method: "GET",
+    });
+    return await response.text();
+}
+
+
+""";
+
+        private const string ExpectedExpanded = """
+const baseUrl = "";
+const parseQuery = (query: Record<any, any>) => "?" + Object.keys(query ? query : {})
+    .map(key => {
+        const value = (query[key] != null ? query[key] : "") as string;
+        if (Array.isArray(value)) {
+            return value.map((s: string) => s ? `${key}=${encodeURIComponent(s)}` : `${key}=`).join("&");
+        }
+        return `${key}=${encodeURIComponent(value)}`;
+    })
+    .join("&");
+
+interface ITsclientTestBodyparamExpandedRequest {
+    responseBody?: string | null;
+    responseStatusCode?: number | null;
+    responseSuccess?: boolean | null;
+    responseErrorMessage?: string | null;
+}
+
+
+/**
+* function tsclient_test.bodyparam_expanded(
+*     _response_body text DEFAULT NULL::tsclient_test.tsc_http_probe,
+*     _response_status_code integer,
+*     _response_success boolean,
+*     _response_error_message text
+* )
+* returns text
+*
+* @remarks
+* comment on function tsclient_test.bodyparam_expanded is 'HTTP POST
+* tsclient_module=bodyparam_expanded
+* body_parameter_name _response_body';
+*
+* @param request - Object containing request parameters.
+* @returns {string}
+*
+* @see FUNCTION tsclient_test.bodyparam_expanded
+*/
+export async function tsclientTestBodyparamExpanded(
+    request: ITsclientTestBodyparamExpandedRequest
+) : Promise<string> {
+    const response = await fetch(baseUrl + "/api/tsclient-test/bodyparam-expanded" + parseQuery((({ ["responseBody"]: _1, ...rest }) => rest)(request)), {
+        method: "POST",
+        body: request.responseBody
+    });
+    return await response.text();
+}
+
+
+""";
+
+        [Fact]
+        public void Test_BodyParamGet_GeneratedFile()
+        {
+            var filePath = Path.Combine(Setup.Program.TsClientOutputPath, "bodyparam_get.ts");
+            File.Exists(filePath).Should().BeTrue($"Expected file at {filePath}");
+
+            var content = File.ReadAllText(filePath);
+
+            // The fixed generator must NOT emit the optional "?" suffix in the runtime name, and must
+            // not attach a body to a GET request.
+            content.Should().NotContain("request.payload?", "the body expression must not carry the TS optional suffix");
+            content.Should().NotContain("[\"payload?\"]", "the query-exclusion key must be the bare property name");
+            content.Should().NotContain("body:", "a GET request must not emit a fetch body");
+
+            // Full-content match. Normalize per-line trailing whitespace and line endings: the generator
+            // emits trailing spaces on blank comment lines, which are easily mangled when transcribed.
+            Normalize(content).Should().Be(Normalize(Expected));
+        }
+
+        [Fact]
+        public void Test_BodyParamExpanded_GeneratedFile()
+        {
+            var filePath = Path.Combine(Setup.Program.TsClientOutputPath, "bodyparam_expanded.ts");
+            File.Exists(filePath).Should().BeTrue($"Expected file at {filePath}");
+
+            var content = File.ReadAllText(filePath);
+
+            // @body_parameter_name targeted the expanded signature name (_response_body); the generator
+            // must resolve it to the body field and emit the body with the bare converted name.
+            content.Should().Contain("body: request.responseBody", "the expanded name must resolve to the body field, emitted by its converted name");
+            content.Should().Contain("[\"responseBody\"]", "the body parameter must be excluded from the query string");
+            content.Should().NotContain("parseQuery(request)", "the body parameter must not be left in the unfiltered query");
+            content.Should().NotContain("request.responseBody?", "no trailing optional suffix in the runtime name");
+
+            Normalize(content).Should().Be(Normalize(ExpectedExpanded));
+        }
+
+        private static string Normalize(string s)
+        {
+            var lines = s.Replace("\r\n", "\n").Split('\n');
+            for (var i = 0; i < lines.Length; i++)
+            {
+                lines[i] = lines[i].TrimEnd();
+            }
+            return string.Join("\n", lines);
+        }
+    }
+}
diff --git a/changelog/v3.18.2.md b/changelog/v3.18.2.md
index 9402cc14..043ce45f 100644
--- a/changelog/v3.18.2.md
+++ b/changelog/v3.18.2.md
@@ -24,9 +24,19 @@ Previously, an HTTP Custom Type whose `body` field held a large payload (e.g. a
 
 Previously the annotation value was force-lowercased and compared case-sensitively, so the camelCase converted name never matched, and the expanded signature name (`_response_body`) matched nothing at all — it is stored as neither the actual nor the converted name. This made it impossible to redirect a single expanded HTTP-type field (such as the response body) into the proxy request body.
 
+### 3. TypeScript client generation for `@body_parameter_name`
+
+The generated TypeScript client was broken for an endpoint with `@body_parameter_name`:
+
+- the body expression was emitted as `request.responseBody?` — a syntax error (the TS optional `?` suffix leaked into the runtime property name);
+- the query-string exclusion key was `["responseBody?"]`, so the body parameter was **not** stripped from the query string;
+- a `body` was emitted even for a `GET` request, which `fetch` forbids.
+
+The generator now uses the parameter's bare name for the body expression and the exclusion key, only emits a `fetch` body for methods that can carry one (not `GET`), and — like the server — matches `@body_parameter_name` against the converted, actual, or expanded signature name of an HTTP Custom Type field (e.g. `responseBody`, `_response`, or `_response_body`).
+
 ### Why these go together
 
-The pattern "fetch with an HTTP Custom Type, then `@proxy` to an upstream" now works cleanly: redirect the (large) body field into the upstream request body with `@body_parameter_name`, while the remaining small fields travel on the query string under the new length guard.
+The pattern "fetch with an HTTP Custom Type, then `@proxy` to an upstream" now works cleanly end to end — server **and** generated client: redirect the (large) body field into the upstream request body with `@body_parameter_name`, while the remaining small fields travel on the query string under the new length guard.
 
 ## Notes
 
@@ -35,4 +45,4 @@ The pattern "fetch with an HTTP Custom Type, then `@proxy` to an upstream" now w
 
 ## Tests
 
-`NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs` adds three cases (WireMock proxy target echoing the received URL / body): body redirect by converted name (`responseBody`), body redirect by expanded signature name (`_response_body`), and an oversized HTTP-type body field skipped from the proxy query string. Full suite green (2291).
+`NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs` adds three cases (WireMock proxy target echoing the received URL / body): body redirect by converted name (`responseBody`), body redirect by expanded signature name (`_response_body`), and an oversized HTTP-type body field skipped from the proxy query string. `NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs` covers the generated client for `@body_parameter_name` endpoints: a `GET` case (no `?`-suffixed name, parameter excluded from the query, no `fetch` body on `GET`) and a `POST` HTTP-Custom-Type case targeted by the expanded name `_response_body` (body emitted as `request.responseBody`, excluded from the query). Full suite green (2293).
diff --git a/plugins/NpgsqlRest.TsClient/TsClient.cs b/plugins/NpgsqlRest.TsClient/TsClient.cs
index b3e02d71..4a32b33a 100644
--- a/plugins/NpgsqlRest.TsClient/TsClient.cs
+++ b/plugins/NpgsqlRest.TsClient/TsClient.cs
@@ -473,9 +473,17 @@ bool Handle(RoutineEndpoint endpoint)
                 var nameSuffix = (descriptor.HasDefault || descriptor.CustomType is not null) ? "?" : "";
                 paramNames[i] = QuoteJavaScriptVariableName($"{parameter.ConvertedName}{nameSuffix}");
                 if (string.Equals(endpoint.BodyParameterName, parameter.ConvertedName, StringComparison.OrdinalIgnoreCase) ||
-                    string.Equals(endpoint.BodyParameterName, parameter.ActualName, StringComparison.OrdinalIgnoreCase))
+                    string.Equals(endpoint.BodyParameterName, parameter.ActualName, StringComparison.OrdinalIgnoreCase) ||
+                    (parameter.ExpandedName is not null && string.Equals(endpoint.BodyParameterName, parameter.ExpandedName, StringComparison.OrdinalIgnoreCase)))
                 {
-                    bodyParameterName = paramNames[i];
+                    // Match the same three names the server-side body-parameter resolution accepts:
+                    // converted (responseBody), actual (the shared composite base, _response), and the
+                    // expanded per-field signature name (_response_body, via ExpandedName).
+                    // Use the bare converted name for emission — NOT paramNames[i], which carries the TS
+                    // optional "?" suffix (e.g. "responseBody?"). That suffix is only for the interface
+                    // property declaration; it must not leak into the runtime property name used for the
+                    // body expression (request.responseBody) or the query-exclusion key (["responseBody"]).
+                    bodyParameterName = parameter.ConvertedName;
                 }
             }
             string requestDesc = "";
@@ -1137,7 +1145,11 @@ string NewLine(string? input, int ident) =>
                 lastContentHeaderWasUrl = false;
             }
 
-            if (body is null && bodyParameterName is not null)
+            // Emit the request body for a designated body parameter only when the method can carry one.
+            // fetch() forbids a body on GET, so a GET endpoint with @body_parameter_name still excludes
+            // that parameter from the query string (above) but does not send it as a body — e.g. when it
+            // is server-filled (an HTTP Custom Type field) and forwarded by a proxy POST upstream.
+            if (body is null && bodyParameterName is not null && endpoint.Method != Method.GET)
             {
                 body = $"body: request.{bodyParameterName}";
             }

From 2482edeb2213d833cce4576943925a3ea91c28e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Fri, 26 Jun 2026 14:35:58 +0200
Subject: [PATCH 09/25] feat(codegen): OmitAutomaticParameters option to drop
 server-filled params from generated requests

New opt-in option (default false) on TsClientOptions, HttpFileOptions, and
OpenApiOptions. When enabled, parameters that are filled by the server and
cannot be set by the client are omitted from the generated request shape:
the TypeScript request interface, the .http query string / JSON body, and the
OpenAPI query parameters / request body.

A parameter is omitted when it is automatic AND optional. The shared rule lives
on the core endpoint as RoutineEndpoint.OmitParameterFromGeneratedRequest, built
on RoutineEndpoint.IsAutomaticParameter, so all three generators stay consistent:

- always automatic: HTTP Custom Type fields, resolved-parameter expressions,
  upload-metadata parameters;
- automatic only when the endpoint uses user parameters: IP-address and
  user-claim parameters;
- optional guard: HasDefault or a composite/HTTP-type field, so omission can
  never make a required argument un-sendable.

When every parameter is omitted the request collapses cleanly: a no-argument
TypeScript function, a bare .http URL, and no OpenAPI parameters/requestBody.

Default is false to keep generated output byte-stable on upgrade; each generator
opts in independently. The option is wired through the client config for all
three plugins (binding, ConfigDefaults, schema, template, appsettings.json).

Tests: omission coverage for each generator (TsClientTests/HttpFilesTests/
OpenApiTests OmitAutomaticParamsTests), reusing the tsclient_test.bodyparam_*
HTTP-type fixtures with separate omit-enabled generator configs. Full suite
green (2299).

See changelog/v3.18.2.md. version.txt / npm not bumped yet.
---
 NpgsqlRest/RoutineEndpoint.cs                 |  47 ++++++
 NpgsqlRestClient/App.cs                       |   5 +-
 NpgsqlRestClient/ConfigDefaults.cs            |   9 +-
 NpgsqlRestClient/ConfigSchemaGenerator.cs     |   3 +
 NpgsqlRestClient/ConfigTemplate.cs            |  18 ++-
 NpgsqlRestClient/appsettings.json             |  18 ++-
 .../OmitAutomaticParamsTests.cs               |  80 ++++++++++
 .../OpenApiTests/OmitAutomaticParamsTests.cs  |  50 ++++++
 NpgsqlRestTests/Setup/Program.cs              |  47 ++++++
 .../TsClientTests/BodyParamGetTests.cs        |  11 ++
 .../TsClientTests/OmitAutomaticParamsTests.cs | 143 ++++++++++++++++++
 changelog/v3.18.2.md                          |  12 +-
 plugins/NpgsqlRest.HttpFiles/HttpFile.cs      |  16 ++
 .../NpgsqlRest.HttpFiles/HttpFileOptions.cs   |  11 +-
 plugins/NpgsqlRest.OpenApi/OpenApi.cs         |  18 +++
 plugins/NpgsqlRest.OpenApi/OpenApiOptions.cs  |   8 +
 plugins/NpgsqlRest.TsClient/TsClient.cs       |  21 ++-
 .../NpgsqlRest.TsClient/TsClientOptions.cs    |  10 ++
 18 files changed, 512 insertions(+), 15 deletions(-)
 create mode 100644 NpgsqlRestTests/HttpFilesTests/OmitAutomaticParamsTests.cs
 create mode 100644 NpgsqlRestTests/OpenApiTests/OmitAutomaticParamsTests.cs
 create mode 100644 NpgsqlRestTests/TsClientTests/OmitAutomaticParamsTests.cs

diff --git a/NpgsqlRest/RoutineEndpoint.cs b/NpgsqlRest/RoutineEndpoint.cs
index 8efe0638..3ce81c64 100644
--- a/NpgsqlRest/RoutineEndpoint.cs
+++ b/NpgsqlRest/RoutineEndpoint.cs
@@ -388,4 +388,51 @@ internal void EnsurePathParametersHashSet()
     /// Configured via the "void" comment annotation.
     /// </summary>
     public bool Void { get; set; } = false;
+
+    /// <summary>
+    /// True when this parameter is filled by the server for this endpoint rather than supplied by the
+    /// client, so a client-provided value would be ignored (overridden). Covers, unconditionally,
+    /// HTTP Custom Type fields, resolved-parameter expressions, and upload-metadata parameters; and,
+    /// only when <see cref="UseUserParameters"/> is enabled for this endpoint, IP-address and
+    /// user-claim parameters. Whether claim/IP parameters are automatic is therefore endpoint-specific.
+    /// </summary>
+    public bool IsAutomaticParameter(NpgsqlRestParameter parameter)
+    {
+        // HTTP Custom Type expanded field — filled by the outbound HTTP call before the routine runs.
+        if (parameter.TypeDescriptor.CustomType is not null
+            && parameter.TypeDescriptor.CustomTypeName is not null
+            && HttpClientType.HttpClientTypes.Definitions.ContainsKey(parameter.TypeDescriptor.CustomType))
+        {
+            return true;
+        }
+        // Resolved-parameter expression — computed server-side via SQL at request time.
+        if (ResolvedParameterExpressions is not null
+            && (ResolvedParameterExpressions.ContainsKey(parameter.ActualName)
+                || ResolvedParameterExpressions.ContainsKey(parameter.ConvertedName)))
+        {
+            return true;
+        }
+        // Upload metadata — set by the upload handler.
+        if (parameter.IsUploadMetadata)
+        {
+            return true;
+        }
+        // IP address / user claims — only automatic when this endpoint binds user parameters.
+        if (UseUserParameters && (parameter.IsIpAddress || parameter.IsFromUserClaims))
+        {
+            return true;
+        }
+        return false;
+    }
+
+    /// <summary>
+    /// True when a parameter should be omitted from generated client request shapes (TypeScript
+    /// modules, HTTP files, OpenAPI specs). A parameter is omitted when it is
+    /// <see cref="IsAutomaticParameter"/> (the client value would be overridden) AND optional — it has
+    /// a default or is a composite / HTTP Custom Type field. The optional guard ensures omission can
+    /// never make a required argument un-sendable; an automatic-but-required parameter is kept.
+    /// </summary>
+    public bool OmitParameterFromGeneratedRequest(NpgsqlRestParameter parameter) =>
+        IsAutomaticParameter(parameter)
+        && (parameter.TypeDescriptor.HasDefault || parameter.TypeDescriptor.CustomType is not null);
 }
diff --git a/NpgsqlRestClient/App.cs b/NpgsqlRestClient/App.cs
index 25d5c636..9825f720 100644
--- a/NpgsqlRestClient/App.cs
+++ b/NpgsqlRestClient/App.cs
@@ -328,6 +328,7 @@ public string CreateUrl(Routine routine, NpgsqlRestOptions options) =>
             NameSimilarTo = _config.GetConfigStr("NameSimilarTo", openApiCfg),
             NameNotSimilarTo = _config.GetConfigStr("NameNotSimilarTo", openApiCfg),
             RequiresAuthorizationOnly = _config.GetConfigBool("RequiresAuthorizationOnly", openApiCfg, false),
+            OmitAutomaticParameters = _config.GetConfigBool("OmitAutomaticParameters", openApiCfg, false),
         };
 
         if (openApi.UrlPath is null && openApi.FileName is null)
@@ -478,7 +479,8 @@ public List<IEndpointCreateHandler> CreateCodeGenHandlers(string connectionStrin
                 CommentHeaderIncludeComments = _config.GetConfigBool("CommentHeaderIncludeComments", httpFilecfg, true),
                 FileMode = _config.GetConfigEnum<HttpFileMode?>("FileMode", httpFilecfg) ?? HttpFileMode.Schema,
                 FileOverwrite = _config.GetConfigBool("FileOverwrite", httpFilecfg, true),
-                ConnectionString = connectionString
+                ConnectionString = connectionString,
+                OmitAutomaticParameters = _config.GetConfigBool("OmitAutomaticParameters", httpFilecfg)
             }));
             _builder.ClientLogger?.LogDebug("HTTP file generation enabled. Name={Name}",
                 _config.GetConfigStr("Name", httpFilecfg) ?? "generated from connection string");
@@ -531,6 +533,7 @@ public List<IEndpointCreateHandler> CreateCodeGenHandlers(string connectionStrin
                 IncludeSchemaInNames = _config.GetConfigBool("IncludeSchemaInNames", tsClientCfg, true),
                 ErrorExpression = _config.GetConfigStr("ErrorExpression", tsClientCfg) ?? "await response.json()",
                 ErrorType = _config.GetConfigStr("ErrorType", tsClientCfg) ?? "{status: number; title: string; detail?: string | null} | undefined",
+                OmitAutomaticParameters = _config.GetConfigBool("OmitAutomaticParameters", tsClientCfg),
             };
 
             Dictionary<string, string> customHeaders = [];
diff --git a/NpgsqlRestClient/ConfigDefaults.cs b/NpgsqlRestClient/ConfigDefaults.cs
index 11579ac7..5282735d 100644
--- a/NpgsqlRestClient/ConfigDefaults.cs
+++ b/NpgsqlRestClient/ConfigDefaults.cs
@@ -945,7 +945,8 @@ private static JsonObject GetHttpFileOptionsDefaults()
             ["CommentHeader"] = "Simple",
             ["CommentHeaderIncludeComments"] = true,
             ["FileMode"] = "Schema",
-            ["FileOverwrite"] = true
+            ["FileOverwrite"] = true,
+            ["OmitAutomaticParameters"] = false
         };
     }
 
@@ -967,7 +968,8 @@ private static JsonObject GetOpenApiOptionsDefaults()
             ["ExcludeSchemas"] = new JsonArray(),
             ["NameSimilarTo"] = null,
             ["NameNotSimilarTo"] = null,
-            ["RequiresAuthorizationOnly"] = false
+            ["RequiresAuthorizationOnly"] = false,
+            ["OmitAutomaticParameters"] = false
         };
     }
 
@@ -1030,7 +1032,8 @@ private static JsonObject GetClientCodeGenDefaults()
             ["CustomHeaders"] = new JsonObject(),
             ["IncludeSchemaInNames"] = true,
             ["ErrorExpression"] = "await response.json()",
-            ["ErrorType"] = "{status: number; title: string; detail?: string | null} | undefined"
+            ["ErrorType"] = "{status: number; title: string; detail?: string | null} | undefined",
+            ["OmitAutomaticParameters"] = false
         };
     }
 
diff --git a/NpgsqlRestClient/ConfigSchemaGenerator.cs b/NpgsqlRestClient/ConfigSchemaGenerator.cs
index 9aa37e79..6e3ba10f 100644
--- a/NpgsqlRestClient/ConfigSchemaGenerator.cs
+++ b/NpgsqlRestClient/ConfigSchemaGenerator.cs
@@ -423,6 +423,7 @@ public static partial class ConfigSchemaGenerator
         ["NpgsqlRest:HttpFileOptions:CommentHeaderIncludeComments"] = "When CommentHeader is set to Simple or Full, set to true to include routine comments in comment header.",
         ["NpgsqlRest:HttpFileOptions:FileMode"] = "- Database: to create one http file for entire database.\n- Schema: to create one http file for each schema.",
         ["NpgsqlRest:HttpFileOptions:FileOverwrite"] = "Set to true to overwrite existing files.",
+        ["NpgsqlRest:HttpFileOptions:OmitAutomaticParameters"] = "When true, parameters filled by the server and not settable by the client are omitted from the generated HTTP file's query string and request body. Covers optional automatic parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and (on endpoints using user parameters) IP-address and user-claim parameters. Default is false.",
         ["NpgsqlRest:OpenApiOptions"] = "Enable or disable the generation of OpenAPI files for NpgsqlRest endpoints.",
         ["NpgsqlRest:OpenApiOptions:FileName"] = "File name for the generated OpenAPI file. Set to null to skip the file generation.",
         ["NpgsqlRest:OpenApiOptions:UrlPath"] = "URL path for the OpenAPI endpoint. Set to null to skip the endpoint generation.",
@@ -438,6 +439,7 @@ public static partial class ConfigSchemaGenerator
         ["NpgsqlRest:OpenApiOptions:NameSimilarTo"] = "PostgreSQL-style SIMILAR TO pattern matched against the routine name. When set, only routines whose name matches are documented in the OpenAPI spec. `_` matches one char, `%` matches any sequence; the rest of SIMILAR TO syntax (|, *, +, ?, (...), [...]) is supported. Anchored. Default null = no name filter.",
         ["NpgsqlRest:OpenApiOptions:NameNotSimilarTo"] = "PostgreSQL-style SIMILAR TO pattern matched against the routine name for EXCLUSION in the OpenAPI spec. Same syntax as NameSimilarTo. Applied alongside it — both must pass. Default null = no name exclusion.",
         ["NpgsqlRest:OpenApiOptions:RequiresAuthorizationOnly"] = "When true, only authenticated endpoints are documented in the OpenAPI spec. Anonymous endpoints (health, login, probes) are omitted. Default false = document everything.",
+        ["NpgsqlRest:OpenApiOptions:OmitAutomaticParameters"] = "When true, parameters filled by the server and not settable by the client are omitted from documented query parameters and request bodies. Covers optional automatic parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and (on endpoints using user parameters) IP-address and user-claim parameters. Default is false.",
         ["NpgsqlRest:McpOptions"] = "Enable or disable the MCP (Model Context Protocol) server endpoint. Disabled by default. Tools are never auto-exposed: only routines explicitly opted in with the `mcp` comment annotation become MCP tools. Implements MCP specification 2025-11-25.",
         ["NpgsqlRest:McpOptions:UrlPath"] = "URL path for the MCP endpoint (Streamable HTTP, single JSON-RPC endpoint). Default \"/mcp\".",
         ["NpgsqlRest:McpOptions:ServerName"] = "serverInfo.name reported in the MCP initialize handshake. When null, the database name from the connection string is used (falling back to \"NpgsqlRest\").",
@@ -485,6 +487,7 @@ public static partial class ConfigSchemaGenerator
         ["NpgsqlRest:ClientCodeGen:IncludeSchemaInNames"] = "When true, include PostgreSQL schema name in the generated type names to avoid name collisions. Set to false to simplify type names when no name collisions are expected.",
         ["NpgsqlRest:ClientCodeGen:ErrorExpression"] = "Expression to parse error response. Only used when IncludeStatusCode is true.",
         ["NpgsqlRest:ClientCodeGen:ErrorType"] = "TypeScript type for error response. Only used when IncludeStatusCode is true.",
+        ["NpgsqlRest:ClientCodeGen:OmitAutomaticParameters"] = "When true, parameters filled by the server and not settable by the client are omitted from the generated request interface, query string, and body. Covers optional automatic parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and (on endpoints using user parameters) IP-address and user-claim parameters. Default is false.",
         ["NpgsqlRest:HttpClientOptions"] = "HTTP client functionality for annotated composite types.\nAllows PostgreSQL functions to make HTTP requests by using specially annotated types as parameters.",
         ["NpgsqlRest:HttpClientOptions:Enabled"] = "Enable HTTP client functionality for annotated types.",
         ["NpgsqlRest:HttpClientOptions:ResponseStatusCodeField"] = "Default name for the response status code field within annotated types.",
diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index fe416ab1..7e3cb377 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -2466,7 +2466,11 @@ public static partial class ConfigSchemaGenerator
           //
           // Set to true to overwrite existing files.
           //
-          "FileOverwrite": true
+          "FileOverwrite": true,
+          //
+          // When true, parameters filled by the server and not settable by the client are omitted from the generated HTTP file's query string and request body. Covers optional automatic parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and (on endpoints using user parameters) IP-address and user-claim parameters. Default is false.
+          //
+          "OmitAutomaticParameters": false
         },
     
         //
@@ -2568,7 +2572,11 @@ public static partial class ConfigSchemaGenerator
           // documented. Anonymous endpoints — typically health, login, probes — are omitted. Useful
           // for partner-facing documents. Default false = document everything.
           //
-          "RequiresAuthorizationOnly": false
+          "RequiresAuthorizationOnly": false,
+          //
+          // When true, parameters filled by the server and not settable by the client are omitted from documented query parameters and request bodies. Covers optional automatic parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and (on endpoints using user parameters) IP-address and user-claim parameters. Default is false.
+          //
+          "OmitAutomaticParameters": false
         },
         //
         // Enable or disable the MCP (Model Context Protocol) server endpoint. Disabled by default. Tools are NEVER auto-exposed: only routines explicitly opted in with the `mcp` comment annotation become MCP tools. Implements MCP specification 2025-11-25.
@@ -2768,7 +2776,11 @@ public static partial class ConfigSchemaGenerator
           //
           // TypeScript type for error response. Only used when IncludeStatusCode is true.
           //
-          "ErrorType": "{status: number; title: string; detail?: string | null} | undefined"
+          "ErrorType": "{status: number; title: string; detail?: string | null} | undefined",
+          //
+          // When true, parameters filled by the server and not settable by the client are omitted from the generated request interface, query string, and body. Covers optional automatic parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and (on endpoints using user parameters) IP-address and user-claim parameters. Default is false.
+          //
+          "OmitAutomaticParameters": false
         },
     
         //
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index f36adda4..2146a723 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -2457,7 +2457,11 @@
       //
       // Set to true to overwrite existing files.
       //
-      "FileOverwrite": true
+      "FileOverwrite": true,
+      //
+      // When true, parameters filled by the server and not settable by the client are omitted from the generated HTTP file's query string and request body. Covers optional automatic parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and (on endpoints using user parameters) IP-address and user-claim parameters. Default is false.
+      //
+      "OmitAutomaticParameters": false
     },
 
     //
@@ -2559,7 +2563,11 @@
       // documented. Anonymous endpoints — typically health, login, probes — are omitted. Useful
       // for partner-facing documents. Default false = document everything.
       //
-      "RequiresAuthorizationOnly": false
+      "RequiresAuthorizationOnly": false,
+      //
+      // When true, parameters filled by the server and not settable by the client are omitted from documented query parameters and request bodies. Covers optional automatic parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and (on endpoints using user parameters) IP-address and user-claim parameters. Default is false.
+      //
+      "OmitAutomaticParameters": false
     },
     //
     // Enable or disable the MCP (Model Context Protocol) server endpoint. Disabled by default. Tools are NEVER auto-exposed: only routines explicitly opted in with the `mcp` comment annotation become MCP tools. Implements MCP specification 2025-11-25.
@@ -2759,7 +2767,11 @@
       //
       // TypeScript type for error response. Only used when IncludeStatusCode is true.
       //
-      "ErrorType": "{status: number; title: string; detail?: string | null} | undefined"
+      "ErrorType": "{status: number; title: string; detail?: string | null} | undefined",
+      //
+      // When true, parameters filled by the server and not settable by the client are omitted from the generated request interface, query string, and body. Covers optional automatic parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and (on endpoints using user parameters) IP-address and user-claim parameters. Default is false.
+      //
+      "OmitAutomaticParameters": false
     },
 
     //
diff --git a/NpgsqlRestTests/HttpFilesTests/OmitAutomaticParamsTests.cs b/NpgsqlRestTests/HttpFilesTests/OmitAutomaticParamsTests.cs
new file mode 100644
index 00000000..52e785df
--- /dev/null
+++ b/NpgsqlRestTests/HttpFilesTests/OmitAutomaticParamsTests.cs
@@ -0,0 +1,80 @@
+namespace NpgsqlRestTests.HttpFilesTests
+{
+    // Exercises HttpFileOptions.OmitAutomaticParameters = true (the Setup.Program "HttpFilesOmit" config).
+    // Reuses the tsclient_test.bodyparam_* functions (HTTP Custom Type parameters). Server-filled
+    // parameters that cannot be set by the client are dropped from the generated request.
+    [Collection("TestFixture")]
+    public class OmitAutomaticParamsTests
+    {
+        private static string ReadOmitFile()
+        {
+            var filePath = Path.Combine(Setup.Program.HttpFilesOmitOutputPath, "npgsqlrest.http");
+            File.Exists(filePath).Should().BeTrue($"Expected file at {filePath}");
+            return File.ReadAllText(filePath);
+        }
+
+        // GET with a normal parameter (keyword) + an HTTP Custom Type: only keyword stays on the query.
+        [Fact]
+        public void Test_MixedParams_OnlyNonAutomaticOnQuery()
+        {
+            var section = ExtractSection(ReadOmitFile(), "/api/tsclient-test/bodyparam-mixed");
+            section.Should().NotBeNull("Should find the mixed endpoint");
+
+            section.Should().Contain("keyword=", "the non-automatic parameter stays on the query string");
+            section.Should().NotContain("responseBody=", "HTTP Custom Type fields are omitted");
+            section.Should().NotContain("responseStatusCode=", "HTTP Custom Type fields are omitted");
+            section.Should().NotContain("responseSuccess=", "HTTP Custom Type fields are omitted");
+        }
+
+        // POST + @body_parameter_name targeting an HTTP Custom Type field: every parameter is automatic,
+        // so the request is just the bare URL — no query string and no body.
+        [Fact]
+        public void Test_AllAutomatic_BareRequest()
+        {
+            var section = ExtractSection(ReadOmitFile(), "/api/tsclient-test/bodyparam-expanded");
+            section.Should().NotBeNull("Should find the expanded endpoint");
+
+            section.Should().NotContain("responseBody", "HTTP Custom Type fields are omitted");
+            section.Should().NotContain("responseStatusCode", "HTTP Custom Type fields are omitted");
+            section.Should().NotContain("?", "no query string when every parameter is omitted");
+            section.Should().NotContain("content-type: application/json", "no body when the body parameter is omitted");
+        }
+
+        // Mirrors PathParameterTests.ExtractSection.
+        private static string? ExtractSection(string content, string marker)
+        {
+            var startIndex = content.IndexOf(marker, StringComparison.Ordinal);
+            if (startIndex < 0)
+            {
+                return null;
+            }
+            var blockStart = content.LastIndexOf("###", startIndex, StringComparison.Ordinal);
+            if (blockStart < 0)
+            {
+                blockStart = content.LastIndexOf("@host=", startIndex, StringComparison.Ordinal);
+                if (blockStart < 0)
+                {
+                    blockStart = 0;
+                }
+                else
+                {
+                    var nextNewline = content.IndexOf('\n', blockStart);
+                    if (nextNewline >= 0)
+                    {
+                        blockStart = nextNewline + 1;
+                    }
+                }
+            }
+            else
+            {
+                blockStart += 3;
+            }
+            var endIndex = content.IndexOf("###", startIndex, StringComparison.Ordinal);
+            if (endIndex < 0)
+            {
+                endIndex = content.Length;
+            }
+            return content.Substring(blockStart, endIndex - blockStart).Trim();
+        }
+    }
+}
diff --git a/NpgsqlRestTests/OpenApiTests/OmitAutomaticParamsTests.cs b/NpgsqlRestTests/OpenApiTests/OmitAutomaticParamsTests.cs
new file mode 100644
index 00000000..9db49d6b
--- /dev/null
+++ b/NpgsqlRestTests/OpenApiTests/OmitAutomaticParamsTests.cs
@@ -0,0 +1,50 @@
+using System.Text.Json.Nodes;
+
+namespace NpgsqlRestTests.OpenApiTests
+{
+    // Exercises OpenApiOptions.OmitAutomaticParameters = true (the Setup.Program "OpenApiOmit" config).
+    // Reuses the tsclient_test.bodyparam_* functions (HTTP Custom Type parameters). Server-filled
+    // parameters that cannot be set by the client are dropped from documented query parameters / body.
+    [Collection("TestFixture")]
+    public class OmitAutomaticParamsTests
+    {
+        private static JsonNode GetOmitDocument()
+        {
+            var filePath = Path.Combine(Setup.Program.OpenApiOmitOutputPath, "openapi.json");
+            File.Exists(filePath).Should().BeTrue($"Expected file at {filePath}");
+            var doc = JsonNode.Parse(File.ReadAllText(filePath));
+            doc.Should().NotBeNull();
+            return doc!;
+        }
+
+        // GET with a normal parameter (keyword) + an HTTP Custom Type: only keyword is documented.
+        [Fact]
+        public void Test_MixedParams_OnlyNonAutomaticDocumented()
+        {
+            var doc = GetOmitDocument();
+            var parameters = doc["paths"]?["/api/tsclient-test/bodyparam-mixed"]?["get"]?["parameters"] as JsonArray;
+            parameters.Should().NotBeNull("the GET endpoint should have query parameters documented");
+
+            var names = parameters!.Select(p => p?["name"]?.GetValue<string>()).ToList();
+            names.Should().Contain("keyword", "the non-automatic parameter is documented");
+            names.Should().NotContain("responseBody", "HTTP Custom Type fields are omitted");
+            names.Should().NotContain("responseStatusCode", "HTTP Custom Type fields are omitted");
+            names.Should().NotContain("responseSuccess", "HTTP Custom Type fields are omitted");
+            names.Should().NotContain("responseErrorMessage", "HTTP Custom Type fields are omitted");
+        }
+
+        // POST + @body_parameter_name targeting an HTTP Custom Type field: every parameter is automatic,
+        // so the operation has no documented query parameters and no request body.
+        [Fact]
+        public void Test_AllAutomatic_NoParametersNoBody()
+        {
+            var doc = GetOmitDocument();
+            var operation = doc["paths"]?["/api/tsclient-test/bodyparam-expanded"]?["post"];
+            operation.Should().NotBeNull("the POST endpoint should be documented");
+
+            var parameters = operation!["parameters"] as JsonArray;
+            (parameters is null || parameters.Count == 0).Should().BeTrue("no query parameters when every parameter is omitted");
+            operation["requestBody"].Should().BeNull("no request body when the body parameter is omitted");
+        }
+    }
+}
diff --git a/NpgsqlRestTests/Setup/Program.cs b/NpgsqlRestTests/Setup/Program.cs
index d1784a98..c9cb55ba 100644
--- a/NpgsqlRestTests/Setup/Program.cs
+++ b/NpgsqlRestTests/Setup/Program.cs
@@ -38,16 +38,31 @@ public class Program
     /// </summary>
     public static string TsClientExportOutputPath { get; } = Path.Combine(Path.GetTempPath(), "NpgsqlRestTests", "TsClientExport");
 
+    /// <summary>
+    /// Output path for TsClient generated files with OmitAutomaticParameters=true (used by tests)
+    /// </summary>
+    public static string TsClientOmitOutputPath { get; } = Path.Combine(Path.GetTempPath(), "NpgsqlRestTests", "TsClientOmit");
+
     /// <summary>
     /// Output path for HttpFiles generated files (used by tests)
     /// </summary>
     public static string HttpFilesOutputPath { get; } = Path.Combine(Path.GetTempPath(), "NpgsqlRestTests", "HttpFiles");
 
+    /// <summary>
+    /// Output path for HttpFiles generated files with OmitAutomaticParameters=true (used by tests)
+    /// </summary>
+    public static string HttpFilesOmitOutputPath { get; } = Path.Combine(Path.GetTempPath(), "NpgsqlRestTests", "HttpFilesOmit");
+
     /// <summary>
     /// Output path for OpenApi generated files (used by tests)
     /// </summary>
     public static string OpenApiOutputPath { get; } = Path.Combine(Path.GetTempPath(), "NpgsqlRestTests", "OpenApi");
 
+    /// <summary>
+    /// Output path for OpenApi generated files with OmitAutomaticParameters=true (used by tests)
+    /// </summary>
+    public static string OpenApiOmitOutputPath { get; } = Path.Combine(Path.GetTempPath(), "NpgsqlRestTests", "OpenApiOmit");
+
     static async Task ValidateAsync(ParameterValidationValues p)
     {
         if (p.Routine.Name == "case_jsonpath_param" && p.Parameter.Value?.ToString() == "XXX")
@@ -249,6 +264,20 @@ public static void Main()
                     SkipSchemas = ["public", "custom_param_schema", "my_schema", "custom_table_param_schema", ""],
                     IncludeStatusCode = false
                 }),
+                // TsClient configuration for OmitAutomaticParameters testing - server-filled params omitted
+                new TsClient(new TsClientOptions
+                {
+                    FilePath = Path.Combine(TsClientOmitOutputPath, "{0}.ts"),
+                    FileOverwrite = true,
+                    BySchema = true,
+                    IncludeHost = false,
+                    CreateSeparateTypeFile = false,
+                    CommentHeader = CommentHeader.Simple,
+                    HeaderLines = [],
+                    SkipSchemas = ["public", "custom_param_schema", "my_schema", "custom_table_param_schema", ""],
+                    IncludeStatusCode = false,
+                    OmitAutomaticParameters = true
+                }),
                 // HttpFiles configuration for testing path parameters
                 new HttpFile(new HttpFileOptions
                 {
@@ -257,6 +286,15 @@ public static void Main()
                     FileOverwrite = true,
                     CommentHeader = CommentHeader.None
                 }),
+                // HttpFiles configuration for OmitAutomaticParameters testing
+                new HttpFile(new HttpFileOptions
+                {
+                    Option = HttpFileOption.File,
+                    NamePattern = Path.Combine(HttpFilesOmitOutputPath, "{0}"),
+                    FileOverwrite = true,
+                    CommentHeader = CommentHeader.None,
+                    OmitAutomaticParameters = true
+                }),
                 // OpenApi configuration for testing path parameters
                 new OpenApi(new OpenApiOptions
                 {
@@ -265,6 +303,15 @@ public static void Main()
                     DocumentTitle = "NpgsqlRest Test API",
                     AddCurrentServer = false
                 }),
+                // OpenApi configuration for OmitAutomaticParameters testing
+                new OpenApi(new OpenApiOptions
+                {
+                    FileName = Path.Combine(OpenApiOmitOutputPath, "openapi.json"),
+                    FileOverwrite = true,
+                    DocumentTitle = "NpgsqlRest Test API",
+                    AddCurrentServer = false,
+                    OmitAutomaticParameters = true
+                }),
             ],
             CommentsMode = CommentsMode.ParseAll,
             ValidateParametersAsync = ValidateAsync,
diff --git a/NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs b/NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs
index f5f2d528..3f7ed1e0 100644
--- a/NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs
+++ b/NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs
@@ -43,6 +43,17 @@ comment on function tsclient_test.bodyparam_expanded(tsclient_test.tsc_http_prob
 HTTP POST
 tsclient_module=bodyparam_expanded
 body_parameter_name _response_body';
+
+-- Mixed: a normal client parameter (_keyword) alongside an HTTP Custom Type. With
+-- OmitAutomaticParameters enabled, the four HTTP-type fields are dropped but _keyword stays in the
+-- request and on the query string.
+create function tsclient_test.bodyparam_mixed(_keyword text, _response tsclient_test.tsc_http_probe default null)
+returns text
+language plpgsql
+as $$ begin return _keyword; end; $$;
+comment on function tsclient_test.bodyparam_mixed(text, tsclient_test.tsc_http_probe) is '
+HTTP GET
+tsclient_module=bodyparam_mixed';
 """);
         }
     }
diff --git a/NpgsqlRestTests/TsClientTests/OmitAutomaticParamsTests.cs b/NpgsqlRestTests/TsClientTests/OmitAutomaticParamsTests.cs
new file mode 100644
index 00000000..e6f9dcb1
--- /dev/null
+++ b/NpgsqlRestTests/TsClientTests/OmitAutomaticParamsTests.cs
@@ -0,0 +1,143 @@
+namespace NpgsqlRestTests.TsClientTests
+{
+    // Exercises TsClientOptions.OmitAutomaticParameters = true (the Setup.Program "TsClientOmit" config).
+    // Server-filled parameters that cannot be set by the client are dropped from the generated request.
+    [Collection("TestFixture")]
+    public class OmitAutomaticParamsTests
+    {
+        // All parameters are HTTP Custom Type fields (automatic + optional) → the whole request collapses:
+        // no request interface, no argument, no body, no query.
+        private const string ExpectedAllOmitted = """
+const baseUrl = "";
+const parseQuery = (query: Record<any, any>) => "?" + Object.keys(query ? query : {})
+    .map(key => {
+        const value = (query[key] != null ? query[key] : "") as string;
+        if (Array.isArray(value)) {
+            return value.map((s: string) => s ? `${key}=${encodeURIComponent(s)}` : `${key}=`).join("&");
+        }
+        return `${key}=${encodeURIComponent(value)}`;
+    })
+    .join("&");
+
+
+/**
+* function tsclient_test.bodyparam_expanded(
+*     _response_body text DEFAULT NULL::tsclient_test.tsc_http_probe,
+*     _response_status_code integer,
+*     _response_success boolean,
+*     _response_error_message text
+* )
+* returns text
+*
+* @remarks
+* comment on function tsclient_test.bodyparam_expanded is 'HTTP POST
+* tsclient_module=bodyparam_expanded
+* body_parameter_name _response_body';
+*
+* @returns {string}
+*
+* @see FUNCTION tsclient_test.bodyparam_expanded
+*/
+export async function tsclientTestBodyparamExpanded() : Promise<string> {
+    const response = await fetch(baseUrl + "/api/tsclient-test/bodyparam-expanded", {
+        method: "POST",
+    });
+    return await response.text();
+}
+
+
+""";
+
+        [Fact]
+        public void Test_AllAutomatic_OmittedEntirely()
+        {
+            var filePath = Path.Combine(Setup.Program.TsClientOmitOutputPath, "bodyparam_expanded.ts");
+            File.Exists(filePath).Should().BeTrue($"Expected file at {filePath}");
+
+            var content = File.ReadAllText(filePath);
+
+            content.Should().NotContain("responseBody", "automatic HTTP-type fields must be omitted");
+            content.Should().NotContain("interface ", "no request interface when every parameter is omitted");
+            content.Should().NotContain("body:", "no body for an omitted body parameter");
+            content.Should().NotContain("+ parseQuery", "no query call when every parameter is omitted");
+            content.Should().Contain("tsclientTestBodyparamExpanded()", "the function takes no request argument");
+
+            Normalize(content).Should().Be(Normalize(ExpectedAllOmitted));
+        }
+
+        // Mixed: a normal parameter (keyword) survives; the HTTP-type fields are omitted.
+        private const string ExpectedMixed = """
+const baseUrl = "";
+const parseQuery = (query: Record<any, any>) => "?" + Object.keys(query ? query : {})
+    .map(key => {
+        const value = (query[key] != null ? query[key] : "") as string;
+        if (Array.isArray(value)) {
+            return value.map((s: string) => s ? `${key}=${encodeURIComponent(s)}` : `${key}=`).join("&");
+        }
+        return `${key}=${encodeURIComponent(value)}`;
+    })
+    .join("&");
+
+interface ITsclientTestBodyparamMixedRequest {
+    keyword: string | null;
+}
+
+
+/**
+* function tsclient_test.bodyparam_mixed(
+*     _keyword text,
+*     _response_body text DEFAULT NULL::tsclient_test.tsc_http_probe,
+*     _response_status_code integer,
+*     _response_success boolean,
+*     _response_error_message text
+* )
+* returns text
+*
+* @remarks
+* comment on function tsclient_test.bodyparam_mixed is 'HTTP GET
+* tsclient_module=bodyparam_mixed';
+*
+* @param request - Object containing request parameters.
+* @returns {string}
+*
+* @see FUNCTION tsclient_test.bodyparam_mixed
+*/
+export async function tsclientTestBodyparamMixed(
+    request: ITsclientTestBodyparamMixedRequest
+) : Promise<string> {
+    const response = await fetch(baseUrl + "/api/tsclient-test/bodyparam-mixed" + parseQuery(request), {
+        method: "GET",
+    });
+    return await response.text();
+}
+
+
+""";
+
+        [Fact]
+        public void Test_MixedParams_KeepsNonAutomatic()
+        {
+            var filePath = Path.Combine(Setup.Program.TsClientOmitOutputPath, "bodyparam_mixed.ts");
+            File.Exists(filePath).Should().BeTrue($"Expected file at {filePath}");
+
+            var content = File.ReadAllText(filePath);
+
+            content.Should().Contain("keyword: string | null;", "non-automatic parameters are kept");
+            content.Should().NotContain("responseBody", "automatic HTTP-type fields must be omitted");
+            content.Should().NotContain("responseStatusCode", "automatic HTTP-type fields must be omitted");
+            content.Should().Contain("parseQuery(request)", "the surviving parameter is still sent on the query");
+
+            Normalize(content).Should().Be(Normalize(ExpectedMixed));
+        }
+
+        private static string Normalize(string s)
+        {
+            var lines = s.Replace("\r\n", "\n").Split('\n');
+            for (var i = 0; i < lines.Length; i++)
+            {
+                lines[i] = lines[i].TrimEnd();
+            }
+            return string.Join("\n", lines);
+        }
+    }
+}
diff --git a/changelog/v3.18.2.md b/changelog/v3.18.2.md
index 043ce45f..21e10fe3 100644
--- a/changelog/v3.18.2.md
+++ b/changelog/v3.18.2.md
@@ -4,7 +4,7 @@
 
 [Full Changelog](https://github.com/NpgsqlRest/NpgsqlRest/compare/3.18.1...3.18.2)
 
-Patch release with two fixes for **proxy endpoints that forward auto-filled parameters** (v3.18.1), surfaced by combining a `@proxy` with an HTTP Custom Type parameter.
+Patch release with fixes for **proxy endpoints that forward auto-filled parameters** (v3.18.1) and the generated TypeScript client, plus a new opt-in option to **omit server-filled parameters from generated request shapes**. All surfaced by combining a `@proxy` with an HTTP Custom Type parameter.
 
 ## What changed
 
@@ -34,6 +34,14 @@ The generated TypeScript client was broken for an endpoint with `@body_parameter
 
 The generator now uses the parameter's bare name for the body expression and the exclusion key, only emits a `fetch` body for methods that can carry one (not `GET`), and — like the server — matches `@body_parameter_name` against the converted, actual, or expanded signature name of an HTTP Custom Type field (e.g. `responseBody`, `_response`, or `_response_body`).
 
+### 4. Opt-in: omit automatic (server-filled) parameters from generated request shapes
+
+New option **`OmitAutomaticParameters`** on all three generators — `TsClientOptions`, `HttpFileOptions`, and `OpenApiOptions` (default **`false`**, so generated output is unchanged unless you opt in).
+
+When enabled, a parameter is omitted from the generated request (TypeScript request interface, `.http` query/body, OpenAPI query parameters / request body) when it is **automatic** (filled server-side, so a client value would be ignored) **and** optional. Automatic covers: HTTP Custom Type fields, resolved-parameter expressions, upload-metadata parameters, and — on endpoints that use user parameters — IP-address and user-claim parameters. The shared rule lives on the core endpoint (`RoutineEndpoint.OmitParameterFromGeneratedRequest`), so the three generators stay consistent. When every parameter is omitted, the generated request collapses cleanly (no-argument TS function, bare `.http` URL, no OpenAPI `parameters`/`requestBody`).
+
+This is the proper fix for the misleading case where, e.g., an HTTP Custom Type's `responseBody` field appeared as a settable request parameter even though the server always overrides it.
+
 ### Why these go together
 
 The pattern "fetch with an HTTP Custom Type, then `@proxy` to an upstream" now works cleanly end to end — server **and** generated client: redirect the (large) body field into the upstream request body with `@body_parameter_name`, while the remaining small fields travel on the query string under the new length guard.
@@ -45,4 +53,4 @@ The pattern "fetch with an HTTP Custom Type, then `@proxy` to an upstream" now w
 
 ## Tests
 
-`NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs` adds three cases (WireMock proxy target echoing the received URL / body): body redirect by converted name (`responseBody`), body redirect by expanded signature name (`_response_body`), and an oversized HTTP-type body field skipped from the proxy query string. `NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs` covers the generated client for `@body_parameter_name` endpoints: a `GET` case (no `?`-suffixed name, parameter excluded from the query, no `fetch` body on `GET`) and a `POST` HTTP-Custom-Type case targeted by the expanded name `_response_body` (body emitted as `request.responseBody`, excluded from the query). Full suite green (2293).
+`NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs` adds three cases (WireMock proxy target echoing the received URL / body): body redirect by converted name (`responseBody`), body redirect by expanded signature name (`_response_body`), and an oversized HTTP-type body field skipped from the proxy query string. `NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs` covers the generated client for `@body_parameter_name` endpoints: a `GET` case (no `?`-suffixed name, parameter excluded from the query, no `fetch` body on `GET`) and a `POST` HTTP-Custom-Type case targeted by the expanded name `_response_body` (body emitted as `request.responseBody`, excluded from the query). `OmitAutomaticParameters` is covered for each generator (TsClient: all-omitted no-arg function + mixed-params; HttpFiles and OpenAPI: query/body omission of HTTP Custom Type fields). Full suite green (2299).
diff --git a/plugins/NpgsqlRest.HttpFiles/HttpFile.cs b/plugins/NpgsqlRest.HttpFiles/HttpFile.cs
index 207eae06..e3ae7a69 100644
--- a/plugins/NpgsqlRest.HttpFiles/HttpFile.cs
+++ b/plugins/NpgsqlRest.HttpFiles/HttpFile.cs
@@ -94,6 +94,12 @@ public void Handle(RoutineEndpoint endpoint)
                     .Parameters
                     .Where((p, i) =>
                     {
+                        // Skip server-filled parameters the client cannot set (when enabled)
+                        if (httpFileOptions.OmitAutomaticParameters && endpoint.OmitParameterFromGeneratedRequest(p))
+                        {
+                            return false;
+                        }
+
                         // Skip body parameter
                         if (endpoint.BodyParameterName is not null)
                         {
@@ -139,6 +145,11 @@ public void Handle(RoutineEndpoint endpoint)
                     if (string.Equals(endpoint.Routine.Parameters[i].ConvertedName, endpoint.BodyParameterName, StringComparison.Ordinal) ||
                         string.Equals(endpoint.Routine.Parameters[i].ActualName, endpoint.BodyParameterName, StringComparison.Ordinal))
                     {
+                        // A server-filled body parameter (e.g. an HTTP Custom Type field) is not sent by the client.
+                        if (httpFileOptions.OmitAutomaticParameters && endpoint.OmitParameterFromGeneratedRequest(endpoint.Routine.Parameters[i]))
+                        {
+                            break;
+                        }
                         sb.AppendLine();
                         sb.AppendLine(SampleValueUnquoted(i, endpoint.Routine.Parameters[i].TypeDescriptor));
                         break;
@@ -154,6 +165,11 @@ public void Handle(RoutineEndpoint endpoint)
                 .Select((p, i) => (param: p, index: i))
                 .Where(x =>
                 {
+                    // Skip server-filled parameters the client cannot set (when enabled)
+                    if (httpFileOptions.OmitAutomaticParameters && endpoint.OmitParameterFromGeneratedRequest(x.param))
+                    {
+                        return false;
+                    }
                     if (endpoint.HasPathParameters)
                     {
                         foreach (var pathParam in endpoint.PathParameters!)
diff --git a/plugins/NpgsqlRest.HttpFiles/HttpFileOptions.cs b/plugins/NpgsqlRest.HttpFiles/HttpFileOptions.cs
index a33a6b34..c0a1647c 100644
--- a/plugins/NpgsqlRest.HttpFiles/HttpFileOptions.cs
+++ b/plugins/NpgsqlRest.HttpFiles/HttpFileOptions.cs
@@ -8,7 +8,8 @@ public class HttpFileOptions(
     HttpFileMode fileMode = HttpFileMode.Database,
     bool fileOverwrite = false,
     string? connectionString = null,
-    string? name = null)
+    string? name = null,
+    bool omitAutomaticParameters = false)
 {
     public static HttpFileOptions CreateBoth() => new(option: HttpFileOption.Both);
     public static HttpFileOptions CreateFile() => new(option: HttpFileOption.File);
@@ -61,4 +62,12 @@ public HttpFileOptions() : this(option: HttpFileOption.Both) { }
     /// If neither ConnectionString nor Name is set, the file name will be "npgsqlrest".
     /// </summary>
     public string? Name { get; set; } = name;
+
+    /// <summary>
+    /// When true, parameters that are filled by the server and cannot be set by the client are omitted
+    /// from the generated HTTP file's query string and request body. Covers optional automatic
+    /// parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and — on
+    /// endpoints that use user parameters — IP-address and user-claim parameters. Default is false.
+    /// </summary>
+    public bool OmitAutomaticParameters { get; set; } = omitAutomaticParameters;
 }
diff --git a/plugins/NpgsqlRest.OpenApi/OpenApi.cs b/plugins/NpgsqlRest.OpenApi/OpenApi.cs
index c29d9399..a0eacd86 100644
--- a/plugins/NpgsqlRest.OpenApi/OpenApi.cs
+++ b/plugins/NpgsqlRest.OpenApi/OpenApi.cs
@@ -249,6 +249,12 @@ public void Handle(RoutineEndpoint endpoint)
             {
                 foreach (var param in endpoint.Routine.Parameters)
                 {
+                    // Skip server-filled parameters the client cannot set (when enabled)
+                    if (openApiOptions.OmitAutomaticParameters && endpoint.OmitParameterFromGeneratedRequest(param))
+                    {
+                        continue;
+                    }
+
                     // Skip body parameter if it exists
                     if (endpoint.BodyParameterName is not null &&
                         (string.Equals(param.ConvertedName, endpoint.BodyParameterName, StringComparison.Ordinal) ||
@@ -301,6 +307,12 @@ public void Handle(RoutineEndpoint endpoint)
 
                 foreach (var param in endpoint.Routine.Parameters)
                 {
+                    // Skip server-filled parameters the client cannot set (when enabled)
+                    if (openApiOptions.OmitAutomaticParameters && endpoint.OmitParameterFromGeneratedRequest(param))
+                    {
+                        continue;
+                    }
+
                     // Skip path parameters - they should not be in the request body
                     if (endpoint.HasPathParameters)
                     {
@@ -363,6 +375,12 @@ public void Handle(RoutineEndpoint endpoint)
                     string.Equals(p.ConvertedName, endpoint.BodyParameterName, StringComparison.Ordinal) ||
                     string.Equals(p.ActualName, endpoint.BodyParameterName, StringComparison.Ordinal));
 
+            // A server-filled body parameter (e.g. an HTTP Custom Type field) is not part of the client contract.
+            if (bodyParam is not null && openApiOptions.OmitAutomaticParameters && endpoint.OmitParameterFromGeneratedRequest(bodyParam))
+            {
+                bodyParam = null;
+            }
+
             if (bodyParam is not null)
             {
                 operation["requestBody"] = new JsonObject
diff --git a/plugins/NpgsqlRest.OpenApi/OpenApiOptions.cs b/plugins/NpgsqlRest.OpenApi/OpenApiOptions.cs
index c52a2c09..84e9d0dc 100644
--- a/plugins/NpgsqlRest.OpenApi/OpenApiOptions.cs
+++ b/plugins/NpgsqlRest.OpenApi/OpenApiOptions.cs
@@ -105,6 +105,14 @@ public class OpenApiOptions
     /// internal anonymous surface should not be advertised.
     /// </summary>
     public bool RequiresAuthorizationOnly { get; set; } = false;
+
+    /// <summary>
+    /// When true, parameters that are filled by the server and cannot be set by the client are omitted
+    /// from the documented query parameters and request body. Covers optional automatic parameters:
+    /// HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and — on endpoints that
+    /// use user parameters — IP-address and user-claim parameters. Default is false.
+    /// </summary>
+    public bool OmitAutomaticParameters { get; set; } = false;
 }
 
 /// <summary>
diff --git a/plugins/NpgsqlRest.TsClient/TsClient.cs b/plugins/NpgsqlRest.TsClient/TsClient.cs
index 4a32b33a..f5d406fb 100644
--- a/plugins/NpgsqlRest.TsClient/TsClient.cs
+++ b/plugins/NpgsqlRest.TsClient/TsClient.cs
@@ -465,11 +465,21 @@ bool Handle(RoutineEndpoint endpoint)
 
             string? requestName = null;
             string[] paramNames = new string[paramCount];
+            // Parameters that are filled server-side and cannot be set by the client are omitted from the
+            // generated request shape when OmitAutomaticParameters is enabled (interface, query, body).
+            bool[] omitParam = new bool[paramCount];
+            int requestParamCount = 0;
             string? bodyParameterName = null;
             for (var i = 0; i < paramCount; i++)
             {
                 var parameter = routine.Parameters[i];
                 var descriptor = parameter.TypeDescriptor;//paramTypeDescriptors[i];
+                if (options.OmitAutomaticParameters && endpoint.OmitParameterFromGeneratedRequest(parameter))
+                {
+                    omitParam[i] = true;
+                    continue;
+                }
+                requestParamCount++;
                 var nameSuffix = (descriptor.HasDefault || descriptor.CustomType is not null) ? "?" : "";
                 paramNames[i] = QuoteJavaScriptVariableName($"{parameter.ConvertedName}{nameSuffix}");
                 if (string.Equals(endpoint.BodyParameterName, parameter.ConvertedName, StringComparison.OrdinalIgnoreCase) ||
@@ -487,7 +497,7 @@ bool Handle(RoutineEndpoint endpoint)
                 }
             }
             string requestDesc = "";
-            if (paramCount > 0)
+            if (requestParamCount > 0)
             {
                 StringBuilder req = new();
                 requestName = $"I{pascal}Request";
@@ -495,6 +505,11 @@ bool Handle(RoutineEndpoint endpoint)
                 var seenParamNames = new HashSet<string>(StringComparer.Ordinal);
                 for (var i = 0; i < paramCount; i++)
                 {
+                    // Skip omitted (server-filled) parameters — their name was not assigned.
+                    if (omitParam[i])
+                    {
+                        continue;
+                    }
                     // Skip duplicate parameter names (e.g., when multiple HTTP custom types share field names)
                     if (!seenParamNames.Add(paramNames[i]))
                     {
@@ -917,7 +932,9 @@ string NewLine(string? input, int ident) =>
             var hasPathParams = endpoint.HasPathParameters;
             var pathParamCount = endpoint.PathParameters?.Length ?? 0;
             var bodyParamCount = bodyParameterName is not null ? 1 : 0;
-            var queryParamCount = paramCount - pathParamCount - bodyParamCount;
+            // requestParamCount already excludes omitted (server-filled) parameters; path parameters are
+            // never omitted, so subtracting them and the body parameter yields the query parameter count.
+            var queryParamCount = requestParamCount - pathParamCount - bodyParamCount;
 
             string qs;
             if (endpoint.RequestParamType == RequestParamType.QueryString && requestName is not null && queryParamCount > 0)
diff --git a/plugins/NpgsqlRest.TsClient/TsClientOptions.cs b/plugins/NpgsqlRest.TsClient/TsClientOptions.cs
index 028eaae5..9c73e9b6 100644
--- a/plugins/NpgsqlRest.TsClient/TsClientOptions.cs
+++ b/plugins/NpgsqlRest.TsClient/TsClientOptions.cs
@@ -180,4 +180,14 @@ public class TsClientOptions
     /// Default is "ApiResult".
     /// </summary>
     public string ResultTypeName { get; set; } = "ApiResult";
+
+    /// <summary>
+    /// When true, parameters that are filled by the server and cannot be set by the client are omitted
+    /// from the generated request interface, query string, and body. This covers automatic parameters
+    /// that are also optional: HTTP Custom Type fields, resolved-parameter expressions, upload metadata,
+    /// and — on endpoints that use user parameters — IP-address and user-claim parameters. A client value
+    /// for these would be overridden server-side, so emitting them is misleading. Default is false
+    /// (all parameters are emitted, preserving existing generated output).
+    /// </summary>
+    public bool OmitAutomaticParameters { get; set; } = false;
 }

From 185698f0f08e70e725783b4d98cecb7558aedac7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Fri, 26 Jun 2026 14:47:48 +0200
Subject: [PATCH 10/25] fix(codegen): @body_parameter_name resolves in HTTP
 files and OpenAPI; unify body-param matching
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The HTTP file and OpenAPI generators matched the @body_parameter_name parameter
with a case-sensitive Ordinal comparison against only the converted and actual
names. An HTTP Custom Type field targeted by its expanded name (e.g.
_response_body) was therefore not recognized as the body parameter: it stayed on
the query string instead of being moved into the request body. (The TypeScript
client and the server were already fixed; these two generators had drifted.)

Body-parameter resolution is now a single shared rule, RoutineEndpoint.
IsBodyParameter(param) — case-insensitive, matching the converted, actual, or
expanded per-field name. Every call site routes through it: the proxy forwarder,
the request-handling body branch, and the TypeScript, HTTP file, and OpenAPI
generators. No more re-inlined three-name comparisons to drift.

Tests: HttpFilesTests/BodyParamToBodyTests and OpenApiTests/BodyParamToBodyTests
assert that an expanded-name body parameter is emitted as the request body (not
the query) in both generators. Full suite green (2301).

See changelog/v3.18.2.md. version.txt / npm not bumped yet.
---
 NpgsqlRest/NpgsqlRestEndpoint.cs              |  8 +--
 NpgsqlRest/Proxy/ProxyRequestHandler.cs       |  4 +-
 NpgsqlRest/RoutineEndpoint.cs                 | 19 ++++++
 .../HttpFilesTests/BodyParamToBodyTests.cs    | 64 +++++++++++++++++++
 .../OpenApiTests/BodyParamToBodyTests.cs      | 30 +++++++++
 changelog/v3.18.2.md                          |  4 +-
 plugins/NpgsqlRest.HttpFiles/HttpFile.cs      | 11 +---
 plugins/NpgsqlRest.OpenApi/OpenApi.cs         |  8 +--
 plugins/NpgsqlRest.TsClient/TsClient.cs       |  7 +-
 9 files changed, 124 insertions(+), 31 deletions(-)
 create mode 100644 NpgsqlRestTests/HttpFilesTests/BodyParamToBodyTests.cs
 create mode 100644 NpgsqlRestTests/OpenApiTests/BodyParamToBodyTests.cs

diff --git a/NpgsqlRest/NpgsqlRestEndpoint.cs b/NpgsqlRest/NpgsqlRestEndpoint.cs
index 3a48e272..dfd84d93 100644
--- a/NpgsqlRest/NpgsqlRestEndpoint.cs
+++ b/NpgsqlRest/NpgsqlRestEndpoint.cs
@@ -440,13 +440,7 @@ public async Task InvokeAsync(HttpContext context, IServiceProvider serviceProvi
                     }
 
                     // body parameter
-                    if (parameter.Value is null && endpoint.HasBodyParameter &&
-                        (
-                        string.Equals(endpoint.BodyParameterName, parameter.ConvertedName, StringComparison.OrdinalIgnoreCase) ||
-                        string.Equals(endpoint.BodyParameterName, parameter.ActualName, StringComparison.OrdinalIgnoreCase) ||
-                        (parameter.ExpandedName is not null && string.Equals(endpoint.BodyParameterName, parameter.ExpandedName, StringComparison.OrdinalIgnoreCase))
-                        )
-                    )
+                    if (parameter.Value is null && endpoint.IsBodyParameter(parameter))
                     {
                         if (body is null)
                         {
diff --git a/NpgsqlRest/Proxy/ProxyRequestHandler.cs b/NpgsqlRest/Proxy/ProxyRequestHandler.cs
index 4d5f66b5..6bec26e8 100644
--- a/NpgsqlRest/Proxy/ProxyRequestHandler.cs
+++ b/NpgsqlRest/Proxy/ProxyRequestHandler.cs
@@ -273,9 +273,7 @@ private static bool IsAutomaticParam(RoutineEndpoint endpoint, NpgsqlRestParamet
         }
         foreach (var p in parameters)
         {
-            if (string.Equals(endpoint.BodyParameterName, p.ConvertedName, StringComparison.OrdinalIgnoreCase)
-                || string.Equals(endpoint.BodyParameterName, p.ActualName, StringComparison.OrdinalIgnoreCase)
-                || (p.ExpandedName is not null && string.Equals(endpoint.BodyParameterName, p.ExpandedName, StringComparison.OrdinalIgnoreCase)))
+            if (endpoint.IsBodyParameter(p))
             {
                 return p;
             }
diff --git a/NpgsqlRest/RoutineEndpoint.cs b/NpgsqlRest/RoutineEndpoint.cs
index 3ce81c64..a54bd253 100644
--- a/NpgsqlRest/RoutineEndpoint.cs
+++ b/NpgsqlRest/RoutineEndpoint.cs
@@ -435,4 +435,23 @@ public bool IsAutomaticParameter(NpgsqlRestParameter parameter)
     public bool OmitParameterFromGeneratedRequest(NpgsqlRestParameter parameter) =>
         IsAutomaticParameter(parameter)
         && (parameter.TypeDescriptor.HasDefault || parameter.TypeDescriptor.CustomType is not null);
+
+    /// <summary>
+    /// True when this parameter is the one designated by <c>@body_parameter_name</c> — it carries the
+    /// raw request body rather than a query/JSON field. The configured name is matched
+    /// case-insensitively against the parameter's converted (API) name, its actual (database) name, or
+    /// its expanded per-field name (for an HTTP Custom Type field expanded from a composite, e.g.
+    /// <c>responseBody</c> / <c>_response</c> / <c>_response_body</c>). Single source of truth for body-
+    /// parameter resolution across request handling and all code generators.
+    /// </summary>
+    public bool IsBodyParameter(NpgsqlRestParameter parameter)
+    {
+        if (!HasBodyParameter)
+        {
+            return false;
+        }
+        return string.Equals(BodyParameterName, parameter.ConvertedName, StringComparison.OrdinalIgnoreCase)
+            || string.Equals(BodyParameterName, parameter.ActualName, StringComparison.OrdinalIgnoreCase)
+            || (parameter.ExpandedName is not null && string.Equals(BodyParameterName, parameter.ExpandedName, StringComparison.OrdinalIgnoreCase));
+    }
 }
diff --git a/NpgsqlRestTests/HttpFilesTests/BodyParamToBodyTests.cs b/NpgsqlRestTests/HttpFilesTests/BodyParamToBodyTests.cs
new file mode 100644
index 00000000..c54c35f2
--- /dev/null
+++ b/NpgsqlRestTests/HttpFilesTests/BodyParamToBodyTests.cs
@@ -0,0 +1,64 @@
+namespace NpgsqlRestTests.HttpFilesTests
+{
+    // Regression: @body_parameter_name targeting an HTTP Custom Type field by its expanded name
+    // (_response_body) must move that field into the request BODY, not leave it in the query string.
+    // Reads the default (omission-off) HTTP file. Reuses tsclient_test.bodyparam_expanded.
+    [Collection("TestFixture")]
+    public class BodyParamToBodyTests
+    {
+        [Fact]
+        public void Test_ExpandedBodyParam_GoesToBodyNotQuery()
+        {
+            var filePath = Path.Combine(Setup.Program.HttpFilesOutputPath, "npgsqlrest.http");
+            File.Exists(filePath).Should().BeTrue($"Expected file at {filePath}");
+
+            var section = ExtractSection(File.ReadAllText(filePath), "/api/tsclient-test/bodyparam-expanded");
+            section.Should().NotBeNull("Should find the expanded endpoint");
+
+            var urlLine = section!.Split('\n')[0];
+            // The body parameter must NOT be on the query string …
+            urlLine.Should().NotContain("responseBody=", "the body parameter belongs in the body, not the query");
+            // … while the remaining small fields still travel on the query.
+            urlLine.Should().Contain("responseStatusCode=", "non-body fields stay on the query string");
+            // … and the body value is emitted after the request line.
+            var afterUrl = section[(section.IndexOf('\n') + 1)..].Trim();
+            afterUrl.Should().NotBeEmpty("the body parameter value must be emitted as the request body");
+        }
+
+        private static string? ExtractSection(string content, string marker)
+        {
+            var startIndex = content.IndexOf(marker, StringComparison.Ordinal);
+            if (startIndex < 0)
+            {
+                return null;
+            }
+            var blockStart = content.LastIndexOf("###", startIndex, StringComparison.Ordinal);
+            if (blockStart < 0)
+            {
+                blockStart = content.LastIndexOf("@host=", startIndex, StringComparison.Ordinal);
+                if (blockStart < 0)
+                {
+                    blockStart = 0;
+                }
+                else
+                {
+                    var nextNewline = content.IndexOf('\n', blockStart);
+                    if (nextNewline >= 0)
+                    {
+                        blockStart = nextNewline + 1;
+                    }
+                }
+            }
+            else
+            {
+                blockStart += 3;
+            }
+            var endIndex = content.IndexOf("###", startIndex, StringComparison.Ordinal);
+            if (endIndex < 0)
+            {
+                endIndex = content.Length;
+            }
+            return content.Substring(blockStart, endIndex - blockStart).Trim();
+        }
+    }
+}
diff --git a/NpgsqlRestTests/OpenApiTests/BodyParamToBodyTests.cs b/NpgsqlRestTests/OpenApiTests/BodyParamToBodyTests.cs
new file mode 100644
index 00000000..2855f92e
--- /dev/null
+++ b/NpgsqlRestTests/OpenApiTests/BodyParamToBodyTests.cs
@@ -0,0 +1,30 @@
+using System.Text.Json.Nodes;
+
+namespace NpgsqlRestTests.OpenApiTests
+{
+    // Regression: @body_parameter_name targeting an HTTP Custom Type field by its expanded name
+    // (_response_body) must document that field as the request body, not as a query parameter.
+    // Reads the default (omission-off) document. Reuses tsclient_test.bodyparam_expanded.
+    [Collection("TestFixture")]
+    public class BodyParamToBodyTests
+    {
+        [Fact]
+        public void Test_ExpandedBodyParam_DocumentedAsBodyNotQuery()
+        {
+            var filePath = Path.Combine(Setup.Program.OpenApiOutputPath, "openapi.json");
+            File.Exists(filePath).Should().BeTrue($"Expected file at {filePath}");
+            var doc = JsonNode.Parse(File.ReadAllText(filePath))!;
+
+            var operation = doc["paths"]?["/api/tsclient-test/bodyparam-expanded"]?["post"];
+            operation.Should().NotBeNull("the POST endpoint should be documented");
+
+            var names = (operation!["parameters"] as JsonArray ?? [])
+                .Select(p => p?["name"]?.GetValue<string>())
+                .ToList();
+
+            names.Should().NotContain("responseBody", "the body parameter must not be a query parameter");
+            names.Should().Contain("responseStatusCode", "non-body fields stay as query parameters");
+            operation["requestBody"].Should().NotBeNull("the body parameter must be documented as the request body");
+        }
+    }
+}
diff --git a/changelog/v3.18.2.md b/changelog/v3.18.2.md
index 21e10fe3..4f118ead 100644
--- a/changelog/v3.18.2.md
+++ b/changelog/v3.18.2.md
@@ -24,6 +24,8 @@ Previously, an HTTP Custom Type whose `body` field held a large payload (e.g. a
 
 Previously the annotation value was force-lowercased and compared case-sensitively, so the camelCase converted name never matched, and the expanded signature name (`_response_body`) matched nothing at all — it is stored as neither the actual nor the converted name. This made it impossible to redirect a single expanded HTTP-type field (such as the response body) into the proxy request body.
 
+Body-parameter resolution is now a single shared rule on the core endpoint (`RoutineEndpoint.IsBodyParameter`) used by request handling **and** every code generator, so they no longer drift. This also fixes the **HTTP file** and **OpenAPI** generators, which previously left a `@body_parameter_name` field (e.g. `responseBody`) in the query string / query parameters instead of moving it to the request body.
+
 ### 3. TypeScript client generation for `@body_parameter_name`
 
 The generated TypeScript client was broken for an endpoint with `@body_parameter_name`:
@@ -53,4 +55,4 @@ The pattern "fetch with an HTTP Custom Type, then `@proxy` to an upstream" now w
 
 ## Tests
 
-`NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs` adds three cases (WireMock proxy target echoing the received URL / body): body redirect by converted name (`responseBody`), body redirect by expanded signature name (`_response_body`), and an oversized HTTP-type body field skipped from the proxy query string. `NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs` covers the generated client for `@body_parameter_name` endpoints: a `GET` case (no `?`-suffixed name, parameter excluded from the query, no `fetch` body on `GET`) and a `POST` HTTP-Custom-Type case targeted by the expanded name `_response_body` (body emitted as `request.responseBody`, excluded from the query). `OmitAutomaticParameters` is covered for each generator (TsClient: all-omitted no-arg function + mixed-params; HttpFiles and OpenAPI: query/body omission of HTTP Custom Type fields). Full suite green (2299).
+`NpgsqlRestTests/ProxyTests/ProxyHttpTypeProbeTest.cs` adds three cases (WireMock proxy target echoing the received URL / body): body redirect by converted name (`responseBody`), body redirect by expanded signature name (`_response_body`), and an oversized HTTP-type body field skipped from the proxy query string. `NpgsqlRestTests/TsClientTests/BodyParamGetTests.cs` covers the generated client for `@body_parameter_name` endpoints: a `GET` case (no `?`-suffixed name, parameter excluded from the query, no `fetch` body on `GET`) and a `POST` HTTP-Custom-Type case targeted by the expanded name `_response_body` (body emitted as `request.responseBody`, excluded from the query). The HTTP file and OpenAPI generators are covered for the same expanded-name body redirect (`BodyParamToBodyTests`). `OmitAutomaticParameters` is covered for each generator (TsClient: all-omitted no-arg function + mixed-params; HttpFiles and OpenAPI: query/body omission of HTTP Custom Type fields). Full suite green (2301).
diff --git a/plugins/NpgsqlRest.HttpFiles/HttpFile.cs b/plugins/NpgsqlRest.HttpFiles/HttpFile.cs
index e3ae7a69..2f65a61a 100644
--- a/plugins/NpgsqlRest.HttpFiles/HttpFile.cs
+++ b/plugins/NpgsqlRest.HttpFiles/HttpFile.cs
@@ -101,13 +101,9 @@ public void Handle(RoutineEndpoint endpoint)
                         }
 
                         // Skip body parameter
-                        if (endpoint.BodyParameterName is not null)
+                        if (endpoint.IsBodyParameter(p))
                         {
-                            if (string.Equals(p.ConvertedName, endpoint.BodyParameterName, StringComparison.Ordinal) ||
-                                string.Equals(p.ActualName, endpoint.BodyParameterName, StringComparison.Ordinal))
-                            {
-                                return false;
-                            }
+                            return false;
                         }
 
                         // Skip path parameters - they are already in the URL path
@@ -142,8 +138,7 @@ public void Handle(RoutineEndpoint endpoint)
             {
                 for(int i = 0; i < endpoint.Routine.Parameters.Length; i++)
                 {
-                    if (string.Equals(endpoint.Routine.Parameters[i].ConvertedName, endpoint.BodyParameterName, StringComparison.Ordinal) ||
-                        string.Equals(endpoint.Routine.Parameters[i].ActualName, endpoint.BodyParameterName, StringComparison.Ordinal))
+                    if (endpoint.IsBodyParameter(endpoint.Routine.Parameters[i]))
                     {
                         // A server-filled body parameter (e.g. an HTTP Custom Type field) is not sent by the client.
                         if (httpFileOptions.OmitAutomaticParameters && endpoint.OmitParameterFromGeneratedRequest(endpoint.Routine.Parameters[i]))
diff --git a/plugins/NpgsqlRest.OpenApi/OpenApi.cs b/plugins/NpgsqlRest.OpenApi/OpenApi.cs
index a0eacd86..67d0e449 100644
--- a/plugins/NpgsqlRest.OpenApi/OpenApi.cs
+++ b/plugins/NpgsqlRest.OpenApi/OpenApi.cs
@@ -256,9 +256,7 @@ public void Handle(RoutineEndpoint endpoint)
                     }
 
                     // Skip body parameter if it exists
-                    if (endpoint.BodyParameterName is not null &&
-                        (string.Equals(param.ConvertedName, endpoint.BodyParameterName, StringComparison.Ordinal) ||
-                         string.Equals(param.ActualName, endpoint.BodyParameterName, StringComparison.Ordinal)))
+                    if (endpoint.IsBodyParameter(param))
                     {
                         continue;
                     }
@@ -371,9 +369,7 @@ public void Handle(RoutineEndpoint endpoint)
         if (endpoint.BodyParameterName is not null && endpoint.RequestParamType == RequestParamType.QueryString)
         {
             var bodyParam = endpoint.Routine.Parameters
-                .FirstOrDefault(p =>
-                    string.Equals(p.ConvertedName, endpoint.BodyParameterName, StringComparison.Ordinal) ||
-                    string.Equals(p.ActualName, endpoint.BodyParameterName, StringComparison.Ordinal));
+                .FirstOrDefault(endpoint.IsBodyParameter);
 
             // A server-filled body parameter (e.g. an HTTP Custom Type field) is not part of the client contract.
             if (bodyParam is not null && openApiOptions.OmitAutomaticParameters && endpoint.OmitParameterFromGeneratedRequest(bodyParam))
diff --git a/plugins/NpgsqlRest.TsClient/TsClient.cs b/plugins/NpgsqlRest.TsClient/TsClient.cs
index f5d406fb..a8e05fa9 100644
--- a/plugins/NpgsqlRest.TsClient/TsClient.cs
+++ b/plugins/NpgsqlRest.TsClient/TsClient.cs
@@ -482,13 +482,8 @@ bool Handle(RoutineEndpoint endpoint)
                 requestParamCount++;
                 var nameSuffix = (descriptor.HasDefault || descriptor.CustomType is not null) ? "?" : "";
                 paramNames[i] = QuoteJavaScriptVariableName($"{parameter.ConvertedName}{nameSuffix}");
-                if (string.Equals(endpoint.BodyParameterName, parameter.ConvertedName, StringComparison.OrdinalIgnoreCase) ||
-                    string.Equals(endpoint.BodyParameterName, parameter.ActualName, StringComparison.OrdinalIgnoreCase) ||
-                    (parameter.ExpandedName is not null && string.Equals(endpoint.BodyParameterName, parameter.ExpandedName, StringComparison.OrdinalIgnoreCase)))
+                if (endpoint.IsBodyParameter(parameter))
                 {
-                    // Match the same three names the server-side body-parameter resolution accepts:
-                    // converted (responseBody), actual (the shared composite base, _response), and the
-                    // expanded per-field signature name (_response_body, via ExpandedName).
                     // Use the bare converted name for emission — NOT paramNames[i], which carries the TS
                     // optional "?" suffix (e.g. "responseBody?"). That suffix is only for the interface
                     // property declaration; it must not leak into the runtime property name used for the

From b82f9a27e3248047fb9ff6e6eb6b592015cbbfdd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Fri, 26 Jun 2026 14:53:29 +0200
Subject: [PATCH 11/25] bump version 3.18.2

---
 NpgsqlRestClient/NpgsqlRestClient.csproj                 | 2 +-
 npm/package.json                                         | 2 +-
 plugins/NpgsqlRest.HttpFiles/NpgsqlRest.HttpFiles.csproj | 8 ++++----
 plugins/NpgsqlRest.OpenApi/NpgsqlRest.OpenApi.csproj     | 8 ++++----
 plugins/NpgsqlRest.TsClient/NpgsqlRest.TsClient.csproj   | 8 ++++----
 version.txt                                              | 2 +-
 6 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/NpgsqlRestClient/NpgsqlRestClient.csproj b/NpgsqlRestClient/NpgsqlRestClient.csproj
index 6beaecf6..c291650e 100644
--- a/NpgsqlRestClient/NpgsqlRestClient.csproj
+++ b/NpgsqlRestClient/NpgsqlRestClient.csproj
@@ -22,7 +22,7 @@
     <PackageReference Include="Microsoft.Extensions.Caching.Hybrid" Version="10.7.0" />
     <PackageReference Include="Microsoft.Extensions.Caching.StackExchangeRedis" Version="10.0.9" />
     <PackageReference Include="SpreadCheetah" Version="1.27.0" />
-    <PackageReference Include="StackExchange.Redis" Version="3.0.0" />
+    <PackageReference Include="StackExchange.Redis" Version="3.0.7" />
   </ItemGroup>
   
   <ItemGroup>
diff --git a/npm/package.json b/npm/package.json
index 6fd5bf82..6cefc2e8 100644
--- a/npm/package.json
+++ b/npm/package.json
@@ -1,6 +1,6 @@
 {
   "name": "npgsqlrest",
-  "version": "3.18.1",
+  "version": "3.18.2",
   "description": "Automatic REST API for PostgreSQL Databases Client Build",
   "scripts": {
     "postinstall": "node postinstall.js",
diff --git a/plugins/NpgsqlRest.HttpFiles/NpgsqlRest.HttpFiles.csproj b/plugins/NpgsqlRest.HttpFiles/NpgsqlRest.HttpFiles.csproj
index 74b949e5..cd2dd03d 100644
--- a/plugins/NpgsqlRest.HttpFiles/NpgsqlRest.HttpFiles.csproj
+++ b/plugins/NpgsqlRest.HttpFiles/NpgsqlRest.HttpFiles.csproj
@@ -28,10 +28,10 @@
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
         <PackageReadmeFile>README.MD</PackageReadmeFile>
         <DocumentationFile>bin\$(Configuration)\$(AssemblyName).xml</DocumentationFile>
-        <Version>1.4.3</Version>
-        <AssemblyVersion>1.4.3</AssemblyVersion>
-        <FileVersion>1.4.3</FileVersion>
-        <PackageVersion>1.4.3</PackageVersion>
+        <Version>1.4.4</Version>
+        <AssemblyVersion>1.4.4</AssemblyVersion>
+        <FileVersion>1.4.4</FileVersion>
+        <PackageVersion>1.4.4</PackageVersion>
         <LangVersion>14</LangVersion>
     </PropertyGroup>
 
diff --git a/plugins/NpgsqlRest.OpenApi/NpgsqlRest.OpenApi.csproj b/plugins/NpgsqlRest.OpenApi/NpgsqlRest.OpenApi.csproj
index 9baebb2b..89dc4400 100644
--- a/plugins/NpgsqlRest.OpenApi/NpgsqlRest.OpenApi.csproj
+++ b/plugins/NpgsqlRest.OpenApi/NpgsqlRest.OpenApi.csproj
@@ -28,10 +28,10 @@
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
         <PackageReadmeFile>README.MD</PackageReadmeFile>
         <DocumentationFile>bin\$(Configuration)\$(AssemblyName).xml</DocumentationFile>
-        <Version>1.2.0</Version>
-        <AssemblyVersion>1.2.0</AssemblyVersion>
-        <FileVersion>1.2.0</FileVersion>
-        <PackageVersion>1.2.0</PackageVersion>
+        <Version>1.2.1</Version>
+        <AssemblyVersion>1.2.1</AssemblyVersion>
+        <FileVersion>1.2.1</FileVersion>
+        <PackageVersion>1.2.1</PackageVersion>
         <LangVersion>14</LangVersion>
     </PropertyGroup>
 
diff --git a/plugins/NpgsqlRest.TsClient/NpgsqlRest.TsClient.csproj b/plugins/NpgsqlRest.TsClient/NpgsqlRest.TsClient.csproj
index 3c0a3531..23486a98 100644
--- a/plugins/NpgsqlRest.TsClient/NpgsqlRest.TsClient.csproj
+++ b/plugins/NpgsqlRest.TsClient/NpgsqlRest.TsClient.csproj
@@ -26,10 +26,10 @@
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
         <PackageReadmeFile>README.MD</PackageReadmeFile>
         <DocumentationFile>bin\$(Configuration)\$(AssemblyName).xml</DocumentationFile>
-        <Version>1.36.1</Version>
-        <AssemblyVersion>1.36.1</AssemblyVersion>
-        <FileVersion>1.36.1</FileVersion>
-        <PackageVersion>1.36.1</PackageVersion>
+        <Version>1.36.2</Version>
+        <AssemblyVersion>1.36.2</AssemblyVersion>
+        <FileVersion>1.36.2</FileVersion>
+        <PackageVersion>1.36.2</PackageVersion>
         <LangVersion>14</LangVersion>
     </PropertyGroup>
 
diff --git a/version.txt b/version.txt
index 10724e0b..05d97541 100644
--- a/version.txt
+++ b/version.txt
@@ -1 +1 @@
-3.18.1
\ No newline at end of file
+3.18.2
\ No newline at end of file

From 6a0f03f830a521241d34b15a46bc0d2439f5d0b1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Tue, 30 Jun 2026 12:17:48 +0200
Subject: [PATCH 12/25] feat: SQL test runner (--test) [WIP], SqlFileSource
 SkipPattern, MinimalLevels Off
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SQL test runner (--test) — WIP, not yet in changelog (still stabilizing):
- Discovers *.test.sql, runs each on its own non-pooled connection, invokes
  endpoints in-process on the test's own connection/transaction, asserts via
  boolean SELECTs / DO blocks / `# @expect-status`. Captures responses into
  per-block pg_temp tables.
- Per-assertion reporting (each boolean SELECT / DO block / expect-status HTTP
  step is one test); console grouped per file, JUnit one <testcase> per assertion.
- Dedicated `NpgsqlRestTest` log channel (configurable TestRunner.LoggerName,
  leveled independently via Log:MinimalLevels): discovery/parsing at Debug,
  queries + HTTP calls at Verbose, notices by severity. Console report stays
  separate.
- Core (additive, inert when unused): NpgsqlRestOptions.AmbientConnectionAccessor
  + connection-selection branch; RoutineInvokeResult.Headers; endpoint
  notice-handler leak fix (named delegate detached in finally);
  NpgsqlRestLogger.LogConnectionNotice ILogger overload.
- 33 parser unit tests (NpgsqlRestTests/TestRunnerTests/ParserTests/).

Shippable in 3.19.0 (changelog/v3.19.0.md):
- SqlFileSource.SkipPattern (default *.test.sql) — exclude files from endpoint
  discovery; included iff matches FilePattern AND not SkipPattern.
- Log:MinimalLevels accepts "Off"/"None"/"Silent" to fully mute a logger
  (minimum level above Fatal); null/omitted still falls back to the default.

Config synced across appsettings.json, ConfigTemplate.cs, ConfigDefaults.cs,
ConfigSchemaGenerator.cs. Full suite green (2334) + 33 parser + 94 config tests.
---
 NpgsqlRest/NpgsqlRestEndpoint.cs              |  21 +-
 NpgsqlRest/NpgsqlRestLogger.cs                |  59 +-
 NpgsqlRest/Options/NpgsqlRestOptions.cs       |   8 +
 NpgsqlRest/RoutineInvoker.cs                  |   4 +-
 NpgsqlRestClient/App.cs                       |  10 +-
 NpgsqlRestClient/Builder.cs                   | 127 +++-
 NpgsqlRestClient/Config.cs                    |   2 +-
 NpgsqlRestClient/ConfigDefaults.cs            |  34 +
 NpgsqlRestClient/ConfigSchemaGenerator.cs     |  18 +-
 NpgsqlRestClient/ConfigTemplate.cs            |  87 ++-
 NpgsqlRestClient/Out.cs                       |  17 +
 NpgsqlRestClient/Program.cs                   |  33 +
 .../Testing/HttpFileRequestParser.cs          | 150 ++++
 NpgsqlRestClient/Testing/SqlTestFileParser.cs | 229 ++++++
 NpgsqlRestClient/Testing/TestRunner.cs        | 708 ++++++++++++++++++
 NpgsqlRestClient/Testing/TestRunnerOptions.cs |  83 ++
 NpgsqlRestClient/Testing/TestStep.cs          |  75 ++
 NpgsqlRestClient/appsettings.json             |  85 +++
 .../ParserTests/HttpFileRequestParserTests.cs | 129 ++++
 .../ParserTests/SqlTestFileParserTests.cs     | 131 ++++
 changelog/v3.19.0.md                          |  46 ++
 .../NpgsqlRest.SqlFileSource/SqlFileSource.cs |   8 +-
 .../SqlFileSourceOptions.cs                   |   7 +
 23 files changed, 2040 insertions(+), 31 deletions(-)
 create mode 100644 NpgsqlRestClient/Testing/HttpFileRequestParser.cs
 create mode 100644 NpgsqlRestClient/Testing/SqlTestFileParser.cs
 create mode 100644 NpgsqlRestClient/Testing/TestRunner.cs
 create mode 100644 NpgsqlRestClient/Testing/TestRunnerOptions.cs
 create mode 100644 NpgsqlRestClient/Testing/TestStep.cs
 create mode 100644 NpgsqlRestTests/TestRunnerTests/ParserTests/HttpFileRequestParserTests.cs
 create mode 100644 NpgsqlRestTests/TestRunnerTests/ParserTests/SqlTestFileParserTests.cs
 create mode 100644 changelog/v3.19.0.md

diff --git a/NpgsqlRest/NpgsqlRestEndpoint.cs b/NpgsqlRest/NpgsqlRestEndpoint.cs
index dfd84d93..3aa0250b 100644
--- a/NpgsqlRest/NpgsqlRestEndpoint.cs
+++ b/NpgsqlRest/NpgsqlRestEndpoint.cs
@@ -71,6 +71,9 @@ public async Task InvokeAsync(HttpContext context, IServiceProvider serviceProvi
         string? commandText = null;
         bool shouldDispose = true;
         bool shouldCommit = true;
+        // Per-request connection notice handler; detached in the finally so it never accumulates on a
+        // reused connection (e.g. ServiceProviderMode=NpgsqlConnection / the SQL test runner's ambient connection).
+        NoticeEventHandler? noticeHandler = null;
         // Held (when non-null) for the streaming records/sets cache path; released in the outer finally.
         SemaphoreSlim? recordCacheGate = null;
         IUploadHandler? uploadHandler = null;
@@ -102,7 +105,14 @@ public async Task InvokeAsync(HttpContext context, IServiceProvider serviceProvi
             : PipeWriter.Create(context.Response.Body);
         try
         {
-            if (endpoint.ConnectionName is not null)
+            if (Options.AmbientConnectionAccessor?.Invoke() is { } ambientConnection)
+            {
+                // Ambient connection override (SQL test runner): run on the caller's already-open
+                // connection/transaction and never dispose it. The caller owns the connection lifecycle.
+                connection = ambientConnection;
+                shouldDispose = false;
+            }
+            else if (endpoint.ConnectionName is not null)
             {
                 // First check if there's a data source for this connection name (for multi-host support)
                 if (Options.DataSources?.TryGetValue(endpoint.ConnectionName, out var namedDataSource) is true)
@@ -171,7 +181,7 @@ public async Task InvokeAsync(HttpContext context, IServiceProvider serviceProvi
                 || noticeWarnEnabled)
             {
                 var currentEndpointCaptured = endpoint;
-                connection.Notice += (sender, args) =>
+                noticeHandler = (sender, args) =>
                 {
                     if (Options.LogConnectionNoticeEvents && Logger != null)
                     {
@@ -192,6 +202,7 @@ public async Task InvokeAsync(HttpContext context, IServiceProvider serviceProvi
                         Logger!.UnboundSseRaise(args.Notice.Severity, currentEndpointCaptured.Path);
                     }
                 };
+                connection.Notice += noticeHandler;
             }
             
             if (Options.AuthenticationOptions.BasicAuth.Enabled is true || endpoint.BasicAuth?.Enabled is true)
@@ -3337,6 +3348,12 @@ await Proxy.ProxyRequestHandler.WriteResponseAsync(
                     }
                 }
             }
+            // Detach the per-request notice handler so it can't accumulate (and re-log) on a reused
+            // connection that this request did not dispose.
+            if (connection is not null && noticeHandler is not null)
+            {
+                connection.Notice -= noticeHandler;
+            }
             if (connection is not null && shouldDispose is true)
             {
                 await connection.DisposeAsync();
diff --git a/NpgsqlRest/NpgsqlRestLogger.cs b/NpgsqlRest/NpgsqlRestLogger.cs
index bc9dde74..393d9809 100644
--- a/NpgsqlRest/NpgsqlRestLogger.cs
+++ b/NpgsqlRest/NpgsqlRestLogger.cs
@@ -17,27 +17,27 @@ public static class NpgsqlRestLogger
     private static readonly Action<ILogger, string?, string, Exception?> __LogTraceCallback =
         LoggerMessage.Define<string?, string>(LogLevel.Trace, 4, LogPattern, LogDefineOptions);
 
-    private static void LogInformation(string? where, string message)
+    private static void LogInformation(ILogger logger, string? where, string message)
     {
-        if (Logger?.IsEnabled(LogLevel.Information) is true)
+        if (logger.IsEnabled(LogLevel.Information))
         {
-            __LogInformationCallback(Logger, where, message, null);
+            __LogInformationCallback(logger, where, message, null);
         }
     }
 
-    private static void LogWarning(string? where, string message)
+    private static void LogWarning(ILogger logger, string? where, string message)
     {
-        if (Logger?.IsEnabled(LogLevel.Warning) is true)
+        if (logger.IsEnabled(LogLevel.Warning))
         {
-            __LogWarningCallback(Logger, where, message, null);
+            __LogWarningCallback(logger, where, message, null);
         }
     }
 
-    private static void LogTrace(string? where, string message)
+    private static void LogTrace(ILogger logger, string? where, string message)
     {
-        if (Logger?.IsEnabled(LogLevel.Trace) is true)
+        if (logger.IsEnabled(LogLevel.Trace))
         {
-            __LogTraceCallback(Logger, where, message, null);
+            __LogTraceCallback(logger, where, message, null);
         }
     }
 
@@ -52,55 +52,76 @@ public static void LogEndpoint(RoutineEndpoint endpoint, string parameters, stri
 #pragma warning disable IDE0079 // Remove unnecessary suppression
     [System.Diagnostics.CodeAnalysis.SuppressMessage("Usage", "CA2254:Template should be a static expression", Justification = "<Pending>")]
 #pragma warning restore IDE0079 // Remove unnecessary suppression
-    public static void LogConnectionNotice(PostgresNotice notice, PostgresConnectionNoticeLoggingMode mode)
+    public static void LogConnectionNotice(PostgresNotice notice, PostgresConnectionNoticeLoggingMode mode, string? context = null)
     {
         if (Logger is null)
         {
             return;
         }
+        LogConnectionNotice(Logger, notice, mode, context);
+    }
+
+    /// <summary>
+    /// Logs a connection notice through the supplied <paramref name="logger"/> rather than the static
+    /// <see cref="Logger"/>. Used by the SQL test runner so notices route through its own log channel
+    /// (e.g. "NpgsqlRestTest"). The log level still follows the notice severity (info/notice => Information,
+    /// warning => Warning, otherwise Trace/Verbose) and the format is identical to the normal-app path.
+    /// </summary>
+#pragma warning disable IDE0079 // Remove unnecessary suppression
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Usage", "CA2254:Template should be a static expression", Justification = "<Pending>")]
+#pragma warning restore IDE0079 // Remove unnecessary suppression
+    public static void LogConnectionNotice(ILogger logger, PostgresNotice notice, PostgresConnectionNoticeLoggingMode mode, string? context = null)
+    {
+        if (logger is null)
+        {
+            return;
+        }
+        // Optional caller context (e.g. the SQL test runner's current test file) prefixed to the location,
+        // so notices can be attributed to their source. Null in normal operation → format unchanged.
+        string? tag = string.IsNullOrEmpty(context) ? null : $"[{context}] ";
         if (notice.IsInfo() || notice.IsNotice())
         {
             if (mode == PostgresConnectionNoticeLoggingMode.MessageOnly)
             {
-                Logger.LogInformation(notice.MessageText);
+                logger.LogInformation(string.Concat(tag, notice.MessageText));
             }
             else if (mode == PostgresConnectionNoticeLoggingMode.FirstStackFrameAndMessage)
             {
-                LogInformation(notice?.Where?.Split('\n').LastOrDefault() ?? "", notice?.MessageText!);
+                LogInformation(logger, string.Concat(tag, notice?.Where?.Split('\n').LastOrDefault() ?? ""), notice?.MessageText!);
             }
             else if (mode == PostgresConnectionNoticeLoggingMode.FullStackAndMessage)
             {
-                LogInformation(notice?.Where, notice?.MessageText!);
+                LogInformation(logger, string.Concat(tag, notice?.Where), notice?.MessageText!);
             }
         }
         else if (notice.IsWarning())
         {
             if (mode == PostgresConnectionNoticeLoggingMode.MessageOnly)
             {
-                Logger.LogWarning(notice.MessageText);
+                logger.LogWarning(string.Concat(tag, notice.MessageText));
             }
             else if (mode == PostgresConnectionNoticeLoggingMode.FirstStackFrameAndMessage)
             {
-                LogWarning(notice?.Where?.Split('\n').Last() ?? "", notice?.MessageText!);
+                LogWarning(logger, string.Concat(tag, notice?.Where?.Split('\n').Last() ?? ""), notice?.MessageText!);
             }
             else if (mode == PostgresConnectionNoticeLoggingMode.FullStackAndMessage)
             {
-                LogWarning(notice?.Where, notice?.MessageText!);
+                LogWarning(logger, string.Concat(tag, notice?.Where), notice?.MessageText!);
             }
         }
         else
         {
             if (mode == PostgresConnectionNoticeLoggingMode.MessageOnly)
             {
-                Logger.LogTrace(notice.MessageText);
+                logger.LogTrace(string.Concat(tag, notice.MessageText));
             }
             else if (mode == PostgresConnectionNoticeLoggingMode.FirstStackFrameAndMessage)
             {
-                LogTrace(notice?.Where?.Split('\n').Last() ?? "", notice?.MessageText!);
+                LogTrace(logger, string.Concat(tag, notice?.Where?.Split('\n').Last() ?? ""), notice?.MessageText!);
             }
             else if (mode == PostgresConnectionNoticeLoggingMode.FullStackAndMessage)
             {
-                LogTrace(notice?.Where, notice?.MessageText!);
+                LogTrace(logger, string.Concat(tag, notice?.Where), notice?.MessageText!);
             }
         }
     }
diff --git a/NpgsqlRest/Options/NpgsqlRestOptions.cs b/NpgsqlRest/Options/NpgsqlRestOptions.cs
index 719b1807..1c87d19b 100644
--- a/NpgsqlRest/Options/NpgsqlRestOptions.cs
+++ b/NpgsqlRest/Options/NpgsqlRestOptions.cs
@@ -150,6 +150,14 @@ public NpgsqlRestOptions(NpgsqlDataSource dataSource)
     /// </summary>
     public ServiceProviderObject ServiceProviderMode { get; set; } = ServiceProviderObject.None;
 
+    /// <summary>
+    /// When set and the accessor returns a non-null connection, the endpoint executes on that ambient
+    /// connection (and does not dispose it) instead of opening its own. Null by default — zero behavioral
+    /// change for normal operation. Used by the SQL test runner to run an endpoint on the test's own
+    /// open connection/transaction (connection affinity).
+    /// </summary>
+    public Func<Npgsql.NpgsqlConnection?>? AmbientConnectionAccessor { get; set; } = null;
+
     /// <summary>
     /// Callback function that is executed just after the new endpoint is created. Set the RoutineEndpoint to null to disable endpoint.
     /// </summary>
diff --git a/NpgsqlRest/RoutineInvoker.cs b/NpgsqlRest/RoutineInvoker.cs
index 86938da0..142e3aee 100644
--- a/NpgsqlRest/RoutineInvoker.cs
+++ b/NpgsqlRest/RoutineInvoker.cs
@@ -6,7 +6,7 @@ namespace NpgsqlRest;
 /// <summary>
 /// Result of a programmatic routine invocation via <see cref="RoutineInvoker"/>.
 /// </summary>
-public readonly record struct RoutineInvokeResult(int StatusCode, string? Body, string? ContentType, bool IsSuccess);
+public readonly record struct RoutineInvokeResult(int StatusCode, string? Body, string? ContentType, string? Headers, bool IsSuccess);
 
 /// <summary>
 /// Public entry point for invoking an NpgsqlRest endpoint in-process (no network hop), running the
@@ -43,6 +43,6 @@ public static async Task<RoutineInvokeResult> InvokeAsync(
         var response = await InternalRequestHandler.ExecuteAsync(
             method, path, headerDict, body, contentType, cancellationToken, user);
 
-        return new RoutineInvokeResult(response.StatusCode, response.Body, response.ContentType, response.IsSuccess);
+        return new RoutineInvokeResult(response.StatusCode, response.Body, response.ContentType, response.Headers, response.IsSuccess);
     }
 }
diff --git a/NpgsqlRestClient/App.cs b/NpgsqlRestClient/App.cs
index 9825f720..dd55f2b6 100644
--- a/NpgsqlRestClient/App.cs
+++ b/NpgsqlRestClient/App.cs
@@ -463,8 +463,10 @@ public string CreateUrl(Routine routine, NpgsqlRestOptions options) =>
     public List<IEndpointCreateHandler> CreateCodeGenHandlers(string connectionString, string[] args)
     {
         List<IEndpointCreateHandler> handlers = new(3);
-        if (args.Any(a => string.Equals(a, "--endpoints", StringComparison.OrdinalIgnoreCase)))
+        if (args.Any(a => string.Equals(a, "--endpoints", StringComparison.OrdinalIgnoreCase)
+            || string.Equals(a, "--test", StringComparison.OrdinalIgnoreCase)))
         {
+            // --test also captures endpoints so the runner can pre-check kinds (SSE/upload/outbound).
             handlers.Add(new EndpointCapture());
         }
         var httpFilecfg = _config.NpgsqlRestCfg.GetSection("HttpFileOptions");
@@ -661,6 +663,12 @@ public List<IEndpointSource> CreateEndpointSources()
                     UnnamedSingleColumnSet = _config.GetConfigBool("UnnamedSingleColumnSet", sqlFileSourceCfg, true),
                     SkipNonQueryCommands = _config.GetConfigBool("SkipNonQueryCommands", sqlFileSourceCfg, true),
                 };
+                // Absent => default "*.test.sql"; explicit empty string disables the exclusion.
+                var skipPattern = _config.GetConfigStr("SkipPattern", sqlFileSourceCfg);
+                if (sqlFileSourceCfg.GetSection("SkipPattern").Exists())
+                {
+                    opts.SkipPattern = skipPattern ?? "";
+                }
                 if (_config.GetConfigStr("CommentsMode", sqlFileSourceCfg) is not null)
                 {
                     opts.CommentsMode = _config.GetConfigEnum<CommentsMode>("CommentsMode", sqlFileSourceCfg);
diff --git a/NpgsqlRestClient/Builder.cs b/NpgsqlRestClient/Builder.cs
index 4610183a..d6ce259a 100644
--- a/NpgsqlRestClient/Builder.cs
+++ b/NpgsqlRestClient/Builder.cs
@@ -15,9 +15,11 @@
 using Microsoft.Extensions.Caching.Hybrid;
 using Microsoft.Extensions.Primitives;
 using Microsoft.Net.Http.Headers;
+using Microsoft.Extensions.Configuration;
 using Npgsql;
 using NpgsqlRest;
 using NpgsqlRestClient.Fido2;
+using NpgsqlRestClient.Testing;
 using Serilog;
 using Serilog.Extensions.Logging;
 using Serilog.Sinks.OpenTelemetry;
@@ -39,6 +41,8 @@ public Builder(Config config)
     
     public Microsoft.Extensions.Logging.ILogger? Logger { get; private set; } = null;
     public Microsoft.Extensions.Logging.ILogger? ClientLogger { get; private set; } = null;
+    /// <summary>Independent log channel for the SQL test runner (<c>--test</c>); name from TestRunner:LoggerName (default "NpgsqlRestTest").</summary>
+    public Microsoft.Extensions.Logging.ILogger? TestLogger { get; private set; } = null;
     public bool UseHttpsRedirection { get; private set; } = false;
     public bool UseHsts { get; private set; } = false;
     public BearerTokenConfig? BearerTokenConfig { get; private set; } = null;
@@ -156,11 +160,28 @@ logToConsole is true ||
             var appName = _config.GetConfigStr("ApplicationName", _config.Cfg);
             var envName = _config.GetConfigStr("EnvironmentName", _config.Cfg) ?? "Production";
             string clientLoggerName = string.IsNullOrEmpty(appName) ? "NpgsqlRestClient" : appName;
+            // SQL test runner's own log channel (see TestRunner:LoggerName). A non-dotted sibling name so it's
+            // controlled independently of "NpgsqlRest" via its own MinimalLevels entry.
+            string testLoggerName = _config.GetConfigStr("LoggerName", _config.Cfg.GetSection("TestRunner")) ?? "NpgsqlRestTest";
+            bool testLoggerAdded = false;
 
             foreach (var level in logCfg?.GetSection("MinimalLevels")?.GetChildren() ?? [])
             {
                 var key = level.Key;
-                var value = _config.GetEnum<Serilog.Events.LogEventLevel?>(level.Value);
+                Serilog.Events.LogEventLevel? value;
+                if (string.IsNullOrWhiteSpace(level.Value) is false &&
+                    (string.Equals(level.Value, "Off", StringComparison.OrdinalIgnoreCase) ||
+                     string.Equals(level.Value, "None", StringComparison.OrdinalIgnoreCase) ||
+                     string.Equals(level.Value, "Silent", StringComparison.OrdinalIgnoreCase)))
+                {
+                    // Mute the source entirely: a minimum above Fatal means no event (max level Fatal) passes.
+                    // null/unrecognized still falls through to GetEnum => null => the source keeps its default.
+                    value = (Serilog.Events.LogEventLevel)((int)Serilog.Events.LogEventLevel.Fatal + 1);
+                }
+                else
+                {
+                    value = _config.GetEnum<Serilog.Events.LogEventLevel?>(level.Value);
+                }
                 if (value is not null && key is not null)
                 {
                     if (string.Equals(key, "NpgsqlRest", StringComparison.OrdinalIgnoreCase))
@@ -183,6 +204,11 @@ logToConsole is true ||
                         loggerConfig.MinimumLevel.Override(key, value.Value);
                         microsoftAdded = true;
                     }
+                    else if (string.Equals(key, testLoggerName, StringComparison.OrdinalIgnoreCase))
+                    {
+                        loggerConfig.MinimumLevel.Override(testLoggerName, value.Value);
+                        testLoggerAdded = true;
+                    }
                     else
                     {
                         loggerConfig.MinimumLevel.Override(key, value.Value);
@@ -205,6 +231,16 @@ logToConsole is true ||
             {
                 loggerConfig.MinimumLevel.Override("Microsoft", Serilog.Events.LogEventLevel.Warning);
             }
+            // Default the test-runner channel to Information when not in MinimalLevels (skip if its name
+            // collides with a reserved logger, which already has its own default above).
+            if (testLoggerAdded is false &&
+                string.Equals(testLoggerName, "NpgsqlRest", StringComparison.OrdinalIgnoreCase) is false &&
+                string.Equals(testLoggerName, clientLoggerName, StringComparison.OrdinalIgnoreCase) is false &&
+                string.Equals(testLoggerName, "System", StringComparison.OrdinalIgnoreCase) is false &&
+                string.Equals(testLoggerName, "Microsoft", StringComparison.OrdinalIgnoreCase) is false)
+            {
+                loggerConfig.MinimumLevel.Override(testLoggerName, Serilog.Events.LogEventLevel.Information);
+            }
 
             string outputTemplate = _config.GetConfigStr("OutputTemplate", logCfg) ?? 
                 "[{Timestamp:HH:mm:ss.fff} {Level:u3}] {Message:lj} [{SourceContext}]{NewLine}{Exception}";
@@ -286,6 +322,9 @@ logToConsole is true ||
             Logger = serilogFactory.CreateLogger("NpgsqlRest");
             // Client application logger - uses ApplicationName or "NpgsqlRestClient"
             ClientLogger = serilogFactory.CreateLogger(clientLoggerName);
+            // Test runner logger - independent channel so `--test` activity (queries=Verbose, parsing=Debug,
+            // notices=by severity) is leveled separately from the app via Log:MinimalLevels.
+            TestLogger = serilogFactory.CreateLogger(testLoggerName);
 
             Instance.Host.UseSerilog(serilog);
 
@@ -2963,6 +3002,92 @@ public Dictionary<string, NpgsqlDataSource> BuildDataSources(string mainConnecti
         return result;
     }
 
+    /// <summary>
+    /// Builds the SQL test-runner options from the top-level "TestRunner" config section.
+    /// </summary>
+    public TestRunnerOptions BuildTestRunnerOptions()
+    {
+        var opt = new TestRunnerOptions();
+        var section = _config.Cfg.GetSection("TestRunner");
+        if (section.Exists() is false) return opt;
+
+        opt.FilePattern = _config.GetConfigStr("FilePattern", section) ?? "";
+        opt.MaxParallelism = _config.GetConfigInt("MaxParallelism", section) ?? 0;
+        opt.FailFast = _config.GetConfigBool("FailFast", section, false);
+        opt.PerTestTimeout = ParseTestTimeout(_config.GetConfigStr("PerTestTimeout", section), TimeSpan.FromSeconds(30));
+        opt.JUnitOutput = _config.GetConfigStr("JUnitOutput", section);
+        opt.Keep = _config.GetConfigBool("Keep", section, false);
+        opt.Verbose = _config.GetConfigBool("Verbose", section, false);
+        opt.AllowEmpty = _config.GetConfigBool("AllowEmpty", section, false);
+
+        var rt = section.GetSection("ResponseTempTable");
+        if (rt.Exists())
+        {
+            opt.ResponseTempTable.Name = _config.GetConfigStr("Name", rt) ?? opt.ResponseTempTable.Name;
+            opt.ResponseTempTable.MultiNamePattern = _config.GetConfigStr("MultiNamePattern", rt) ?? opt.ResponseTempTable.MultiNamePattern;
+            var cols = rt.GetSection("Columns");
+            if (cols.Exists())
+            {
+                var c = opt.ResponseTempTable.Columns;
+                c.Status = ReadColumnName(cols, "Status", c.Status);
+                c.Body = ReadColumnName(cols, "Body", c.Body);
+                c.ContentType = ReadColumnName(cols, "ContentType", c.ContentType);
+                c.Headers = ReadColumnName(cols, "Headers", c.Headers);
+                c.IsSuccess = ReadColumnName(cols, "IsSuccess", c.IsSuccess);
+            }
+        }
+
+        opt.Setup = ReadTestSteps(section.GetSection("Setup"));
+        opt.Teardown = ReadTestSteps(section.GetSection("Teardown"));
+        return opt;
+
+        // Absent key => keep default name; explicit empty string => omit the column.
+        string? ReadColumnName(IConfigurationSection cols, string key, string? def)
+        {
+            var s = cols.GetSection(key);
+            if (s.Exists() is false) return def;
+            return string.IsNullOrWhiteSpace(s.Value) ? null : s.Value;
+        }
+
+        List<TestSetupStep> ReadTestSteps(IConfigurationSection stepsSection)
+        {
+            var list = new List<TestSetupStep>();
+            if (stepsSection.Exists() is false) return list;
+            foreach (var child in stepsSection.GetChildren())
+            {
+                var step = new TestSetupStep
+                {
+                    Sql = _config.GetConfigStr("Sql", child),
+                    SqlFile = _config.GetConfigStr("SqlFile", child),
+                    Command = _config.GetConfigStr("Command", child),
+                    WorkingDirectory = _config.GetConfigStr("WorkingDirectory", child),
+                };
+                if (step.Sql is not null || step.SqlFile is not null || step.Command is not null)
+                {
+                    list.Add(step);
+                }
+            }
+            return list;
+        }
+    }
+
+    private static TimeSpan ParseTestTimeout(string? raw, TimeSpan def)
+    {
+        if (string.IsNullOrWhiteSpace(raw)) return def;
+        raw = raw.Trim();
+        if (int.TryParse(raw, out var secs)) return TimeSpan.FromSeconds(secs);
+        if (raw.Length > 1 && int.TryParse(raw[..^1], out var n))
+        {
+            switch (char.ToLowerInvariant(raw[^1]))
+            {
+                case 's': return TimeSpan.FromSeconds(n);
+                case 'm': return TimeSpan.FromMinutes(n);
+                case 'h': return TimeSpan.FromHours(n);
+            }
+        }
+        return TimeSpan.TryParse(raw, out var ts) ? ts : def;
+    }
+
     /// <summary>
     /// Builds the main data source (handles both single-host and multi-host).
     /// </summary>
diff --git a/NpgsqlRestClient/Config.cs b/NpgsqlRestClient/Config.cs
index e6badbaa..55b257e0 100644
--- a/NpgsqlRestClient/Config.cs
+++ b/NpgsqlRestClient/Config.cs
@@ -1117,7 +1117,7 @@ private static void LoadEnvFile(string path)
                 {
                     commandLineArgs.Add(arg);
                 }
-                else if (lower is "--json" or "--validate" or "--endpoints")
+                else if (lower is "--json" or "--validate" or "--endpoints" or "--test")
                 {
                     // Known flags handled by Program.cs, skip silently
                 }
diff --git a/NpgsqlRestClient/ConfigDefaults.cs b/NpgsqlRestClient/ConfigDefaults.cs
index 5282735d..93e5ab26 100644
--- a/NpgsqlRestClient/ConfigDefaults.cs
+++ b/NpgsqlRestClient/ConfigDefaults.cs
@@ -173,6 +173,7 @@ public static JsonObject GetDefaults()
             ["ForwardedHeaders"] = GetForwardedHeadersDefaults(),
             ["HealthChecks"] = GetHealthChecksDefaults(),
             ["Stats"] = GetStatsDefaults(),
+            ["TestRunner"] = GetTestRunnerDefaults(),
             ["CommandRetryOptions"] = GetCommandRetryOptionsDefaults(),
             ["CacheOptions"] = GetCacheOptionsDefaults(),
             ["ValidationOptions"] = GetValidationOptionsDefaults(),
@@ -359,6 +360,7 @@ private static JsonObject GetLogDefaults()
             {
                 ["NpgsqlRest"] = "Information",
                 ["NpgsqlRestClient"] = "Information",
+                ["NpgsqlRestTest"] = "Information",
                 ["System"] = "Warning",
                 ["Microsoft"] = "Warning"
             },
@@ -1082,6 +1084,7 @@ private static JsonObject GetSqlFileSourceDefaults()
         {
             ["Enabled"] = false,
             ["FilePattern"] = "",
+            ["SkipPattern"] = "*.test.sql",
             ["CommentsMode"] = "OnlyAnnotated",
             ["CommentScope"] = "All",
             ["ErrorMode"] = "Exit",
@@ -1093,6 +1096,37 @@ private static JsonObject GetSqlFileSourceDefaults()
         };
     }
 
+    private static JsonObject GetTestRunnerDefaults()
+    {
+        return new JsonObject
+        {
+            ["FilePattern"] = "",
+            ["MaxParallelism"] = 0,
+            ["FailFast"] = false,
+            ["PerTestTimeout"] = "30s",
+            ["JUnitOutput"] = null,
+            ["Keep"] = false,
+            ["Verbose"] = false,
+            ["AllowEmpty"] = false,
+            ["LoggerName"] = "NpgsqlRestTest",
+            ["ResponseTempTable"] = new JsonObject
+            {
+                ["Name"] = "_response",
+                ["MultiNamePattern"] = "_response_{n}",
+                ["Columns"] = new JsonObject
+                {
+                    ["Status"] = "status",
+                    ["Body"] = "body",
+                    ["ContentType"] = "content_type",
+                    ["Headers"] = "headers",
+                    ["IsSuccess"] = "is_success"
+                }
+            },
+            ["Setup"] = new JsonArray(),
+            ["Teardown"] = new JsonArray()
+        };
+    }
+
     private static JsonObject GetTableFormatOptionsDefaults()
     {
         return new JsonObject
diff --git a/NpgsqlRestClient/ConfigSchemaGenerator.cs b/NpgsqlRestClient/ConfigSchemaGenerator.cs
index 6e3ba10f..e84405cb 100644
--- a/NpgsqlRestClient/ConfigSchemaGenerator.cs
+++ b/NpgsqlRestClient/ConfigSchemaGenerator.cs
@@ -158,7 +158,7 @@ public static partial class ConfigSchemaGenerator
         ["Auth:PasskeyAuth:ClientAnalyticsIpKey"] = "The JSON key name used to add the client's IP address to the analytics data server-side.\nSet to null or empty string to disable IP address collection.",
         ["Auth:PasskeyAuth:StatusColumnName"] = "Column name configuration for database responses",
         ["Log"] = "Serilog settings",
-        ["Log:MinimalLevels"] = "See https://github.com/serilog/serilog/wiki/Configuration-Basics#minimum-level\nVerbose, Debug, Information, Warning, Error, Fatal.\nNote: NpgsqlRest logger applies to main application logger, which will, by default have the name defined in the ApplicationName setting.",
+        ["Log:MinimalLevels"] = "See https://github.com/serilog/serilog/wiki/Configuration-Basics#minimum-level\nVerbose, Debug, Information, Warning, Error, Fatal.\nSet a level to \"Off\" (aliases \"None\"/\"Silent\") to mute that logger entirely; use null (or omit it) to fall back to its built-in default.\nNote: NpgsqlRest logger applies to main application logger, which will, by default have the name defined in the ApplicationName setting.\nNpgsqlRestTest is the SQL test runner (--test) channel (see TestRunner:LoggerName): discovery/parsing at Debug, each query and HTTP call at Verbose, notices by severity.",
         ["Log:ToConsole"] = "Enable logging to console output.",
         ["Log:ConsoleMinimumLevel"] = "Minimum log level for console output: Verbose, Debug, Information, Warning, Error, Fatal.",
         ["Log:ToFile"] = "Enable logging to file system.",
@@ -246,6 +246,21 @@ public static partial class ConfigSchemaGenerator
         ["Stats:TablesStatsPath"] = "Path for table statistics.\nReturns data from pg_stat_user_tables including tuple counts, sizes, scan counts, and vacuum info.",
         ["Stats:IndexesStatsPath"] = "Path for index statistics.\nReturns data from pg_stat_user_indexes including scan counts and index definitions.",
         ["Stats:ActivityPath"] = "Path for current database activity.\nReturns data from pg_stat_activity showing active sessions, queries, and wait events.\nSecurity Consideration: Shows currently running queries which may contain sensitive data.",
+        ["TestRunner"] = "SQL test runner. Invoked with the `--test` command-line flag (otherwise inert).\nDiscovers *.test.sql files, runs each in an isolated non-pooled connection, can invoke endpoints in-process from an embedded `/* GET /path */` block (response captured into a temp table), and asserts via boolean-returning SELECTs or `do $$ ... assert ... $$;` blocks.\nExit codes: 0 pass, 1 failures, 2 errors, 3 config/runner error, 4 no tests found.",
+        ["TestRunner:FilePattern"] = "Glob (same engine as SqlFileSource) selecting *.test.sql files. Empty disables discovery.\nCo-located convention: app.sql (endpoint) next to app.test.sql (test).",
+        ["TestRunner:MaxParallelism"] = "Max test files run concurrently. 0 => processor count. Each test uses its own non-pooled connection.",
+        ["TestRunner:FailFast"] = "Stop scheduling new tests after the first failure/error (in-flight tests still finish).",
+        ["TestRunner:PerTestTimeout"] = "Per-test timeout. Accepts \"30s\", \"5m\", \"1h\", a plain number of seconds, or \"hh:mm:ss\". 0 disables.",
+        ["TestRunner:JUnitOutput"] = "Optional path to also write a JUnit XML report (console output is always printed).",
+        ["TestRunner:Keep"] = "Skip Teardown so a failed run's state can be inspected.",
+        ["TestRunner:Verbose"] = "Show captured `raise notice` output for all tests, not just failed/errored ones.",
+        ["TestRunner:AllowEmpty"] = "Treat \"no tests discovered\" as success (exit 0) instead of exit 4.",
+        ["TestRunner:LoggerName"] = "SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels (defaults to Information).\nDiscovery/parsing log at Debug, each query and HTTP invocation at Verbose, `raise notice` by severity. The console PASS/FAIL report is separate.",
+        ["TestRunner:ResponseTempTable:Name"] = "Temp table name used when a test file has exactly ONE HTTP block.\nEach HTTP block gets its own fresh temp table (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified. Per-block override: `# @response <name>`.",
+        ["TestRunner:ResponseTempTable:MultiNamePattern"] = "Temp table name pattern used when a test file has 2+ HTTP blocks.\n{n} is the 1-based block ordinal, e.g. \"_response_{n}\" => _response_1, _response_2, …",
+        ["TestRunner:ResponseTempTable:Columns"] = "Maps each response component to a column name. A null or empty name omits that column.",
+        ["TestRunner:Setup"] = "Run-once setup, BEFORE endpoint discovery. Command steps run first (provision infra), then SqlFile/Sql steps (migrations/seed) — declared order preserved within each group.\nEach entry: { \"Command\": \"...\", \"WorkingDirectory\": \"...\" } | { \"SqlFile\": \"...\" } | { \"Sql\": \"...\" }.",
+        ["TestRunner:Teardown"] = "Run-once teardown, ALWAYS (best-effort), reverse order: SqlFile/Sql first, then Command (e.g. docker down). The `Keep` option skips it.",
         ["CommandRetryOptions"] = "Command retry strategies and options for client and middleware commands.",
         ["CommandRetryOptions:Strategies:default:RetrySequenceSeconds"] = "Retry sequence in seconds. Accepts decimal numbers (0.25 is quarter of a second). The length of the array determines the maximum number of retries.",
         ["CommandRetryOptions:Strategies:default:ErrorCodes"] = "Error codes that will trigger a retry when executing a command. See https://www.postgresql.org/docs/current/errcodes-appendix.html",
@@ -518,6 +533,7 @@ public static partial class ConfigSchemaGenerator
         ["NpgsqlRest:SqlFileSource"] = "SQL file source for generating REST API endpoints from .sql files.",
         ["NpgsqlRest:SqlFileSource:Enabled"] = "Enable or disable SQL file source endpoints. Default is false.",
         ["NpgsqlRest:SqlFileSource:FilePattern"] = "Glob pattern for SQL files, e.g. \"sql/**/*.sql\", \"queries/*.sql\".\nSupports * (any chars), ** (recursive, any including /), ? (single char).\nEmpty string disables the feature.",
+        ["NpgsqlRest:SqlFileSource:SkipPattern"] = "Glob (same semantics as FilePattern) for files to EXCLUDE from endpoint discovery.\nDefault \"*.test.sql\" so co-located SQL test files (run by the test runner) are never exposed as endpoints. Empty string disables the exclusion.",
         ["NpgsqlRest:SqlFileSource:CommentsMode"] = "How comment annotations are processed for SQL file endpoints.\nPossible values: Ignore, ParseAll, OnlyAnnotated, OnlyWithHttpTag.\nDefault: OnlyAnnotated (OnlyWithHttpTag is a back-compat alias) — SQL files must contain an explicit HTTP annotation (e.g., '-- HTTP GET') to become endpoints.",
         ["NpgsqlRest:SqlFileSource:CommentScope"] = "Which comments in the SQL file to parse as annotations.\nPossible values: All (default — all comments), Header (only comments before the first statement).",
         ["NpgsqlRest:SqlFileSource:ErrorMode"] = "Behavior when a SQL file fails to parse or describe.\nPossible values: Exit (default — log error, exit process), Skip (log error, continue).",
diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index 7e3cb377..f992f6f2 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -890,11 +890,14 @@ public static partial class ConfigSchemaGenerator
         //
         // See https://github.com/serilog/serilog/wiki/Configuration-Basics#minimum-level
         // Verbose, Debug, Information, Warning, Error, Fatal.
+        // Set a level to "Off" (aliases "None"/"Silent") to mute that logger entirely; use null (or omit it) to fall back to its built-in default.
         // Note: NpgsqlRest logger applies to main application logger, which will, by default have the name defined in the ApplicationName setting.
+        // NpgsqlRestTest is the SQL test runner (--test) channel (see TestRunner:LoggerName): discovery/parsing at Debug, each query and HTTP call at Verbose, notices by severity.
         //
         "MinimalLevels": {
           "NpgsqlRest": "Information",
           "NpgsqlRestClient": "Information",
+          "NpgsqlRestTest": "Information",
           "System": "Warning",
           "Microsoft": "Warning"
         },
@@ -1430,7 +1433,83 @@ public static partial class ConfigSchemaGenerator
         //
         "ActivityPath": "/stats/activity"
       },
-    
+
+      //
+      // SQL test runner. Invoked with the `--test` command-line flag (this section is otherwise inert).
+      // Discovers *.test.sql files, runs each in an isolated non-pooled connection, can invoke endpoints
+      // in-process from an embedded `/* GET /path */` block (response captured into a temp table), and
+      // asserts via boolean-returning SELECTs or `do $$ ... assert ... $$;` blocks. Exit codes:
+      // 0 pass, 1 failures, 2 errors, 3 config/runner error, 4 no tests found.
+      //
+      "TestRunner": {
+        //
+        // Glob (same engine as SqlFileSource) selecting test files. Empty disables discovery.
+        // Co-located convention: app.sql (endpoint) next to app.test.sql (test).
+        //
+        "FilePattern": "",
+        //
+        // Max test files run concurrently. 0 => processor count. Each test uses its own non-pooled connection.
+        //
+        "MaxParallelism": 0,
+        //
+        // Stop scheduling new tests after the first failure/error (in-flight tests still finish).
+        //
+        "FailFast": false,
+        //
+        // Per-test timeout. Accepts "30s", "5m", "1h", a plain number of seconds, or "hh:mm:ss". 0 disables.
+        //
+        "PerTestTimeout": "30s",
+        //
+        // Optional path to also write a JUnit XML report (console output is always printed).
+        //
+        "JUnitOutput": null,
+        //
+        // Skip Teardown so a failed run's state can be inspected.
+        //
+        "Keep": false,
+        //
+        // Show captured `raise notice` output for all tests, not just failed/errored ones.
+        //
+        "Verbose": false,
+        //
+        // Treat "no tests discovered" as success (exit 0) instead of exit 4.
+        //
+        "AllowEmpty": false,
+        //
+        // SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels.
+        // Discovery/parsing log at Debug, each query and HTTP invocation at Verbose, `raise notice` by severity.
+        //
+        "LoggerName": "NpgsqlRestTest",
+        //
+        // Per-HTTP-block temp table that captures the response. Each block gets its own fresh temp table
+        // (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified.
+        // A file with ONE HTTP block uses "Name"; a file with 2+ blocks uses "MultiNamePattern" where {n} is
+        // the 1-based block ordinal (_response_1, _response_2, ...). Per-block override: `# @response <name>`.
+        // A null/empty column name omits that column.
+        //
+        "ResponseTempTable": {
+          "Name": "_response",
+          "MultiNamePattern": "_response_{n}",
+          "Columns": {
+            "Status": "status",
+            "Body": "body",
+            "ContentType": "content_type",
+            "Headers": "headers",
+            "IsSuccess": "is_success"
+          }
+        },
+        //
+        // Run-once setup, BEFORE endpoint discovery. Command steps run first (provision infra, e.g. docker),
+        // then SqlFile/Sql steps (migrations/seed) — declared order preserved within each group. Each entry:
+        //   { "Command": "...", "WorkingDirectory": "..." } | { "SqlFile": "..." } | { "Sql": "..." }
+        //
+        "Setup": [],
+        //
+        // Run-once teardown, ALWAYS (best-effort), reverse order: SqlFile/Sql first, then Command. `Keep` skips it.
+        //
+        "Teardown": []
+      },
+
       //
       // Command retry strategies and options for client and middleware commands.
       //
@@ -2917,6 +2996,12 @@ public static partial class ConfigSchemaGenerator
           //
           "FilePattern": "",
           //
+          // Glob (same semantics as FilePattern) for files to EXCLUDE from endpoint discovery.
+          // Default "*.test.sql" so co-located SQL test files (run by the test runner, see "TestRunner")
+          // are never exposed as endpoints. Empty string disables the exclusion.
+          //
+          "SkipPattern": "*.test.sql",
+          //
           // How comment annotations are processed for SQL file endpoints.
           // Possible values: Ignore, ParseAll, OnlyAnnotated, OnlyWithHttpTag.
           // OnlyAnnotated (default; OnlyWithHttpTag is a back-compat alias) requires an explicit
diff --git a/NpgsqlRestClient/Out.cs b/NpgsqlRestClient/Out.cs
index 6a5d95c2..f1c9c05a 100644
--- a/NpgsqlRestClient/Out.cs
+++ b/NpgsqlRestClient/Out.cs
@@ -46,6 +46,23 @@ public void Write(string line, ConsoleColor? color = null)
         }
     }
 
+    /// <summary>
+    /// Write a line wrapped in a raw ANSI SGR sequence (e.g. "\x1b[38;5;196m" for a 256-color foreground),
+    /// used when a specific color is needed that the 16-color <see cref="ConsoleColor"/> API can't express.
+    /// Emits plain text (no escapes) when output is redirected, so piped/CI logs stay clean.
+    /// </summary>
+    public void LineAnsi(string line, string ansiSgr)
+    {
+        if (Console.IsOutputRedirected)
+        {
+            Console.WriteLine(line);
+            return;
+        }
+        Console.Write(ansiSgr);
+        Console.Write(line);
+        Console.WriteLine("\x1b[0m");
+    }
+
     public void JsonHighlight(string json)
     {
         if (Console.IsOutputRedirected)
diff --git a/NpgsqlRestClient/Program.cs b/NpgsqlRestClient/Program.cs
index f4096532..a10031b6 100644
--- a/NpgsqlRestClient/Program.cs
+++ b/NpgsqlRestClient/Program.cs
@@ -38,6 +38,7 @@
         ("npgsqlrest --config-schema", "Output JSON Schema for appsettings.json. Syntax highlighted in terminal, plain JSON when piped."),
         ("npgsqlrest --annotations", "Output all supported comment annotations as JSON. Syntax highlighted in terminal, plain JSON when piped."),
         ("npgsqlrest [files...] --endpoints", "Connect to database, discover endpoints, output as JSON, then exit. Syntax highlighted in terminal, plain JSON when piped."),
+        ("npgsqlrest [files...] --test", "Run SQL test files (TestRunner config), then exit. Exit codes: 0 pass, 1 failures, 2 errors, 3 config error, 4 no tests."),
         (" ", " "),
         ("npgsqlrest --hash [value]", "Hash value with default hasher and print to console."),
         ("npgsqlrest --basic_auth [username] [password]", "Print out basic basic auth header value in format 'Authorization: Basic base64(username:password)'."),
@@ -268,6 +269,7 @@
 }
 
 bool endpointsMode = args.Any(a => string.Equals(a, "--endpoints", StringComparison.OrdinalIgnoreCase));
+bool testMode = args.Any(a => string.Equals(a, "--test", StringComparison.OrdinalIgnoreCase));
 
 builder.BuildInstance();
 builder.Instance.Services.AddRouting();
@@ -482,6 +484,30 @@
     TableFormatHandlers = appInstance.CreateTableFormatHandlers(),
 };
 
+// SQL test runner: run Setup (Commands then SqlFile/Sql) BEFORE discovery so migrations can build the
+// schema that UseNpgsqlRest then discovers. The runner sets options.AmbientConnectionAccessor in its ctor.
+NpgsqlRestClient.Testing.TestRunner? testRunner = null;
+if (testMode)
+{
+    // Test-mode invariants: the endpoint must never begin/commit on the test's connection, and caching
+    // must be off so a test never gets another test's cached response.
+    options.WrapInTransaction = false;
+    options.CacheOptions.DefaultRoutineCache = null;
+    options.CacheOptions.Profiles = null;
+    // Make the runner the single source of connection-notice logging, so notices from the endpoint
+    // pipeline and from the test's own SQL are logged identically (and once). Capture the user's setting,
+    // then disable the per-endpoint notice logging to avoid double-logging on the shared test connection.
+    var logTestNotices = options.LogConnectionNoticeEvents;
+    options.LogConnectionNoticeEvents = false;
+
+    testRunner = new NpgsqlRestClient.Testing.TestRunner(options, builder.BuildTestRunnerOptions(), connectionString, builder.TestLogger, logTestNotices);
+    if (await testRunner.SetupAsync() is false)
+    {
+        Environment.ExitCode = NpgsqlRestClient.Testing.TestRunner.ExitConfig;
+        return;
+    }
+}
+
 app.UseNpgsqlRest(options);
 
 if (endpointsMode)
@@ -495,6 +521,13 @@
     return;
 }
 
+if (testMode)
+{
+    // Endpoints are now built; run the test files (then Teardown), and exit.
+    Environment.ExitCode = await testRunner!.RunAsync(EndpointCapture.Endpoints);
+    return;
+}
+
 if (builder.ExternalAuthConfig?.Enabled is true)
 {
     new ExternalAuth(
diff --git a/NpgsqlRestClient/Testing/HttpFileRequestParser.cs b/NpgsqlRestClient/Testing/HttpFileRequestParser.cs
new file mode 100644
index 00000000..e5939a60
--- /dev/null
+++ b/NpgsqlRestClient/Testing/HttpFileRequestParser.cs
@@ -0,0 +1,150 @@
+namespace NpgsqlRestClient.Testing;
+
+/// <summary>
+/// Parses a single HTTP request out of a block-comment body, using a single-request subset of the
+/// Microsoft .http syntax plus the test directives <c># @claim</c>, <c># @expect-status</c>, <c># @response</c>.
+/// Returns null when the block is not an HTTP request (ordinary SQL comment).
+/// </summary>
+public static class HttpFileRequestParser
+{
+    private static readonly string[] Methods = ["GET", "PUT", "POST", "DELETE"];
+
+    /// <summary>
+    /// Try to parse <paramref name="commentBody"/> (the text between /* and */) as an HTTP request.
+    /// Returns null if the block's first non-blank/non-comment line is not a request line.
+    /// </summary>
+    public static HttpStep? TryParse(string commentBody, int lineNumber)
+    {
+        var lines = commentBody.Replace("\r\n", "\n").Replace('\r', '\n').Split('\n');
+
+        // Find the request line: first line that is not blank and not a #/// comment line.
+        int idx = 0;
+        string? requestLine = null;
+        for (; idx < lines.Length; idx++)
+        {
+            var t = lines[idx].Trim();
+            if (t.Length == 0) continue;
+            if (t.StartsWith('#') || t.StartsWith("//")) continue;
+            requestLine = t;
+            break;
+        }
+        if (requestLine is null) return null;
+
+        if (!TryParseRequestLine(requestLine, out var method, out var path)) return null;
+
+        idx++; // consume the request line
+
+        var headers = new List<(string, string)>();
+        var claims = new List<(string, string)>();
+        int? expectStatus = null;
+        string? responseTable = null;
+        int bodyStart = -1;
+
+        for (; idx < lines.Length; idx++)
+        {
+            var t = lines[idx].Trim();
+            if (t.Length == 0)
+            {
+                bodyStart = idx + 1; // body begins after the blank line
+                break;
+            }
+
+            string? directive = null;
+            if (t.StartsWith('#')) directive = t[1..].TrimStart();
+            else if (t.StartsWith("//")) directive = t[2..].TrimStart();
+
+            if (directive is not null)
+            {
+                if (directive.StartsWith('@'))
+                {
+                    ParseDirective(directive[1..].Trim(), claims, ref expectStatus, ref responseTable);
+                }
+                // plain comment line → ignore
+                continue;
+            }
+
+            // Header: Name: Value
+            int colon = t.IndexOf(':');
+            if (colon > 0)
+            {
+                headers.Add((t[..colon].Trim(), t[(colon + 1)..].Trim()));
+            }
+            // otherwise: stray line in the header region → ignore
+        }
+
+        string? body = null;
+        if (bodyStart >= 0 && bodyStart < lines.Length)
+        {
+            var bodyText = string.Join('\n', lines[bodyStart..]).Trim();
+            if (bodyText.Length > 0) body = bodyText;
+        }
+
+        return new HttpStep(method, path, headers, claims, body, expectStatus, responseTable, lineNumber);
+    }
+
+    // [HTTP] METHOD /path [HTTP/x]. Method required (GET|PUT|POST|DELETE); path must start with '/';
+    // an optional trailing HTTP-version token is allowed but ignored; anything else → not a request.
+    private static bool TryParseRequestLine(string line, out string method, out string path)
+    {
+        method = "";
+        path = "";
+        var tokens = line.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries);
+        if (tokens.Length == 0) return false;
+
+        int ti = 0;
+        if (string.Equals(tokens[ti], "HTTP", StringComparison.OrdinalIgnoreCase))
+        {
+            ti++; // optional leading HTTP keyword
+        }
+        if (ti >= tokens.Length) return false;
+
+        var m = tokens[ti].ToUpperInvariant();
+        if (Array.IndexOf(Methods, m) < 0) return false;
+        ti++;
+
+        if (ti >= tokens.Length) return false; // method but no path
+        var p = tokens[ti];
+        if (!p.StartsWith('/')) return false;  // reject prose like "GET the data"
+        ti++;
+
+        // At most one trailing token, which must be an HTTP-version; otherwise it's prose, not a request.
+        if (ti < tokens.Length)
+        {
+            if (!tokens[ti].StartsWith("HTTP/", StringComparison.OrdinalIgnoreCase)) return false;
+            ti++;
+            if (ti < tokens.Length) return false;
+        }
+
+        method = m;
+        path = p;
+        return true;
+    }
+
+    private static void ParseDirective(
+        string directive,
+        List<(string, string)> claims,
+        ref int? expectStatus,
+        ref string? responseTable)
+    {
+        int sp = directive.IndexOfAny([' ', '\t']);
+        var keyword = sp < 0 ? directive : directive[..sp];
+        var rest = sp < 0 ? "" : directive[(sp + 1)..].Trim();
+
+        if (string.Equals(keyword, "claim", StringComparison.OrdinalIgnoreCase))
+        {
+            int eq = rest.IndexOf('=');
+            if (eq > 0)
+            {
+                claims.Add((rest[..eq].Trim(), rest[(eq + 1)..].Trim()));
+            }
+        }
+        else if (string.Equals(keyword, "expect-status", StringComparison.OrdinalIgnoreCase))
+        {
+            if (int.TryParse(rest, out var code)) expectStatus = code;
+        }
+        else if (string.Equals(keyword, "response", StringComparison.OrdinalIgnoreCase))
+        {
+            if (rest.Length > 0) responseTable = rest;
+        }
+    }
+}
diff --git a/NpgsqlRestClient/Testing/SqlTestFileParser.cs b/NpgsqlRestClient/Testing/SqlTestFileParser.cs
new file mode 100644
index 00000000..bc8bc385
--- /dev/null
+++ b/NpgsqlRestClient/Testing/SqlTestFileParser.cs
@@ -0,0 +1,229 @@
+using System.Text;
+
+namespace NpgsqlRestClient.Testing;
+
+/// <summary>
+/// Splits a .test.sql file into an ordered list of steps (SQL statements and embedded HTTP requests),
+/// preserving interleaving. A char-by-char state machine handles ';' statement splitting, line/block
+/// comments, single quotes (with '' escapes), and dollar-quoted strings / DO blocks (so semicolons inside
+/// them don't split). A block comment whose first line is a request line becomes an <see cref="HttpStep"/>;
+/// any other comment is ignored.
+/// </summary>
+public static class SqlTestFileParser
+{
+    private enum State { Normal, BlockComment, SingleQuote, DollarQuote }
+
+    public static List<TestStep> Parse(string content)
+    {
+        var steps = new List<TestStep>();
+        if (string.IsNullOrEmpty(content)) return steps;
+
+        var state = State.Normal;
+        var stmt = new StringBuilder();
+        var dollarTag = new StringBuilder();
+        var blockComment = new StringBuilder();
+        int blockDepth = 0;
+        int currentLine = 1;
+        int stmtStartLine = 1;
+        bool stmtHasContent = false;
+        int blockCommentStartLine = 1;
+        string lastToken = "";
+        bool lastTokenIsWord = false;
+        bool isDoBlock = false;
+
+        void MarkContent()
+        {
+            if (!stmtHasContent)
+            {
+                stmtHasContent = true;
+                stmtStartLine = currentLine;
+            }
+        }
+
+        void FlushSql()
+        {
+            var text = stmt.ToString().Trim();
+            if (text.Length > 0)
+            {
+                steps.Add(new SqlStep(text, isDoBlock, stmtStartLine));
+            }
+            stmt.Clear();
+            stmtHasContent = false;
+            isDoBlock = false;
+            lastToken = "";
+            lastTokenIsWord = false;
+        }
+
+        int i = 0;
+        int len = content.Length;
+
+        while (i < len)
+        {
+            char c = content[i];
+            switch (state)
+            {
+                case State.Normal:
+                    // line comment: -- (skip to end of line, never an HTTP step)
+                    if (c == '-' && i + 1 < len && content[i + 1] == '-')
+                    {
+                        i += 2;
+                        while (i < len && content[i] != '\n') i++;
+                        continue;
+                    }
+                    // block comment: /*
+                    if (c == '/' && i + 1 < len && content[i + 1] == '*')
+                    {
+                        state = State.BlockComment;
+                        blockDepth = 1;
+                        blockComment.Clear();
+                        blockCommentStartLine = currentLine;
+                        i += 2;
+                        continue;
+                    }
+                    // single quote
+                    if (c == '\'')
+                    {
+                        state = State.SingleQuote;
+                        stmt.Append(c);
+                        MarkContent();
+                        lastToken = "";
+                        lastTokenIsWord = false;
+                        i++;
+                        continue;
+                    }
+                    // dollar quote: $tag$ or $$
+                    if (c == '$')
+                    {
+                        int tagStart = i;
+                        i++;
+                        while (i < len && (char.IsLetterOrDigit(content[i]) || content[i] == '_')) i++;
+                        if (i < len && content[i] == '$')
+                        {
+                            dollarTag.Clear();
+                            dollarTag.Append(content, tagStart, i - tagStart + 1);
+                            state = State.DollarQuote;
+                            if (lastTokenIsWord && lastToken.Length == 2
+                                && (lastToken[0] is 'd' or 'D') && (lastToken[1] is 'o' or 'O'))
+                            {
+                                isDoBlock = true;
+                            }
+                            stmt.Append(content, tagStart, i - tagStart + 1);
+                            MarkContent();
+                            lastToken = "";
+                            lastTokenIsWord = false;
+                            i++;
+                            continue;
+                        }
+                        // not a valid dollar quote: treat $ + run as normal text
+                        stmt.Append(content, tagStart, i - tagStart);
+                        MarkContent();
+                        lastToken = "";
+                        lastTokenIsWord = false;
+                        continue;
+                    }
+                    // statement separator
+                    if (c == ';')
+                    {
+                        FlushSql();
+                        i++;
+                        continue;
+                    }
+                    // word token (for DO-block detection)
+                    if (char.IsLetter(c) || c == '_')
+                    {
+                        int ws = i;
+                        while (i < len && (char.IsLetterOrDigit(content[i]) || content[i] == '_')) i++;
+                        stmt.Append(content, ws, i - ws);
+                        MarkContent();
+                        lastToken = content.Substring(ws, i - ws);
+                        lastTokenIsWord = true;
+                        continue;
+                    }
+                    // whitespace / other
+                    if (c == '\n') currentLine++;
+                    stmt.Append(c);
+                    if (!char.IsWhiteSpace(c))
+                    {
+                        MarkContent();
+                        lastToken = "";
+                        lastTokenIsWord = false;
+                    }
+                    i++;
+                    break;
+
+                case State.BlockComment:
+                    if (c == '/' && i + 1 < len && content[i + 1] == '*')
+                    {
+                        blockDepth++;
+                        blockComment.Append("/*");
+                        i += 2;
+                        continue;
+                    }
+                    if (c == '*' && i + 1 < len && content[i + 1] == '/')
+                    {
+                        blockDepth--;
+                        if (blockDepth == 0)
+                        {
+                            state = State.Normal;
+                            i += 2;
+                            var http = HttpFileRequestParser.TryParse(blockComment.ToString(), blockCommentStartLine);
+                            if (http is not null)
+                            {
+                                FlushSql(); // emit any pending SQL before the HTTP step
+                                steps.Add(http);
+                            }
+                            // else: ordinary comment → ignored
+                            continue;
+                        }
+                        blockComment.Append("*/");
+                        i += 2;
+                        continue;
+                    }
+                    if (c == '\n') currentLine++;
+                    blockComment.Append(c);
+                    i++;
+                    break;
+
+                case State.SingleQuote:
+                    stmt.Append(c);
+                    if (c == '\n') currentLine++;
+                    if (c == '\'')
+                    {
+                        if (i + 1 < len && content[i + 1] == '\'')
+                        {
+                            stmt.Append('\'');
+                            i += 2;
+                            continue;
+                        }
+                        state = State.Normal;
+                    }
+                    i++;
+                    break;
+
+                case State.DollarQuote:
+                    stmt.Append(c);
+                    if (c == '\n') currentLine++;
+                    if (c == '$' && i + dollarTag.Length <= len)
+                    {
+                        bool match = true;
+                        for (int j = 0; j < dollarTag.Length; j++)
+                        {
+                            if (content[i + j] != dollarTag[j]) { match = false; break; }
+                        }
+                        if (match)
+                        {
+                            stmt.Append(content, i + 1, dollarTag.Length - 1);
+                            i += dollarTag.Length;
+                            state = State.Normal;
+                            continue;
+                        }
+                    }
+                    i++;
+                    break;
+            }
+        }
+
+        FlushSql();
+        return steps;
+    }
+}
diff --git a/NpgsqlRestClient/Testing/TestRunner.cs b/NpgsqlRestClient/Testing/TestRunner.cs
new file mode 100644
index 00000000..2e55446d
--- /dev/null
+++ b/NpgsqlRestClient/Testing/TestRunner.cs
@@ -0,0 +1,708 @@
+using System.Collections.Concurrent;
+using System.Diagnostics;
+using System.Security.Claims;
+using System.Text;
+using System.Xml.Linq;
+using Microsoft.Extensions.Logging;
+using Npgsql;
+using NpgsqlRest;
+
+namespace NpgsqlRestClient.Testing;
+
+/// <summary>
+/// SQL test runner (`--test`). Discovers *.test.sql files and runs each on its own non-pooled connection,
+/// invoking endpoints in-process (via <see cref="RoutineInvoker"/> on the test's ambient connection) and
+/// asserting on the captured response. See scrap/test-runner-plan for the full design.
+/// </summary>
+public sealed class TestRunner
+{
+    // Failure/error color: ANSI 256-color 196 — the same red Serilog's Code theme uses (truer than the
+    // 16-color ConsoleColor.Red, which renders orange in some themes). Emitted only to a real terminal.
+    private const string AnsiFail = "\x1b[38;5;196m";
+
+    public const int ExitPass = 0;
+    public const int ExitFailures = 1;
+    public const int ExitErrors = 2;
+    public const int ExitConfig = 3;
+    public const int ExitNoTests = 4;
+
+    // Per-async-flow ambient connection: each parallel test file sets this so the endpoint pipeline
+    // (NpgsqlRestOptions.AmbientConnectionAccessor) runs on that file's connection/transaction.
+    private static readonly AsyncLocal<NpgsqlConnection?> Ambient = new();
+
+    private readonly NpgsqlRestOptions _rest;
+    private readonly TestRunnerOptions _opt;
+    private readonly string _connString;
+    private readonly ILogger? _log;
+    private readonly bool _logNotices;
+    private readonly Out _out = new();
+    private volatile bool _failFast;
+
+    private enum Outcome { Pass, Fail, Error }
+
+    // Result of executing one step. Emit=false marks an arrange/act step that is not a reported test (it
+    // only becomes a result when it errors). Name/Message describe the assertion when Emit=true.
+    private readonly record struct StepResult(bool Emit, Outcome Outcome, string? Message, string? Name);
+
+    // One reported test = one assertion: a boolean-returning SELECT, a DO block (passes unless it raises,
+    // e.g. via ASSERT), or an HTTP step with `# @expect-status`. Errors from any step are also recorded
+    // here so they surface and count.
+    private sealed class AssertionResult
+    {
+        public required string Name { get; init; }
+        public int? Line { get; init; }
+        public Outcome Outcome { get; init; }
+        public string? Message { get; init; }
+        public string? Sql { get; init; }
+    }
+
+    // A test file groups its assertions; the file's outcome is the worst of them (Error > Fail > Pass).
+    // Execution is fail-fast: assertions after the first failure/error in a file are not run (so not listed).
+    private sealed class FileResult
+    {
+        public required string File { get; init; }
+        public long ElapsedMs { get; set; }
+        public List<AssertionResult> Assertions { get; } = [];
+        public List<string> Notices { get; set; } = [];
+
+        public Outcome Outcome =>
+            Assertions.Any(a => a.Outcome == Outcome.Error) ? Outcome.Error :
+            Assertions.Any(a => a.Outcome == Outcome.Fail) ? Outcome.Fail :
+            Outcome.Pass;
+    }
+
+    public TestRunner(NpgsqlRestOptions rest, TestRunnerOptions opt, string baseConnectionString, ILogger? logger, bool logConnectionNotices = false)
+    {
+        _rest = rest;
+        _opt = opt;
+        // Always non-pooled: a fresh physical session per test (no temp-table / GUC / prepared-statement carryover).
+        _connString = new NpgsqlConnectionStringBuilder(baseConnectionString) { Pooling = false }.ConnectionString;
+        _log = logger;
+        _logNotices = logConnectionNotices;
+        // Wire the ambient accessor once; null when no test flow is active → zero effect on discovery/normal ops.
+        _rest.AmbientConnectionAccessor = () => Ambient.Value;
+    }
+
+    /// <summary>Runs before endpoint discovery: collision check + Setup steps. Returns false on failure (logged, teardown attempted).</summary>
+    public async Task<bool> SetupAsync(CancellationToken ct = default)
+    {
+        try
+        {
+            // Response-table names are validated and created per HTTP block (no pre-run permanent-table
+            // collision check needed: writes are pg_temp-qualified and CREATE TEMP TABLE (no IF NOT EXISTS)
+            // fails loudly on a real duplicate).
+            _log?.LogDebug("setup: {Commands} command(s), {Sql} sql step(s)",
+                _opt.Setup.Count(s => s.IsCommand), _opt.Setup.Count(s => !s.IsCommand));
+
+            // Commands first (provision infra), then SqlFile/Sql (migrations/seed), in declared order within each group.
+            foreach (var step in _opt.Setup.Where(s => s.IsCommand))
+            {
+                await RunCommandAsync(step, ct);
+            }
+            await using (var conn = new NpgsqlConnection(_connString))
+            {
+                await conn.OpenAsync(ct);
+                foreach (var step in _opt.Setup.Where(s => !s.IsCommand))
+                {
+                    await RunSqlStepAsync(conn, step, ct);
+                }
+            }
+            return true;
+        }
+        catch (Exception ex)
+        {
+            _out.Line($"Test runner setup failed: {ex.Message}", ConsoleColor.Red);
+            _log?.LogError(ex, "Test runner setup failed");
+            await TeardownAsync(ct);
+            return false;
+        }
+    }
+
+    /// <summary>Runs after endpoint discovery: executes the test files and (always) Teardown. Returns the process exit code.</summary>
+    public async Task<int> RunAsync(RoutineEndpoint[] endpoints, CancellationToken ct = default)
+    {
+        try
+        {
+            var files = DiscoverFiles();
+            _log?.LogDebug("discovered {Count} test file(s) matching {Pattern}", files.Count, _opt.FilePattern);
+            if (files.Count == 0)
+            {
+                _out.Line("Test runner: no test files matched FilePattern.", ConsoleColor.Yellow);
+                return _opt.AllowEmpty ? ExitPass : ExitNoTests;
+            }
+
+            var lookup = BuildEndpointLookup(endpoints);
+            var results = new ConcurrentBag<FileResult>();
+            int dop = _opt.MaxParallelism > 0 ? _opt.MaxParallelism : Environment.ProcessorCount;
+
+            // Console header stays a clean human report (just the file count, like other test runners). The
+            // parallelism is a diagnostic → log channel at Debug, not the always-on console line.
+            _out.Line($"NpgsqlRest test runner — {files.Count} file(s)", ConsoleColor.Cyan);
+            _log?.LogDebug("running {Count} test file(s) at degree of parallelism {Parallelism}", files.Count, dop);
+
+            await Parallel.ForEachAsync(
+                files,
+                new ParallelOptions { MaxDegreeOfParallelism = dop, CancellationToken = ct },
+                async (file, _) =>
+                {
+                    if (_failFast) return; // stop scheduling new work after the first failure (in-flight finish)
+                    var r = await RunFileAsync(file, lookup, ct);
+                    results.Add(r);
+                    if (_opt.FailFast && r.Outcome != Outcome.Pass) _failFast = true;
+                });
+
+            var ordered = results.OrderBy(r => r.File, StringComparer.Ordinal).ToList();
+            ReportConsole(ordered);
+            if (!string.IsNullOrWhiteSpace(_opt.JUnitOutput))
+            {
+                WriteJUnit(ordered, _opt.JUnitOutput!);
+            }
+
+            if (ordered.Any(r => r.Outcome == Outcome.Error)) return ExitErrors;
+            if (ordered.Any(r => r.Outcome == Outcome.Fail)) return ExitFailures;
+            return ExitPass;
+        }
+        finally
+        {
+            await TeardownAsync(ct);
+        }
+    }
+
+    private async Task<FileResult> RunFileAsync(string file, IReadOnlyDictionary<string, RoutineEndpoint> lookup, CancellationToken runCt)
+    {
+        var sw = Stopwatch.StartNew();
+        var result = new FileResult { File = file };
+        var notices = new List<string>();
+        NpgsqlConnection? conn = null;
+        var contextName = Path.GetRelativePath(Environment.CurrentDirectory, file);
+
+        using var perTestCts = CancellationTokenSource.CreateLinkedTokenSource(runCt);
+        if (_opt.PerTestTimeout > TimeSpan.Zero) perTestCts.CancelAfter(_opt.PerTestTimeout);
+        var ct = perTestCts.Token;
+        int timeoutSecs = _opt.PerTestTimeout > TimeSpan.Zero ? (int)Math.Ceiling(_opt.PerTestTimeout.TotalSeconds) : 0;
+
+        try
+        {
+            conn = new NpgsqlConnection(_connString);
+            conn.Notice += (_, e) =>
+            {
+                // Route notices through the test runner's own log channel, tagged with this test file. The
+                // log level follows the notice severity (info/notice => Information, warning => Warning, …);
+                // the channel's MinimalLevel governs visibility. Also capture per-test for the console report.
+                if (_logNotices && _log is not null)
+                    NpgsqlRestLogger.LogConnectionNotice(_log, e.Notice, _rest.LogConnectionNoticeEventsMode, contextName);
+                lock (notices) notices.Add(e.Notice.MessageText);
+            };
+            await conn.OpenAsync(ct);
+            Ambient.Value = conn;
+
+            var steps = SqlTestFileParser.Parse(await File.ReadAllTextAsync(file, ct));
+
+            int httpTotal = steps.Count(s => s is HttpStep);
+            int httpOrdinal = 0;
+            _log?.LogDebug("parsed {File}: {Steps} step(s), {Http} HTTP block(s)", contextName, steps.Count, httpTotal);
+            foreach (var step in steps)
+            {
+                StepResult sr;
+                if (step is SqlStep sql)
+                {
+                    sr = await ExecuteSqlStepAsync(conn, sql, timeoutSecs, ct);
+                }
+                else if (step is HttpStep http)
+                {
+                    httpOrdinal++;
+                    sr = await InvokeHttpStepAsync(conn, http, ResolveResponseTable(http, httpOrdinal, httpTotal), lookup, ct);
+                }
+                else
+                {
+                    continue;
+                }
+
+                if (sr.Emit)
+                {
+                    result.Assertions.Add(new AssertionResult
+                    {
+                        Name = sr.Name ?? DefaultAssertionName(step),
+                        Line = step.LineNumber,
+                        Outcome = sr.Outcome,
+                        Message = sr.Message,
+                        Sql = step is SqlStep s ? s.Text : null,
+                    });
+                }
+                // Fail-fast within a file: a failed/errored step (a failing DO-block assert aborts the PG
+                // transaction anyway) stops execution, so later assertions in this file are not run.
+                if (sr.Outcome is Outcome.Fail or Outcome.Error) break;
+            }
+        }
+        catch (OperationCanceledException) when (perTestCts.IsCancellationRequested && !runCt.IsCancellationRequested)
+        {
+            result.Assertions.Add(TimeoutAssertion());
+        }
+        catch (PostgresException pg) when (pg.SqlState == "57014")
+        {
+            result.Assertions.Add(TimeoutAssertion());
+        }
+        catch (Exception ex)
+        {
+            result.Assertions.Add(new AssertionResult { Name = "execution error", Outcome = Outcome.Error, Message = ex.Message });
+        }
+        finally
+        {
+            // No explicit ROLLBACK: the connection is non-pooled, so DisposeAsync physically closes it and
+            // the server aborts any still-open transaction — that is the safety net for a test that didn't
+            // roll back itself. An explicit ROLLBACK here would also raise PG warning 25P01
+            // ("there is no transaction in progress") for the common case where the test already rolled
+            // back or never opened a transaction.
+            Ambient.Value = null;
+            if (conn is not null) await conn.DisposeAsync();
+        }
+
+        result.ElapsedMs = sw.ElapsedMilliseconds;
+        result.Notices = notices;
+        _log?.LogDebug("{File}: {Outcome} ({Count} assertion(s), {Ms}ms)",
+            contextName, result.Outcome, result.Assertions.Count, result.ElapsedMs);
+        return result;
+
+        AssertionResult TimeoutAssertion() => new()
+        {
+            Name = "timed out",
+            Outcome = Outcome.Error,
+            Message = $"timed out after {_opt.PerTestTimeout.TotalSeconds:0}s",
+        };
+    }
+
+    private async Task<StepResult> ExecuteSqlStepAsync(
+        NpgsqlConnection conn, SqlStep step, int timeoutSecs, CancellationToken ct)
+    {
+        _log?.LogTrace("sql (line {Line}): {Sql}", step.LineNumber, step.Text.Trim());
+        try
+        {
+            await using var cmd = new NpgsqlCommand(step.Text, conn);
+            if (timeoutSecs > 0) cmd.CommandTimeout = timeoutSecs;
+            await using var reader = await cmd.ExecuteReaderAsync(ct);
+
+            // Boolean first column => assertion (first row only; 0 rows = pass). The optional second column
+            // is the human-readable assertion name/message.
+            if (reader.FieldCount >= 1 && reader.GetFieldType(0) == typeof(bool))
+            {
+                string? desc = null;
+                bool pass = true;
+                if (await reader.ReadAsync(ct))
+                {
+                    pass = !reader.IsDBNull(0) && reader.GetBoolean(0);
+                    desc = reader.FieldCount >= 2 && !reader.IsDBNull(1) ? reader.GetValue(1)?.ToString() : null;
+                }
+                return pass
+                    ? new StepResult(true, Outcome.Pass, null, desc)
+                    : new StepResult(true, Outcome.Fail, desc ?? $"assertion failed: {FirstLine(step.Text)}", desc);
+            }
+            // A DO block produces no result set; it counts as an assertion that passes unless it raised
+            // (e.g. ASSERT => P0004, caught below). Any other statement is arrange/act, not a reported test.
+            return step.IsDoBlock
+                ? new StepResult(true, Outcome.Pass, null, null)
+                : new StepResult(false, Outcome.Pass, null, null);
+        }
+        catch (PostgresException pg)
+        {
+            if (pg.SqlState == "P0004") return new StepResult(true, Outcome.Fail, pg.MessageText, null); // assert
+            if (pg.SqlState == "57014") throw; // timeout — let RunFileAsync classify
+            return new StepResult(true, Outcome.Error, $"{pg.SqlState}: {pg.MessageText}", null);
+        }
+    }
+
+    private async Task<StepResult> InvokeHttpStepAsync(
+        NpgsqlConnection conn, HttpStep step, string responseTable, IReadOnlyDictionary<string, RoutineEndpoint> lookup, CancellationToken ct)
+    {
+        var httpName = $"{step.Method} {step.Path}";
+        var pathOnly = StripQuery(step.Path);
+        if (lookup.TryGetValue($"{step.Method} {pathOnly}", out var ep))
+        {
+            if (ep.SseEventsPath is not null || ep.SsePublishEnabled)
+                return new StepResult(true, Outcome.Error, $"SSE endpoints are not supported in test mode: {httpName}", httpName);
+            if (ep.Upload)
+                return new StepResult(true, Outcome.Error, $"upload endpoints are not supported in test mode: {httpName}", httpName);
+            if (ep.IsProxy)
+            {
+                var host = ep.ProxyHost ?? _rest.ProxyOptions?.Host;
+                if (host is not null && !host.StartsWith('/'))
+                    return new StepResult(true, Outcome.Error, $"outbound proxy/HTTP-type endpoints are disallowed in test mode: {httpName}", httpName);
+            }
+        }
+
+        var user = BuildPrincipal(step.Claims);
+
+        Dictionary<string, string>? headers = null;
+        string? contentType = null;
+        if (step.Headers.Count > 0)
+        {
+            headers = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+            foreach (var (name, value) in step.Headers)
+            {
+                headers[name] = value;
+                if (string.Equals(name, "Content-Type", StringComparison.OrdinalIgnoreCase)) contentType = value;
+            }
+        }
+
+        Ambient.Value = conn; // ensure this file's connection is used by the endpoint pipeline
+        _log?.LogTrace("http {Method} {Path} (line {Line})", step.Method, step.Path, step.LineNumber);
+        var response = await RoutineInvoker.InvokeAsync(step.Method, step.Path, headers, step.Body, contentType, user, ct);
+        _log?.LogTrace("http {Method} {Path} → {Status}, captured into temp table \"{Table}\"",
+            step.Method, step.Path, response.StatusCode, responseTable);
+
+        await WriteResponseAsync(conn, responseTable, response, ct);
+
+        // An HTTP block is a reported assertion only when it carries `# @expect-status`; otherwise it is an
+        // act step (capture the response into the temp table) and produces no test of its own.
+        if (step.ExpectStatus.HasValue)
+        {
+            var name = $"{httpName} (expect {step.ExpectStatus.Value})";
+            return response.StatusCode == step.ExpectStatus.Value
+                ? new StepResult(true, Outcome.Pass, null, name)
+                : new StepResult(true, Outcome.Fail, $"expected status {step.ExpectStatus.Value} but got {response.StatusCode} for {httpName}", name);
+        }
+        return new StepResult(false, Outcome.Pass, null, null);
+    }
+
+    private async Task WriteResponseAsync(NpgsqlConnection conn, string table, RoutineInvokeResult response, CancellationToken ct)
+    {
+        if (!ValidateIdentifier(table))
+            throw new InvalidOperationException($"invalid response table name '{table}'");
+
+        var c = _opt.ResponseTempTable.Columns;
+        var cols = new List<(string Name, string Type, object? Value, bool Jsonb)>();
+        if (!string.IsNullOrWhiteSpace(c.Status)) cols.Add((c.Status!, "int", response.StatusCode, false));
+        if (!string.IsNullOrWhiteSpace(c.Body)) cols.Add((c.Body!, "text", (object?)response.Body ?? DBNull.Value, false));
+        if (!string.IsNullOrWhiteSpace(c.ContentType)) cols.Add((c.ContentType!, "text", (object?)response.ContentType ?? DBNull.Value, false));
+        if (!string.IsNullOrWhiteSpace(c.Headers)) cols.Add((c.Headers!, "jsonb", (object?)response.Headers ?? DBNull.Value, true));
+        if (!string.IsNullOrWhiteSpace(c.IsSuccess)) cols.Add((c.IsSuccess!, "boolean", response.IsSuccess, false));
+        if (cols.Count == 0)
+            throw new InvalidOperationException("ResponseTempTable.Columns has no columns enabled.");
+
+        foreach (var col in cols)
+        {
+            if (!ValidateIdentifier(col.Name))
+                throw new InvalidOperationException($"invalid response column name '{col.Name}'");
+        }
+
+        // CREATE TEMP TABLE (no IF NOT EXISTS): each HTTP block gets its own fresh table, so a name clash
+        // (e.g. a duplicate `# @response` name) fails the test loudly. TEMP forces pg_temp; the INSERT is
+        // pg_temp-qualified so it can never touch a permanent table. (Client runs with Npgsql SQL-rewriting
+        // disabled → one statement per command, positional params.)
+        var defs = string.Join(", ", cols.Select(col => $"\"{col.Name}\" {col.Type}"));
+        await using (var create = new NpgsqlCommand($"create temp table \"{table}\" ({defs})", conn))
+        {
+            await create.ExecuteNonQueryAsync(ct);
+        }
+
+        var colList = string.Join(", ", cols.Select(col => $"\"{col.Name}\""));
+        var valList = string.Join(", ", cols.Select((col, i) => col.Jsonb ? $"${i + 1}::jsonb" : $"${i + 1}"));
+        await using var ins = new NpgsqlCommand($"insert into pg_temp.\"{table}\" ({colList}) values ({valList})", conn);
+        foreach (var col in cols)
+        {
+            ins.Parameters.AddWithValue(col.Value ?? DBNull.Value);
+        }
+        await ins.ExecuteNonQueryAsync(ct);
+    }
+
+    // The temp-table name for an HTTP block: explicit `# @response` wins; otherwise a file with a single
+    // HTTP block uses Name (`_response`), and a file with 2+ blocks uses MultiNamePattern with {n} = the
+    // 1-based block ordinal (`_response_1`, `_response_2`, …).
+    private string ResolveResponseTable(HttpStep http, int ordinal, int httpTotal)
+    {
+        if (!string.IsNullOrWhiteSpace(http.ResponseTable)) return http.ResponseTable!.Trim();
+        if (httpTotal <= 1) return _opt.ResponseTempTable.Name;
+        return _opt.ResponseTempTable.MultiNamePattern
+            .Replace("{n}", ordinal.ToString(System.Globalization.CultureInfo.InvariantCulture));
+    }
+
+    private static ClaimsPrincipal? BuildPrincipal(IReadOnlyList<(string Name, string Value)> claims)
+    {
+        if (claims.Count == 0) return null; // anonymous → 401 on protected endpoints
+        var identity = new ClaimsIdentity(authenticationType: "TestRunner"); // non-null auth type => IsAuthenticated
+        foreach (var (name, value) in claims)
+        {
+            identity.AddClaim(new Claim(name, value));
+        }
+        return new ClaimsPrincipal(identity);
+    }
+
+    // -------- Setup/Teardown step execution --------
+
+    private async Task RunCommandAsync(TestSetupStep step, CancellationToken ct)
+    {
+        var psi = new ProcessStartInfo
+        {
+            FileName = OperatingSystem.IsWindows() ? "cmd.exe" : "/bin/sh",
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            UseShellExecute = false,
+            WorkingDirectory = string.IsNullOrWhiteSpace(step.WorkingDirectory)
+                ? Environment.CurrentDirectory
+                : Path.GetFullPath(step.WorkingDirectory),
+        };
+        psi.ArgumentList.Add(OperatingSystem.IsWindows() ? "/c" : "-c");
+        psi.ArgumentList.Add(step.Command!);
+
+        _log?.LogDebug("setup/teardown command: {Command}", step.Command);
+        using var proc = new Process { StartInfo = psi };
+        proc.Start();
+        var stdout = await proc.StandardOutput.ReadToEndAsync(ct);
+        var stderr = await proc.StandardError.ReadToEndAsync(ct);
+        await proc.WaitForExitAsync(ct);
+        if (!string.IsNullOrWhiteSpace(stdout)) _log?.LogDebug("command output: {Out}", stdout.Trim());
+        if (proc.ExitCode != 0)
+        {
+            throw new InvalidOperationException(
+                $"command failed (exit {proc.ExitCode}): {step.Command}{(string.IsNullOrWhiteSpace(stderr) ? "" : "\n" + stderr.Trim())}");
+        }
+    }
+
+    private async Task RunSqlStepAsync(NpgsqlConnection conn, TestSetupStep step, CancellationToken ct)
+    {
+        string sql;
+        if (!string.IsNullOrWhiteSpace(step.SqlFile))
+        {
+            sql = await File.ReadAllTextAsync(Path.GetFullPath(step.SqlFile), ct);
+        }
+        else
+        {
+            sql = step.Sql ?? "";
+        }
+        if (string.IsNullOrWhiteSpace(sql)) return;
+        _log?.LogDebug("setup/teardown sql: {Source}", step.SqlFile ?? "(inline)");
+        // Split into individual statements (SQL-rewriting is disabled → one statement per command).
+        // Reuses the test-file parser; DO blocks / dollar-quoted bodies stay whole.
+        foreach (var parsed in SqlTestFileParser.Parse(sql))
+        {
+            if (parsed is SqlStep s)
+            {
+                _log?.LogTrace("sql: {Sql}", s.Text.Trim());
+                await using var cmd = new NpgsqlCommand(s.Text, conn);
+                await cmd.ExecuteNonQueryAsync(ct);
+            }
+        }
+    }
+
+    private async Task TeardownAsync(CancellationToken ct)
+    {
+        if (_opt.Keep || _opt.Teardown.Count == 0) return;
+        _log?.LogDebug("teardown: {Steps} step(s)", _opt.Teardown.Count);
+        try
+        {
+            await using var conn = new NpgsqlConnection(_connString);
+            await conn.OpenAsync(ct);
+            foreach (var step in _opt.Teardown.Where(s => !s.IsCommand)) // SQL first
+            {
+                try { await RunSqlStepAsync(conn, step, ct); }
+                catch (Exception ex) { _log?.LogWarning(ex, "teardown SQL step failed"); }
+            }
+        }
+        catch (Exception ex) { _log?.LogWarning(ex, "teardown connection failed"); }
+
+        foreach (var step in _opt.Teardown.Where(s => s.IsCommand)) // commands last (e.g. docker down)
+        {
+            try { await RunCommandAsync(step, ct); }
+            catch (Exception ex) { _log?.LogWarning(ex, "teardown command failed"); }
+        }
+    }
+
+    // -------- discovery / reporting / helpers --------
+
+    private List<string> DiscoverFiles()
+    {
+        var pattern = _opt.FilePattern;
+        if (string.IsNullOrWhiteSpace(pattern)) return [];
+
+        int firstWildcard = pattern.IndexOfAny(['*', '?']);
+        if (firstWildcard < 0)
+        {
+            return File.Exists(pattern) ? [Path.GetFullPath(pattern)] : [];
+        }
+
+        int lastSlash = pattern.LastIndexOf('/', firstWildcard);
+        string baseDir = lastSlash >= 0 ? pattern[..lastSlash] : ".";
+        if (!Directory.Exists(baseDir)) return [];
+
+        var searchOption = pattern.Contains("**") ? SearchOption.AllDirectories : SearchOption.TopDirectoryOnly;
+        var result = new List<string>();
+        foreach (var file in Directory.EnumerateFiles(baseDir, "*", searchOption))
+        {
+            if (Parser.IsPatternMatch(file.Replace('\\', '/'), pattern))
+            {
+                result.Add(file);
+            }
+        }
+        return result;
+    }
+
+    private static Dictionary<string, RoutineEndpoint> BuildEndpointLookup(RoutineEndpoint[] endpoints)
+    {
+        var d = new Dictionary<string, RoutineEndpoint>(endpoints.Length, StringComparer.OrdinalIgnoreCase);
+        foreach (var ep in endpoints)
+        {
+            d[$"{ep.Method} {ep.Path}"] = ep;
+        }
+        return d;
+    }
+
+    // Print the failing statement under the message (dimmed). Capped to its first line unless --verbose.
+    private void WriteFailingSql(string? sql)
+    {
+        if (string.IsNullOrWhiteSpace(sql)) return;
+        var text = sql.Trim();
+        if (_opt.Verbose)
+        {
+            _out.Line("        " + text.Replace("\n", "\n        "), ConsoleColor.DarkGray);
+            return;
+        }
+        int nl = text.IndexOf('\n');
+        var line = (nl >= 0 ? text[..nl] : text).TrimEnd();
+        bool more = nl >= 0 || line.Length > 120;
+        if (line.Length > 120) line = line[..120];
+        _out.Line($"        {line}{(more ? " …" : "")}", ConsoleColor.DarkGray);
+    }
+
+    private void ReportConsole(List<FileResult> results)
+    {
+        // Counts are at assertion granularity (each boolean SELECT / DO block / `# @expect-status` HTTP
+        // step is one test); files are the grouping unit. A file is fail-fast, so on failure the assertions
+        // listed are those that ran up to and including the first failure.
+        int passed = 0, failed = 0, errored = 0, totalAssertions = 0;
+        foreach (var fr in results)
+        {
+            var rel = Path.GetRelativePath(Environment.CurrentDirectory, fr.File);
+            int aPass = fr.Assertions.Count(a => a.Outcome == Outcome.Pass);
+            passed += aPass;
+            failed += fr.Assertions.Count(a => a.Outcome == Outcome.Fail);
+            errored += fr.Assertions.Count(a => a.Outcome == Outcome.Error);
+            totalAssertions += fr.Assertions.Count;
+
+            if (fr.Assertions.Count == 0)
+            {
+                // The file ran but contained no recognizable assertion — surface it rather than count a pass.
+                _out.Line($"PASS  {rel}  (no assertions, {fr.ElapsedMs}ms)", ConsoleColor.Yellow);
+            }
+            else if (fr.Outcome == Outcome.Pass)
+            {
+                _out.Line($"PASS  {rel}  ({aPass} assertion{(aPass == 1 ? "" : "s")}, {fr.ElapsedMs}ms)", ConsoleColor.Green);
+                if (_opt.Verbose)
+                    foreach (var a in fr.Assertions) _out.Line($"        ✓ {a.Name}", ConsoleColor.DarkGray);
+            }
+            else
+            {
+                var label = fr.Outcome == Outcome.Error ? "ERROR" : "FAIL ";
+                _out.LineAnsi($"{label} {rel}  ({fr.ElapsedMs}ms)", AnsiFail);
+                foreach (var a in fr.Assertions)
+                {
+                    if (a.Outcome == Outcome.Pass)
+                    {
+                        if (_opt.Verbose) _out.Line($"        ✓ {a.Name}", ConsoleColor.DarkGray);
+                        continue;
+                    }
+                    var loc = a.Line is null ? "" : $"  [{rel}:{a.Line}]";
+                    _out.LineAnsi($"        ✗ {a.Name}{loc}", AnsiFail);
+                    if (!string.IsNullOrWhiteSpace(a.Message) && a.Message != a.Name) _out.LineAnsi($"          {a.Message}", AnsiFail);
+                    WriteFailingSql(a.Sql);
+                }
+            }
+
+            if (fr.Notices.Count > 0 && (_opt.Verbose || fr.Outcome != Outcome.Pass))
+                foreach (var n in fr.Notices) _out.Line($"        notice: {n}", ConsoleColor.DarkGray);
+        }
+
+        var summary = $"\n{passed} passed, {failed} failed, {errored} error(s)  —  {totalAssertions} assertion{(totalAssertions == 1 ? "" : "s")} in {results.Count} file{(results.Count == 1 ? "" : "s")}";
+        if (failed + errored == 0) _out.Line(summary, ConsoleColor.Green);
+        else _out.LineAnsi(summary, AnsiFail);
+    }
+
+    private static void WriteJUnit(List<FileResult> results, string path)
+    {
+        var inv = System.Globalization.CultureInfo.InvariantCulture;
+        // One <testcase> per assertion (classname = file), so CI tools count individual tests. A file with
+        // no assertions still appears as a single skipped testcase. Notices are attached to failing cases.
+        int tests = results.Sum(f => Math.Max(f.Assertions.Count, 1));
+        int failures = results.Sum(f => f.Assertions.Count(a => a.Outcome == Outcome.Fail));
+        int errors = results.Sum(f => f.Assertions.Count(a => a.Outcome == Outcome.Error));
+        int skipped = results.Count(f => f.Assertions.Count == 0);
+
+        var suite = new XElement("testsuite",
+            new XAttribute("name", "npgsqlrest"),
+            new XAttribute("tests", tests),
+            new XAttribute("failures", failures),
+            new XAttribute("errors", errors),
+            new XAttribute("skipped", skipped),
+            new XAttribute("time", (results.Sum(r => r.ElapsedMs) / 1000.0).ToString("0.000", inv)));
+
+        foreach (var fr in results)
+        {
+            // Spread the file's wall-clock time evenly across its assertions for per-case timing.
+            double caseTime = fr.Assertions.Count > 0 ? fr.ElapsedMs / 1000.0 / fr.Assertions.Count : fr.ElapsedMs / 1000.0;
+            string caseTimeStr = caseTime.ToString("0.000", inv);
+
+            if (fr.Assertions.Count == 0)
+            {
+                var empty = new XElement("testcase",
+                    new XAttribute("name", "(no assertions)"),
+                    new XAttribute("classname", fr.File),
+                    new XAttribute("time", caseTimeStr));
+                empty.Add(new XElement("skipped"));
+                suite.Add(empty);
+                continue;
+            }
+
+            foreach (var a in fr.Assertions)
+            {
+                var tc = new XElement("testcase",
+                    new XAttribute("name", a.Name),
+                    new XAttribute("classname", fr.File),
+                    new XAttribute("time", caseTimeStr));
+                if (a.Outcome == Outcome.Fail)
+                    tc.Add(new XElement("failure", new XAttribute("message", a.Message ?? "assertion failed"), $"{fr.File}{(a.Line is null ? "" : $":{a.Line}")}"));
+                else if (a.Outcome == Outcome.Error)
+                    tc.Add(new XElement("error", new XAttribute("message", a.Message ?? "error"), $"{fr.File}{(a.Line is null ? "" : $":{a.Line}")}"));
+                if (a.Outcome != Outcome.Pass && fr.Notices.Count > 0)
+                    tc.Add(new XElement("system-out", string.Join('\n', fr.Notices)));
+                suite.Add(tc);
+            }
+        }
+
+        var dir = Path.GetDirectoryName(Path.GetFullPath(path));
+        if (!string.IsNullOrEmpty(dir)) Directory.CreateDirectory(dir);
+        new XDocument(new XDeclaration("1.0", "utf-8", null), suite).Save(path);
+    }
+
+    private static string StripQuery(string path)
+    {
+        int q = path.IndexOf('?');
+        return q >= 0 ? path[..q] : path;
+    }
+
+    private static string FirstLine(string text)
+    {
+        int nl = text.IndexOf('\n');
+        var line = (nl >= 0 ? text[..nl] : text).Trim();
+        return line.Length > 80 ? line[..80] + "…" : line;
+    }
+
+    // Fallback display name when a step has no inherent label (a boolean SELECT without a description column,
+    // a DO block, or a non-`# @expect-status` HTTP step that errored).
+    private static string DefaultAssertionName(TestStep step) => step switch
+    {
+        SqlStep { IsDoBlock: true } => $"assert block (line {step.LineNumber})",
+        SqlStep sql => FirstLine(sql.Text),
+        HttpStep http => $"{http.Method} {http.Path}",
+        _ => $"step (line {step.LineNumber})",
+    };
+
+    // Valid unquoted/quoted SQL identifier: [A-Za-z_][A-Za-z0-9_]*  (prevents injection in table/column DDL).
+    private static bool ValidateIdentifier(string? id)
+    {
+        if (string.IsNullOrEmpty(id)) return false;
+        if (!(char.IsLetter(id[0]) || id[0] == '_')) return false;
+        for (int i = 1; i < id.Length; i++)
+        {
+            if (!(char.IsLetterOrDigit(id[i]) || id[i] == '_')) return false;
+        }
+        return true;
+    }
+}
diff --git a/NpgsqlRestClient/Testing/TestRunnerOptions.cs b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
new file mode 100644
index 00000000..2ccf7a55
--- /dev/null
+++ b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
@@ -0,0 +1,83 @@
+namespace NpgsqlRestClient.Testing;
+
+/// <summary>Options for the SQL test runner (<c>--test</c>). Bound from the top-level "TestRunner" config section.</summary>
+public class TestRunnerOptions
+{
+    /// <summary>Glob (same engine as SqlFileSource) selecting *.test.sql files. Empty disables the runner.</summary>
+    public string FilePattern { get; set; } = "";
+
+    /// <summary>Max concurrent test files. 0 => Environment.ProcessorCount.</summary>
+    public int MaxParallelism { get; set; } = 0;
+
+    /// <summary>Stop scheduling new tests after the first failure/error (in-flight tests still finish).</summary>
+    public bool FailFast { get; set; } = false;
+
+    /// <summary>Per-test timeout. Zero or negative => no timeout.</summary>
+    public TimeSpan PerTestTimeout { get; set; } = TimeSpan.FromSeconds(30);
+
+    /// <summary>Optional path to also write a JUnit XML report (console is always printed).</summary>
+    public string? JUnitOutput { get; set; } = null;
+
+    /// <summary>Skip Teardown so a failed run's state can be inspected.</summary>
+    public bool Keep { get; set; } = false;
+
+    /// <summary>Show captured `raise notice` output for all tests, not just failed/errored ones.</summary>
+    public bool Verbose { get; set; } = false;
+
+    /// <summary>Zero tests discovered => exit 0 instead of 4.</summary>
+    public bool AllowEmpty { get; set; } = false;
+
+    /// <summary>
+    /// SourceContext name for the runner's own log channel — discovery/parsing at Debug, each query and HTTP
+    /// invocation at Verbose, captured `raise notice` by its severity. Set its level independently via
+    /// Log:MinimalLevels (defaults to Information when absent). The console PASS/FAIL report is separate.
+    /// </summary>
+    public string LoggerName { get; set; } = "NpgsqlRestTest";
+
+    public ResponseTempTableOptions ResponseTempTable { get; set; } = new();
+
+    /// <summary>Run-once setup, before endpoint discovery. Commands run first, then SqlFile/Sql (declared order within each group).</summary>
+    public List<TestSetupStep> Setup { get; set; } = [];
+
+    /// <summary>Run-once teardown, always (best-effort). Reverse: SqlFile/Sql first, then Commands.</summary>
+    public List<TestSetupStep> Teardown { get; set; } = [];
+}
+
+/// <summary>Response temp-table configuration. Column values map 1:1 from the captured response; a null/empty column name omits that column.</summary>
+public class ResponseTempTableOptions
+{
+    /// <summary>Temp table name when a test file has exactly one HTTP block.</summary>
+    public string Name { get; set; } = "_response";
+
+    /// <summary>Temp table name pattern when a file has 2+ HTTP blocks. <c>{n}</c> = the 1-based block ordinal.</summary>
+    public string MultiNamePattern { get; set; } = "_response_{n}";
+
+    public ResponseColumnOptions Columns { get; set; } = new();
+}
+
+public class ResponseColumnOptions
+{
+    public string? Status { get; set; } = "status";
+    public string? Body { get; set; } = "body";
+    public string? ContentType { get; set; } = "content_type";
+    public string? Headers { get; set; } = "headers";
+    public string? IsSuccess { get; set; } = "is_success";
+}
+
+/// <summary>One Setup/Teardown step — exactly one of Sql / SqlFile / Command.</summary>
+public class TestSetupStep
+{
+    /// <summary>Inline SQL executed as a single batch.</summary>
+    public string? Sql { get; set; }
+
+    /// <summary>Path (cwd-relative) to a .sql file executed as a single batch.</summary>
+    public string? SqlFile { get; set; }
+
+    /// <summary>Shell command (run via the OS shell). Non-zero exit aborts a Setup run.</summary>
+    public string? Command { get; set; }
+
+    /// <summary>Working directory for <see cref="Command"/> (cwd-relative); null => current directory.</summary>
+    public string? WorkingDirectory { get; set; }
+
+    public bool IsCommand => !string.IsNullOrWhiteSpace(Command);
+}
diff --git a/NpgsqlRestClient/Testing/TestStep.cs b/NpgsqlRestClient/Testing/TestStep.cs
new file mode 100644
index 00000000..2ffeb0ae
--- /dev/null
+++ b/NpgsqlRestClient/Testing/TestStep.cs
@@ -0,0 +1,75 @@
+namespace NpgsqlRestClient.Testing;
+
+/// <summary>Kind of a parsed test step.</summary>
+public enum TestStepKind
+{
+    /// <summary>A SQL statement (or DO block) executed on the test connection.</summary>
+    Sql,
+    /// <summary>An embedded HTTP request (a /* ... */ block whose first line is a request line).</summary>
+    Http,
+}
+
+/// <summary>One ordered step in a parsed .test.sql file.</summary>
+public abstract class TestStep
+{
+    public TestStepKind Kind { get; }
+    /// <summary>1-based line in the source file where this step starts (for error reporting).</summary>
+    public int LineNumber { get; }
+
+    protected TestStep(TestStepKind kind, int lineNumber)
+    {
+        Kind = kind;
+        LineNumber = lineNumber;
+    }
+}
+
+/// <summary>A SQL statement step — executed via ExecuteReader; a boolean first column is an assertion.</summary>
+public sealed class SqlStep : TestStep
+{
+    public string Text { get; }
+    public bool IsDoBlock { get; }
+
+    public SqlStep(string text, bool isDoBlock, int lineNumber) : base(TestStepKind.Sql, lineNumber)
+    {
+        Text = text;
+        IsDoBlock = isDoBlock;
+    }
+}
+
+/// <summary>An embedded single-request HTTP step parsed from a block comment.</summary>
+public sealed class HttpStep : TestStep
+{
+    /// <summary>HTTP method (upper-cased): GET, PUT, POST, DELETE.</summary>
+    public string Method { get; }
+    /// <summary>Request target verbatim, including any query string. Always starts with '/'.</summary>
+    public string Path { get; }
+    /// <summary>Request headers in declared order (duplicates allowed).</summary>
+    public IReadOnlyList<(string Name, string Value)> Headers { get; }
+    /// <summary>Claims for the acting principal (from <c># @claim name=value</c>), in declared order.</summary>
+    public IReadOnlyList<(string Name, string Value)> Claims { get; }
+    /// <summary>Request body (verbatim), or null when none.</summary>
+    public string? Body { get; }
+    /// <summary>Expected status from <c># @expect-status NNN</c>, or null.</summary>
+    public int? ExpectStatus { get; }
+    /// <summary>Response temp-table name override from <c># @response name</c>, or null (use the configured default).</summary>
+    public string? ResponseTable { get; }
+
+    public HttpStep(
+        string method,
+        string path,
+        IReadOnlyList<(string Name, string Value)> headers,
+        IReadOnlyList<(string Name, string Value)> claims,
+        string? body,
+        int? expectStatus,
+        string? responseTable,
+        int lineNumber) : base(TestStepKind.Http, lineNumber)
+    {
+        Method = method;
+        Path = path;
+        Headers = headers;
+        Claims = claims;
+        Body = body;
+        ExpectStatus = expectStatus;
+        ResponseTable = responseTable;
+    }
+}
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index 2146a723..db81a5c2 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -881,11 +881,14 @@
     //
     // See https://github.com/serilog/serilog/wiki/Configuration-Basics#minimum-level
     // Verbose, Debug, Information, Warning, Error, Fatal.
+    // Set a level to "Off" (aliases "None"/"Silent") to mute that logger entirely; use null (or omit it) to fall back to its built-in default.
     // Note: NpgsqlRest logger applies to main application logger, which will, by default have the name defined in the ApplicationName setting.
+    // NpgsqlRestTest is the SQL test runner (--test) channel (see TestRunner:LoggerName): discovery/parsing at Debug, each query and HTTP call at Verbose, notices by severity.
     //
     "MinimalLevels": {
       "NpgsqlRest": "Information",
       "NpgsqlRestClient": "Information",
+      "NpgsqlRestTest": "Information",
       "System": "Warning",
       "Microsoft": "Warning"
     },
@@ -1422,6 +1425,82 @@
     "ActivityPath": "/stats/activity"
   },
 
+  //
+  // SQL test runner. Invoked with the `--test` command-line flag (this section is otherwise inert).
+  // Discovers *.test.sql files, runs each in an isolated non-pooled connection, can invoke endpoints
+  // in-process from an embedded `/* GET /path */` block (response captured into a temp table), and
+  // asserts via boolean-returning SELECTs or `do $$ ... assert ... $$;` blocks. Exit codes:
+  // 0 pass, 1 failures, 2 errors, 3 config/runner error, 4 no tests found.
+  //
+  "TestRunner": {
+    //
+    // Glob (same engine as SqlFileSource) selecting test files. Empty disables discovery.
+    // Co-located convention: app.sql (endpoint) next to app.test.sql (test).
+    //
+    "FilePattern": "",
+    //
+    // Max test files run concurrently. 0 => processor count. Each test uses its own non-pooled connection.
+    //
+    "MaxParallelism": 0,
+    //
+    // Stop scheduling new tests after the first failure/error (in-flight tests still finish).
+    //
+    "FailFast": false,
+    //
+    // Per-test timeout. Accepts "30s", "5m", "1h", a plain number of seconds, or "hh:mm:ss". 0 disables.
+    //
+    "PerTestTimeout": "30s",
+    //
+    // Optional path to also write a JUnit XML report (console output is always printed).
+    //
+    "JUnitOutput": null,
+    //
+    // Skip Teardown so a failed run's state can be inspected.
+    //
+    "Keep": false,
+    //
+    // Show captured `raise notice` output for all tests, not just failed/errored ones.
+    //
+    "Verbose": false,
+    //
+    // Treat "no tests discovered" as success (exit 0) instead of exit 4.
+    //
+    "AllowEmpty": false,
+    //
+    // SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels.
+    // Discovery/parsing log at Debug, each query and HTTP invocation at Verbose, `raise notice` by severity.
+    //
+    "LoggerName": "NpgsqlRestTest",
+    //
+    // Per-HTTP-block temp table that captures the response. Each block gets its own fresh temp table
+    // (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified.
+    // A file with ONE HTTP block uses "Name"; a file with 2+ blocks uses "MultiNamePattern" where {n} is
+    // the 1-based block ordinal (_response_1, _response_2, ...). Per-block override: `# @response <name>`.
+    // A null/empty column name omits that column.
+    //
+    "ResponseTempTable": {
+      "Name": "_response",
+      "MultiNamePattern": "_response_{n}",
+      "Columns": {
+        "Status": "status",
+        "Body": "body",
+        "ContentType": "content_type",
+        "Headers": "headers",
+        "IsSuccess": "is_success"
+      }
+    },
+    //
+    // Run-once setup, BEFORE endpoint discovery. Command steps run first (provision infra, e.g. docker),
+    // then SqlFile/Sql steps (migrations/seed) — declared order preserved within each group. Each entry:
+    //   { "Command": "...", "WorkingDirectory": "..." } | { "SqlFile": "..." } | { "Sql": "..." }
+    //
+    "Setup": [],
+    //
+    // Run-once teardown, ALWAYS (best-effort), reverse order: SqlFile/Sql first, then Command. `Keep` skips it.
+    //
+    "Teardown": []
+  },
+
   //
   // Command retry strategies and options for client and middleware commands.
   //
@@ -2908,6 +2987,12 @@
       //
       "FilePattern": "",
       //
+      // Glob (same semantics as FilePattern) for files to EXCLUDE from endpoint discovery.
+      // Default "*.test.sql" so co-located SQL test files (run by the test runner, see "TestRunner")
+      // are never exposed as endpoints. Empty string disables the exclusion.
+      //
+      "SkipPattern": "*.test.sql",
+      //
       // How comment annotations are processed for SQL file endpoints.
       // Possible values: Ignore, ParseAll, OnlyAnnotated, OnlyWithHttpTag.
       // OnlyAnnotated (default; OnlyWithHttpTag is a back-compat alias) requires an explicit
diff --git a/NpgsqlRestTests/TestRunnerTests/ParserTests/HttpFileRequestParserTests.cs b/NpgsqlRestTests/TestRunnerTests/ParserTests/HttpFileRequestParserTests.cs
new file mode 100644
index 00000000..09ca1252
--- /dev/null
+++ b/NpgsqlRestTests/TestRunnerTests/ParserTests/HttpFileRequestParserTests.cs
@@ -0,0 +1,129 @@
+using NpgsqlRestClient.Testing;
+
+namespace NpgsqlRestTests.TestRunnerTests.ParserTests;
+
+public class HttpFileRequestParserTests
+{
+    private static HttpStep Parse(string body)
+    {
+        var step = HttpFileRequestParser.TryParse(body, 1);
+        step.Should().NotBeNull("the block should be recognized as an HTTP request");
+        return step!;
+    }
+
+    [Fact]
+    public void Get_With_Path_Is_Recognized()
+    {
+        var s = Parse("GET /get-users");
+        s.Method.Should().Be("GET");
+        s.Path.Should().Be("/get-users");
+        s.Body.Should().BeNull();
+    }
+
+    [Fact]
+    public void Query_String_Is_Kept_In_Path()
+    {
+        Parse("GET /users?active=true&role=admin").Path.Should().Be("/users?active=true&role=admin");
+    }
+
+    [Fact]
+    public void Leading_Http_Keyword_Is_Tolerated()
+    {
+        var s = Parse("HTTP POST /things");
+        s.Method.Should().Be("POST");
+        s.Path.Should().Be("/things");
+    }
+
+    [Fact]
+    public void Method_Is_Case_Insensitive_And_Uppercased()
+    {
+        Parse("post /things").Method.Should().Be("POST");
+    }
+
+    [Fact]
+    public void Trailing_Http_Version_Is_Ignored()
+    {
+        var s = Parse("GET /users HTTP/1.1");
+        s.Method.Should().Be("GET");
+        s.Path.Should().Be("/users");
+    }
+
+    [Theory]
+    [InlineData("this is just a note")]
+    [InlineData("/api/foo")]                 // no method
+    [InlineData("GET the data")]             // path doesn't start with '/'
+    [InlineData("PATCH /things")]            // method not in GET|PUT|POST|DELETE
+    [InlineData("HEAD /things")]
+    [InlineData("GET /data from the cache")] // trailing junk that isn't a version
+    [InlineData("")]
+    public void Non_Request_Blocks_Are_Not_Recognized(string body)
+    {
+        HttpFileRequestParser.TryParse(body, 1).Should().BeNull();
+    }
+
+    [Fact]
+    public void Headers_Are_Parsed_Until_Blank_Line()
+    {
+        var s = Parse("POST /things\nContent-Type: application/json\nX-Trace: abc\n\n{\"a\":1}");
+        s.Headers.Should().HaveCount(2);
+        s.Headers.Should().Contain(("Content-Type", "application/json"));
+        s.Headers.Should().Contain(("X-Trace", "abc"));
+        s.Body.Should().Be("{\"a\":1}");
+    }
+
+    [Fact]
+    public void Claim_Directive_Adds_Claim()
+    {
+        var s = Parse("POST /things\n# @claim user_id=123\n\n{}");
+        s.Claims.Should().ContainSingle()
+            .Which.Should().Be(("user_id", "123"));
+    }
+
+    [Fact]
+    public void Repeated_Claim_Type_Yields_Multiple_Values()
+    {
+        var s = Parse("POST /things\n# @claim roles=admin\n# @claim roles=editor\n\n{}");
+        s.Claims.Should().HaveCount(2);
+        s.Claims.Should().Contain(("roles", "admin"));
+        s.Claims.Should().Contain(("roles", "editor"));
+    }
+
+    [Fact]
+    public void Expect_Status_And_Response_Directives_Are_Parsed()
+    {
+        var s = Parse("GET /x\n# @expect-status 404\n# @response listing");
+        s.ExpectStatus.Should().Be(404);
+        s.ResponseTable.Should().Be("listing");
+    }
+
+    [Fact]
+    public void Double_Slash_Comment_And_Directive_Variants_Work()
+    {
+        var s = Parse("// a note\nGET /x\n// @claim user_id=7");
+        s.Method.Should().Be("GET");
+        s.Claims.Should().ContainSingle().Which.Value.Should().Be("7");
+    }
+
+    [Fact]
+    public void Leading_Comment_Lines_Before_Request_Are_Skipped()
+    {
+        var s = Parse("# create the thing\nPOST /things\n\n{\"name\":\"x\"}");
+        s.Method.Should().Be("POST");
+        s.Body.Should().Be("{\"name\":\"x\"}");
+    }
+
+    [Fact]
+    public void Body_With_Colons_Is_Not_Parsed_As_Headers()
+    {
+        var s = Parse("POST /things\n\n{\"url\": \"http://x\", \"k\": \"v\"}");
+        s.Headers.Should().BeEmpty();
+        s.Body.Should().Be("{\"url\": \"http://x\", \"k\": \"v\"}");
+    }
+
+    [Fact]
+    public void Multiline_Body_Is_Preserved()
+    {
+        var s = Parse("POST /things\n\n{\n  \"a\": 1\n}");
+        s.Body.Should().Be("{\n  \"a\": 1\n}");
+    }
+}
diff --git a/NpgsqlRestTests/TestRunnerTests/ParserTests/SqlTestFileParserTests.cs b/NpgsqlRestTests/TestRunnerTests/ParserTests/SqlTestFileParserTests.cs
new file mode 100644
index 00000000..d5d5cb44
--- /dev/null
+++ b/NpgsqlRestTests/TestRunnerTests/ParserTests/SqlTestFileParserTests.cs
@@ -0,0 +1,131 @@
+using NpgsqlRestClient.Testing;
+
+namespace NpgsqlRestTests.TestRunnerTests.ParserTests;
+
+public class SqlTestFileParserTests
+{
+    [Fact]
+    public void Single_Statement_Yields_One_Sql_Step()
+    {
+        var steps = SqlTestFileParser.Parse("select 1;");
+        steps.Should().ContainSingle();
+        var sql = steps[0].Should().BeOfType<SqlStep>().Subject;
+        sql.Text.Should().Be("select 1");
+        sql.IsDoBlock.Should().BeFalse();
+    }
+
+    [Fact]
+    public void Two_Statements_Split_On_Semicolon()
+    {
+        var steps = SqlTestFileParser.Parse("select 1;\nselect 2;");
+        steps.Should().HaveCount(2);
+        steps.Should().AllBeOfType<SqlStep>();
+        ((SqlStep)steps[0]).Text.Should().Be("select 1");
+        ((SqlStep)steps[1]).Text.Should().Be("select 2");
+    }
+
+    [Fact]
+    public void Trailing_Statement_Without_Semicolon_Is_Flushed()
+    {
+        var steps = SqlTestFileParser.Parse("select 1;\nselect 2");
+        steps.Should().HaveCount(2);
+        ((SqlStep)steps[1]).Text.Should().Be("select 2");
+    }
+
+    [Fact]
+    public void Do_Block_Is_A_Single_Step_With_Inner_Semicolons_Kept()
+    {
+        var sqlText = "do $$\nbegin\n  insert into t values (1);\n  assert true, 'x';\nend;\n$$;";
+        var steps = SqlTestFileParser.Parse(sqlText);
+        steps.Should().ContainSingle();
+        var sql = (SqlStep)steps[0];
+        sql.IsDoBlock.Should().BeTrue();
+        sql.Text.Should().Contain("insert into t values (1)");
+        sql.Text.Should().Contain("assert true");
+    }
+
+    [Fact]
+    public void Semicolon_Inside_Single_Quote_Does_Not_Split()
+    {
+        var steps = SqlTestFileParser.Parse("select 'a;b' as v;");
+        steps.Should().ContainSingle();
+        ((SqlStep)steps[0]).Text.Should().Be("select 'a;b' as v");
+    }
+
+    [Fact]
+    public void Escaped_Quote_Inside_String_Is_Handled()
+    {
+        var steps = SqlTestFileParser.Parse("select 'O''Reilly; co' as v;");
+        steps.Should().ContainSingle();
+        ((SqlStep)steps[0]).Text.Should().Be("select 'O''Reilly; co' as v");
+    }
+
+    [Fact]
+    public void Tagged_Dollar_Quote_With_Inner_Semicolon()
+    {
+        var steps = SqlTestFileParser.Parse("select $tag$ a; b $tag$ as v;");
+        steps.Should().ContainSingle();
+        ((SqlStep)steps[0]).Text.Should().Contain("$tag$ a; b $tag$");
+    }
+
+    [Fact]
+    public void Line_Comments_Are_Ignored()
+    {
+        var steps = SqlTestFileParser.Parse("-- a note\nselect 1; -- trailing\nselect 2;");
+        steps.Should().HaveCount(2);
+    }
+
+    [Fact]
+    public void NonHttp_Block_Comment_Is_Ignored()
+    {
+        var steps = SqlTestFileParser.Parse("/* just a note */\nselect 1;");
+        steps.Should().ContainSingle().Which.Should().BeOfType<SqlStep>();
+    }
+
+    [Fact]
+    public void Http_Block_Between_Statements_Preserves_Order()
+    {
+        var sqlText =
+            "insert into t values (1);\n" +
+            "/*\nGET /x\n*/\n" +
+            "do $$ begin assert (select status from _response) = 200; end $$;";
+        var steps = SqlTestFileParser.Parse(sqlText);
+        steps.Should().HaveCount(3);
+        steps[0].Should().BeOfType<SqlStep>();
+        steps[1].Should().BeOfType<HttpStep>();
+        steps[2].Should().BeOfType<SqlStep>();
+        var http = (HttpStep)steps[1];
+        http.Method.Should().Be("GET");
+        http.Path.Should().Be("/x");
+    }
+
+    [Fact]
+    public void Http_Block_First_Yields_Http_Step_First()
+    {
+        var steps = SqlTestFileParser.Parse("/*\nPOST /things\n\n{\"a\":1}\n*/\nselect 1;");
+        steps.Should().HaveCount(2);
+        steps[0].Should().BeOfType<HttpStep>();
+        ((HttpStep)steps[0]).Body.Should().Be("{\"a\":1}");
+        steps[1].Should().BeOfType<SqlStep>();
+    }
+
+    [Fact]
+    public void Line_Numbers_Are_Tracked()
+    {
+        var sqlText = "select 1;\n\n/*\nGET /x\n*/\nselect 2;";
+        var steps = SqlTestFileParser.Parse(sqlText);
+        steps.Should().HaveCount(3);
+        steps[0].LineNumber.Should().Be(1);   // select 1
+        steps[1].LineNumber.Should().Be(3);   // /* opens on line 3
+        steps[2].LineNumber.Should().Be(6);   // select 2
+    }
+
+    [Fact]
+    public void Block_Comment_In_Middle_Of_Statement_Is_Stripped()
+    {
+        var steps = SqlTestFileParser.Parse("select /* note */ 1;");
+        steps.Should().ContainSingle();
+        ((SqlStep)steps[0]).Text.Should().StartWith("select");
+        ((SqlStep)steps[0]).Text.Should().EndWith("1");
+    }
+}
diff --git a/changelog/v3.19.0.md b/changelog/v3.19.0.md
new file mode 100644
index 00000000..f5ef3c21
--- /dev/null
+++ b/changelog/v3.19.0.md
@@ -0,0 +1,46 @@
+# Changelog v3.19.0
+
+## Version [3.19.0](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.19.0) (2026-06-30)
+
+[Full Changelog](https://github.com/NpgsqlRest/NpgsqlRest/compare/3.18.2...3.19.0)
+
+Minor release adding two small, independent configuration options: a **skip glob for the SQL file source** (exclude files from endpoint discovery) and the ability to **mute an individual logger** via `Log:MinimalLevels`.
+
+## What changed
+
+### 1. `SqlFileSource.SkipPattern` — exclude files from endpoint discovery
+
+New option **`SkipPattern`** on the SQL file source (config key `NpgsqlRest:SqlFileSource:SkipPattern`, default **`"*.test.sql"`**). Files whose full path matches this glob are excluded from endpoint discovery: a `.sql` file becomes an endpoint only when it matches **`FilePattern`** *and* does **not** match **`SkipPattern`**.
+
+This lets you keep auxiliary `.sql` files that live alongside your endpoint files — for example co-located SQL files following the `*.test.sql` naming convention — without them being turned into HTTP endpoints. The pattern uses the same glob engine and semantics as `FilePattern` (`*.ext` matches by suffix). Set it to an empty string (`""`) to disable the exclusion.
+
+> **Behavior change:** the default is `"*.test.sql"`, so files matching that suffix are **no longer exposed** as endpoints out of the box. If you previously relied on serving `*.test.sql` files, set `SkipPattern` to `""` to restore the old behavior.
+
+### 2. Mute an individual logger with `"Off"` in `Log:MinimalLevels`
+
+Each entry under **`Log:MinimalLevels`** now accepts **`"Off"`** (aliases **`"None"`** and **`"Silent"`**, case-insensitive) to **fully silence** that logger. Previously the only accepted values were the Serilog levels `Verbose…Fatal`, and there was no way to turn a logger off completely.
+
+- `"Off"` / `"None"` / `"Silent"` → the logger emits nothing (implemented as a minimum level above `Fatal`, since Serilog's `LogEventLevel` has no native "off").
+- `null`, an omitted key, or an unrecognized value → unchanged: the logger keeps its built-in default level.
+
+Each named logger is controlled independently, so you can, for example, mute the `System`/`Microsoft` framework logs entirely while keeping the application loggers at `Information`:
+
+```json
+"Log": {
+  "MinimalLevels": {
+    "NpgsqlRest": "Information",
+    "NpgsqlRestClient": "Information",
+    "System": "Off",
+    "Microsoft": "Off"
+  }
+}
+```
+
+## Notes
+
+- Both options are wired through the client configuration: `appsettings.json`, the JSON-schema descriptions, and the `--config` template (which continues to match `appsettings.json` byte-for-byte).
+- Fully additive apart from the `SkipPattern` default noted above; no API changes.
+
+## Tests
+
+Full test suite green (2334). The new configuration keys are covered by the configuration round-trip tests (the `--config` template output matches `appsettings.json`).
diff --git a/plugins/NpgsqlRest.SqlFileSource/SqlFileSource.cs b/plugins/NpgsqlRest.SqlFileSource/SqlFileSource.cs
index 493f53b0..7edf6c19 100644
--- a/plugins/NpgsqlRest.SqlFileSource/SqlFileSource.cs
+++ b/plugins/NpgsqlRest.SqlFileSource/SqlFileSource.cs
@@ -24,7 +24,7 @@ public class SqlFileSource(SqlFileSourceOptions options) : IEndpointSource
             yield break;
         }
 
-        var files = FindMatchingFiles(options.FilePattern).ToArray();
+        var files = FindMatchingFiles(options.FilePattern, options.SkipPattern).ToArray();
         if (files.Length == 0)
         {
             NpgsqlRestOptions.Logger?.LogWarning("SqlFileSource: No SQL files found matching pattern \"{FilePattern}\"", options.FilePattern);
@@ -619,7 +619,7 @@ and a.attnum > 0 and not a.attisdropped
     /// Find files matching the glob pattern. Splits the pattern into a base directory
     /// and a file pattern, then lazily enumerates matching files.
     /// </summary>
-    internal static IEnumerable<string> FindMatchingFiles(string filePattern)
+    internal static IEnumerable<string> FindMatchingFiles(string filePattern, string? skipPattern = null)
     {
         // Find the base directory (everything before the first wildcard)
         int firstWildcard = filePattern.IndexOfAny(['*', '?']);
@@ -658,10 +658,12 @@ internal static IEnumerable<string> FindMatchingFiles(string filePattern)
         bool isRecursive = filePattern.Contains("**");
         var searchOption = isRecursive ? SearchOption.AllDirectories : SearchOption.TopDirectoryOnly;
 
+        bool hasSkip = !string.IsNullOrEmpty(skipPattern);
         foreach (var file in Directory.EnumerateFiles(baseDir, "*", searchOption))
         {
             var normalizedFile = file.Replace('\\', '/');
-            if (Parser.IsPatternMatch(normalizedFile, pattern))
+            if (Parser.IsPatternMatch(normalizedFile, pattern)
+                && !(hasSkip && Parser.IsPatternMatch(normalizedFile, skipPattern!)))
             {
                 yield return file;
             }
diff --git a/plugins/NpgsqlRest.SqlFileSource/SqlFileSourceOptions.cs b/plugins/NpgsqlRest.SqlFileSource/SqlFileSourceOptions.cs
index 4d093e03..094eac65 100644
--- a/plugins/NpgsqlRest.SqlFileSource/SqlFileSourceOptions.cs
+++ b/plugins/NpgsqlRest.SqlFileSource/SqlFileSourceOptions.cs
@@ -34,6 +34,13 @@ public class SqlFileSourceOptions
     /// </summary>
     public string FilePattern { get; set; } = "";
 
+    /// <summary>
+    /// Glob (same semantics as <see cref="FilePattern"/>) for files to EXCLUDE from endpoint discovery.
+    /// Default "*.test.sql" so co-located SQL test files (run by the test runner) are never exposed as
+    /// endpoints. Empty disables the exclusion. Matched against the full path; "*.ext" matches by suffix.
+    /// </summary>
+    public string SkipPattern { get; set; } = "*.test.sql";
+
     /// <summary>
     /// How comment annotations are processed for this source.
     /// Default is OnlyWithHttpTag — SQL files must contain an explicit HTTP annotation

From 0a20ec9b12bb9982632374b7e78a7442d55cf267 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Thu, 2 Jul 2026 11:22:21 +0200
Subject: [PATCH 13/25] feat(test-runner): test database support, per-assertion
 hardening, changelog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Test database / separate test connection:
- TestRunner.ConnectionName: run tests (endpoint Describe + execution) against
  a named ConnectionStrings entry instead of the app's main connection; not
  opened/validated at startup, so a Setup step can create the database first.
- Per-step ConnectionName on Setup/Teardown Sql/SqlFile steps (e.g. an Admin
  maintenance connection running `create database`); runner issues no DDL of
  its own. Steps now run in the exact order written (dropped Command-first
  grouping). BuildTestRunnerConnectionStrings resolves entries unvalidated.
- {rnd1}..{rnd10} config placeholders: random lowercase tokens (length =
  digit), generated once per run, substituted everywhere {ENV} works — one
  stable name across connection string, create, and drop.

Hardening round (full-feature review):
- `# @expect-status` removed — assert on the response temp table's status
  column instead; HTTP blocks are pure act steps.
- Code generation (HTTP files, TS client, OpenAPI) skipped in --test mode —
  a test run never rewrites generated artifacts.
- login/logout endpoints rejected in test mode with a clear error (inject
  the principal with `# @claim` instead).
- Request matching no endpoint logs a warning (path typo / missing /api
  prefix) — the 404 remains assertable.
- Per-step exception attribution: errors thrown by HTTP steps (e.g. 42P07
  duplicate `# @response` table) report with the block's file:line.

Rename: TestRunner.Verbose -> DetailedReport (detailed console report:
passed ✓ lines, full failing SQL, notices for passing tests) — removes the
collision with the Serilog "Verbose" level in Log:MinimalLevels.

changelog/v3.19.0.md rewritten: SQL test runner documented as the headline
feature with a full user manual (execution model, file anatomy, HTTP-block
syntax, response temp tables, Setup/Teardown, test-database workflow,
reporting, logging, config reference), plus SqlFileSource.SkipPattern and
MinimalLevels "Off".

Config synced across appsettings.json, ConfigTemplate.cs, ConfigDefaults.cs,
ConfigSchemaGenerator.cs. Full suite green (2334); examples 19 + 20 verified
end-to-end (fresh {rnd}-named test DB created, migrated, tested, dropped).
---
 NpgsqlRestClient/App.cs                       |  13 +-
 NpgsqlRestClient/Builder.cs                   |  74 +++++-
 NpgsqlRestClient/Config.cs                    |  21 ++
 NpgsqlRestClient/ConfigDefaults.cs            |   3 +-
 NpgsqlRestClient/ConfigSchemaGenerator.cs     |   7 +-
 NpgsqlRestClient/ConfigTemplate.cs            |  24 +-
 NpgsqlRestClient/Program.cs                   |   4 +-
 .../Testing/HttpFileRequestParser.cs          |  12 +-
 NpgsqlRestClient/Testing/TestRunner.cs        | 150 +++++++----
 NpgsqlRestClient/Testing/TestRunnerOptions.cs |  26 +-
 NpgsqlRestClient/Testing/TestStep.cs          |   4 -
 NpgsqlRestClient/appsettings.json             |  24 +-
 .../ParserTests/HttpFileRequestParserTests.cs |   5 +-
 changelog/v3.19.0.md                          | 251 +++++++++++++++++-
 14 files changed, 499 insertions(+), 119 deletions(-)

diff --git a/NpgsqlRestClient/App.cs b/NpgsqlRestClient/App.cs
index dd55f2b6..ba97954b 100644
--- a/NpgsqlRestClient/App.cs
+++ b/NpgsqlRestClient/App.cs
@@ -463,10 +463,17 @@ public string CreateUrl(Routine routine, NpgsqlRestOptions options) =>
     public List<IEndpointCreateHandler> CreateCodeGenHandlers(string connectionString, string[] args)
     {
         List<IEndpointCreateHandler> handlers = new(3);
-        if (args.Any(a => string.Equals(a, "--endpoints", StringComparison.OrdinalIgnoreCase)
-            || string.Equals(a, "--test", StringComparison.OrdinalIgnoreCase)))
+        if (args.Any(a => string.Equals(a, "--test", StringComparison.OrdinalIgnoreCase)))
+        {
+            // Test mode: only capture endpoints for the runner (kind pre-checks: SSE/upload/login/outbound).
+            // Code generation (HTTP files, TS client, OpenAPI) is deliberately skipped so a test run never
+            // rewrites generated artifacts as a side effect.
+            handlers.Add(new EndpointCapture());
+            _builder.TestLogger?.LogDebug("code generation handlers skipped in test mode");
+            return handlers;
+        }
+        if (args.Any(a => string.Equals(a, "--endpoints", StringComparison.OrdinalIgnoreCase)))
         {
-            // --test also captures endpoints so the runner can pre-check kinds (SSE/upload/outbound).
             handlers.Add(new EndpointCapture());
         }
         var httpFilecfg = _config.NpgsqlRestCfg.GetSection("HttpFileOptions");
diff --git a/NpgsqlRestClient/Builder.cs b/NpgsqlRestClient/Builder.cs
index d6ce259a..882ba793 100644
--- a/NpgsqlRestClient/Builder.cs
+++ b/NpgsqlRestClient/Builder.cs
@@ -1724,10 +1724,11 @@ public bool BuildForwardedHeaders()
     }
 
     private (string?, ConnectionRetryOptions) BuildConnection(
-        string? connectionName, 
-        string connectionString, 
+        string? connectionName,
+        string connectionString,
         bool isMain,
-        bool skipRetryOpts)
+        bool skipRetryOpts,
+        bool skipValidation = false)
     {
         if (_config.EnvDict is not null)
         {
@@ -1807,7 +1808,7 @@ public bool BuildForwardedHeaders()
                     string.Join(",", retryOptions.Strategy.ErrorCodes));
             }
         }
-        if (_config.GetConfigBool("TestConnectionStrings", _config.ConnectionSettingsCfg, true) is true)
+        if (skipValidation is false && _config.GetConfigBool("TestConnectionStrings", _config.ConnectionSettingsCfg, true) is true)
         {
             using var conn = new NpgsqlConnection(connectionString);
             try
@@ -1823,10 +1824,37 @@ public bool BuildForwardedHeaders()
         return (connectionString, retryOptions);
     }
 
-    public (string?, ConnectionRetryOptions) BuildConnectionString()
+    public (string?, ConnectionRetryOptions) BuildConnectionString(bool testMode = false)
     {
         string? connectionString;
-        string? connectionName = _config.GetConfigStr("ConnectionName", _config.NpgsqlRestCfg);
+        string? connectionName = null;
+        bool skipValidation = false;
+
+        // In test mode a dedicated TestRunner.ConnectionName (when set) becomes the app's main connection,
+        // so endpoint Describe + execution run against the TEST database. That database may not exist until
+        // TestRunner.Setup creates it (which runs after this), so it is NOT opened/validated here — it is
+        // first touched by Setup / Describe, by which point Setup has created it.
+        if (testMode)
+        {
+            connectionName = _config.GetConfigStr("ConnectionName", _config.Cfg.GetSection("TestRunner"));
+            if (connectionName is not null)
+            {
+                connectionString = _config.Cfg.GetConnectionString(connectionName);
+                skipValidation = true;
+                if (connectionString is null)
+                {
+                    throw new InvalidOperationException(
+                        $"TestRunner.ConnectionName is '{connectionName}', but there is no matching entry under 'ConnectionStrings'.");
+                }
+                var (testResult, testRetryOpts) = BuildConnection(connectionName, connectionString, isMain: true, skipRetryOpts: false, skipValidation: true);
+                AppContext.SetSwitch("Npgsql.EnableSqlRewriting", false);
+                ConnectionString = testResult;
+                ConnectionName = connectionName;
+                return (testResult, testRetryOpts);
+            }
+        }
+
+        connectionName = _config.GetConfigStr("ConnectionName", _config.NpgsqlRestCfg);
         if (connectionName is not null)
         {
             connectionString = _config.Cfg.GetConnectionString(connectionName);
@@ -1846,7 +1874,7 @@ public bool BuildForwardedHeaders()
                 "or set the PGHOST, PGDATABASE, PGUSER, and PGPASSWORD environment variables with 'Config.AddEnvironmentVariables: true'.");
         }
 
-        var (result, retryOpts) = BuildConnection(connectionName, connectionString!, isMain: true, skipRetryOpts: false);
+        var (result, retryOpts) = BuildConnection(connectionName, connectionString!, isMain: true, skipRetryOpts: false, skipValidation: skipValidation);
 
         // disable SQL rewriting to ensure that NpgsqlRest works with this option OFF.
         AppContext.SetSwitch("Npgsql.EnableSqlRewriting", false);
@@ -1879,6 +1907,34 @@ public IDictionary<string, string> BuildConnectionStringDict()
         return result.ToFrozenDictionary();
     }
 
+    /// <summary>
+    /// Resolves every <c>ConnectionStrings</c> entry (env/{rnd} placeholders substituted, pooling disabled)
+    /// into a name→connection-string map for the SQL test runner's Setup/Teardown <c>ConnectionName</c>
+    /// steps. Unlike <see cref="BuildConnectionStringDict"/> this does NOT open/validate the connections —
+    /// a test database referenced here may not exist until a Setup step creates it.
+    /// </summary>
+    public Dictionary<string, string> BuildTestRunnerConnectionStrings()
+    {
+        var result = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+        foreach (var section in _config.Cfg.GetSection("ConnectionStrings").GetChildren())
+        {
+            if (string.IsNullOrEmpty(section?.Key) || string.IsNullOrEmpty(section.Value))
+            {
+                continue;
+            }
+            var cs = section.Value;
+            if (_config.EnvDict is not null)
+            {
+                cs = Formatter.FormatString(cs.AsSpan(), _config.EnvDict).ToString();
+            }
+            // Non-pooled: maintenance/test sessions are short-lived and must not linger (a pooled session
+            // would block DROP DATABASE in a Teardown step).
+            var b = new NpgsqlConnectionStringBuilder(cs) { Pooling = false, Enlist = false };
+            result[section.Key] = b.ConnectionString;
+        }
+        return result;
+    }
+
     private string? _instanceId = null;
 
     public string InstanceId
@@ -3012,12 +3068,13 @@ public TestRunnerOptions BuildTestRunnerOptions()
         if (section.Exists() is false) return opt;
 
         opt.FilePattern = _config.GetConfigStr("FilePattern", section) ?? "";
+        opt.ConnectionName = _config.GetConfigStr("ConnectionName", section);
         opt.MaxParallelism = _config.GetConfigInt("MaxParallelism", section) ?? 0;
         opt.FailFast = _config.GetConfigBool("FailFast", section, false);
         opt.PerTestTimeout = ParseTestTimeout(_config.GetConfigStr("PerTestTimeout", section), TimeSpan.FromSeconds(30));
         opt.JUnitOutput = _config.GetConfigStr("JUnitOutput", section);
         opt.Keep = _config.GetConfigBool("Keep", section, false);
-        opt.Verbose = _config.GetConfigBool("Verbose", section, false);
+        opt.DetailedReport = _config.GetConfigBool("DetailedReport", section, false);
         opt.AllowEmpty = _config.GetConfigBool("AllowEmpty", section, false);
 
         var rt = section.GetSection("ResponseTempTable");
@@ -3061,6 +3118,7 @@ List<TestSetupStep> ReadTestSteps(IConfigurationSection stepsSection)
                     SqlFile = _config.GetConfigStr("SqlFile", child),
                     Command = _config.GetConfigStr("Command", child),
                     WorkingDirectory = _config.GetConfigStr("WorkingDirectory", child),
+                    ConnectionName = _config.GetConfigStr("ConnectionName", child),
                 };
                 if (step.Sql is not null || step.SqlFile is not null || step.Command is not null)
                 {
diff --git a/NpgsqlRestClient/Config.cs b/NpgsqlRestClient/Config.cs
index 55b257e0..2678f8cf 100644
--- a/NpgsqlRestClient/Config.cs
+++ b/NpgsqlRestClient/Config.cs
@@ -105,6 +105,14 @@ public void Build(string[] args, string[] skip)
             {
                 EnvDict.Add(key.ToString()!, envVars[key.ToString()!]?.ToString()!);
             }
+            // {rnd1}..{rnd10}: random lowercase tokens (length = the trailing digit) generated once per
+            // process and stable across the whole config — usable wherever {ENV} placeholders are
+            // (connection strings, TestRunner Setup/Teardown). E.g. a test DB named per run:
+            //   "ConnectionStrings:Test": "...;Database=app_test_{rnd6};..."  +  "create database app_test_{rnd6}".
+            for (int n = 1; n <= 10; n++)
+            {
+                EnvDict[string.Concat("rnd", n.ToString(System.Globalization.CultureInfo.InvariantCulture))] = RandomToken(n);
+            }
         }
 
         UseJsonApplicationName = GetConfigBool("UseJsonApplicationName", ConnectionSettingsCfg);
@@ -151,6 +159,19 @@ public bool GetConfigBool(string key, IConfiguration? subsection = null, bool de
         };
     }
 
+    // A random lowercase-letter token of the given length, used for the {rnd1}..{rnd10} config placeholders.
+    private static string RandomToken(int length)
+    {
+        const string chars = "abcdefghijklmnopqrstuvwxyz";
+        return string.Create(length, chars, static (span, c) =>
+        {
+            for (int i = 0; i < span.Length; i++)
+            {
+                span[i] = c[Random.Shared.Next(c.Length)];
+            }
+        });
+    }
+
     // True when the value still contains a {TOKEN} placeholder, i.e. an environment variable that was
     // not resolved because it is not set. Typed config values (bool/int) never legitimately contain
     // braces, so an unresolved token is unambiguously a missing-env-var, not a real value.
diff --git a/NpgsqlRestClient/ConfigDefaults.cs b/NpgsqlRestClient/ConfigDefaults.cs
index 93e5ab26..b47ec6da 100644
--- a/NpgsqlRestClient/ConfigDefaults.cs
+++ b/NpgsqlRestClient/ConfigDefaults.cs
@@ -1101,12 +1101,13 @@ private static JsonObject GetTestRunnerDefaults()
         return new JsonObject
         {
             ["FilePattern"] = "",
+            ["ConnectionName"] = "",
             ["MaxParallelism"] = 0,
             ["FailFast"] = false,
             ["PerTestTimeout"] = "30s",
             ["JUnitOutput"] = null,
             ["Keep"] = false,
-            ["Verbose"] = false,
+            ["DetailedReport"] = false,
             ["AllowEmpty"] = false,
             ["LoggerName"] = "NpgsqlRestTest",
             ["ResponseTempTable"] = new JsonObject
diff --git a/NpgsqlRestClient/ConfigSchemaGenerator.cs b/NpgsqlRestClient/ConfigSchemaGenerator.cs
index e84405cb..959d8a45 100644
--- a/NpgsqlRestClient/ConfigSchemaGenerator.cs
+++ b/NpgsqlRestClient/ConfigSchemaGenerator.cs
@@ -248,19 +248,20 @@ public static partial class ConfigSchemaGenerator
         ["Stats:ActivityPath"] = "Path for current database activity.\nReturns data from pg_stat_activity showing active sessions, queries, and wait events.\nSecurity Consideration: Shows currently running queries which may contain sensitive data.",
         ["TestRunner"] = "SQL test runner. Invoked with the `--test` command-line flag (otherwise inert).\nDiscovers *.test.sql files, runs each in an isolated non-pooled connection, can invoke endpoints in-process from an embedded `/* GET /path */` block (response captured into a temp table), and asserts via boolean-returning SELECTs or `do $$ ... assert ... $$;` blocks.\nExit codes: 0 pass, 1 failures, 2 errors, 3 config/runner error, 4 no tests found.",
         ["TestRunner:FilePattern"] = "Glob (same engine as SqlFileSource) selecting *.test.sql files. Empty disables discovery.\nCo-located convention: app.sql (endpoint) next to app.test.sql (test).",
+        ["TestRunner:ConnectionName"] = "Optional: a ConnectionStrings entry to run the tests against instead of the app's main connection.\nIn test mode it becomes the connection used for endpoint type-checking (Describe) and execution, so it can point at a dedicated test database that a Setup step creates first (it need not exist at startup). Empty = use the main connection.\nTip: {rnd1}..{rnd10} are random lowercase tokens (length = the digit), stable for the whole run, usable in any connection string or Setup/Teardown SQL (e.g. Database=app_test_{rnd6}).",
         ["TestRunner:MaxParallelism"] = "Max test files run concurrently. 0 => processor count. Each test uses its own non-pooled connection.",
         ["TestRunner:FailFast"] = "Stop scheduling new tests after the first failure/error (in-flight tests still finish).",
         ["TestRunner:PerTestTimeout"] = "Per-test timeout. Accepts \"30s\", \"5m\", \"1h\", a plain number of seconds, or \"hh:mm:ss\". 0 disables.",
         ["TestRunner:JUnitOutput"] = "Optional path to also write a JUnit XML report (console output is always printed).",
         ["TestRunner:Keep"] = "Skip Teardown so a failed run's state can be inspected.",
-        ["TestRunner:Verbose"] = "Show captured `raise notice` output for all tests, not just failed/errored ones.",
+        ["TestRunner:DetailedReport"] = "Detailed console REPORT: list passed assertions, print the full failing SQL statement, and show captured `raise notice` output for passing tests too.\nThis shapes the report only — for diagnostic logging of every executed query/HTTP call, raise the log channel instead (Log:MinimalLevels + LoggerName).",
         ["TestRunner:AllowEmpty"] = "Treat \"no tests discovered\" as success (exit 0) instead of exit 4.",
         ["TestRunner:LoggerName"] = "SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels (defaults to Information).\nDiscovery/parsing log at Debug, each query and HTTP invocation at Verbose, `raise notice` by severity. The console PASS/FAIL report is separate.",
         ["TestRunner:ResponseTempTable:Name"] = "Temp table name used when a test file has exactly ONE HTTP block.\nEach HTTP block gets its own fresh temp table (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified. Per-block override: `# @response <name>`.",
         ["TestRunner:ResponseTempTable:MultiNamePattern"] = "Temp table name pattern used when a test file has 2+ HTTP blocks.\n{n} is the 1-based block ordinal, e.g. \"_response_{n}\" => _response_1, _response_2, …",
         ["TestRunner:ResponseTempTable:Columns"] = "Maps each response component to a column name. A null or empty name omits that column.",
-        ["TestRunner:Setup"] = "Run-once setup, BEFORE endpoint discovery. Command steps run first (provision infra), then SqlFile/Sql steps (migrations/seed) — declared order preserved within each group.\nEach entry: { \"Command\": \"...\", \"WorkingDirectory\": \"...\" } | { \"SqlFile\": \"...\" } | { \"Sql\": \"...\" }.",
-        ["TestRunner:Teardown"] = "Run-once teardown, ALWAYS (best-effort), reverse order: SqlFile/Sql first, then Command (e.g. docker down). The `Keep` option skips it.",
+        ["TestRunner:Setup"] = "Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written.\nEach entry is one of: { \"Command\": \"...\", \"WorkingDirectory\": \"...\" } (OS shell); { \"Sql\": \"...\" } | { \"SqlFile\": \"...\" } which run on the test connection, or set \"ConnectionName\" to run on another ConnectionStrings entry (e.g. an admin connection that runs `create database`).",
+        ["TestRunner:Teardown"] = "Run-once teardown, ALWAYS (best-effort), in the EXACT order written. Same step shapes as Setup (e.g. a `drop database` on an admin connection). The `Keep` option skips it.",
         ["CommandRetryOptions"] = "Command retry strategies and options for client and middleware commands.",
         ["CommandRetryOptions:Strategies:default:RetrySequenceSeconds"] = "Retry sequence in seconds. Accepts decimal numbers (0.25 is quarter of a second). The length of the array determines the maximum number of retries.",
         ["CommandRetryOptions:Strategies:default:ErrorCodes"] = "Error codes that will trigger a retry when executing a command. See https://www.postgresql.org/docs/current/errcodes-appendix.html",
diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index f992f6f2..fe68090e 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -1448,6 +1448,14 @@ public static partial class ConfigSchemaGenerator
         //
         "FilePattern": "",
         //
+        // Optional: a ConnectionStrings entry to run the tests against instead of the app's main connection. In
+        // test mode it becomes the connection used for endpoint type-checking (Describe) and execution, so it can
+        // point at a dedicated test database that a Setup step creates first (it need not exist at startup).
+        // Empty = use the main connection. Tip: {rnd1}..{rnd10} are random lowercase tokens (length = the digit),
+        // stable for the whole run, usable in any connection string or Setup/Teardown SQL (e.g. Database=app_test_{rnd6}).
+        //
+        "ConnectionName": "",
+        //
         // Max test files run concurrently. 0 => processor count. Each test uses its own non-pooled connection.
         //
         "MaxParallelism": 0,
@@ -1468,9 +1476,11 @@ public static partial class ConfigSchemaGenerator
         //
         "Keep": false,
         //
-        // Show captured `raise notice` output for all tests, not just failed/errored ones.
+        // Detailed console REPORT: list passed assertions, print the full failing SQL statement, and show
+        // captured `raise notice` output for passing tests too. This shapes the report only — for diagnostic
+        // logging of every executed query/HTTP call, raise the log channel instead (Log:MinimalLevels + LoggerName).
         //
-        "Verbose": false,
+        "DetailedReport": false,
         //
         // Treat "no tests discovered" as success (exit 0) instead of exit 4.
         //
@@ -1499,13 +1509,15 @@ public static partial class ConfigSchemaGenerator
           }
         },
         //
-        // Run-once setup, BEFORE endpoint discovery. Command steps run first (provision infra, e.g. docker),
-        // then SqlFile/Sql steps (migrations/seed) — declared order preserved within each group. Each entry:
-        //   { "Command": "...", "WorkingDirectory": "..." } | { "SqlFile": "..." } | { "Sql": "..." }
+        // Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written. Each entry is one of:
+        //   { "Command": "...", "WorkingDirectory": "..." }    — runs via the OS shell
+        //   { "Sql": "..." } | { "SqlFile": "..." }            — runs on the test connection; set "ConnectionName"
+        //                                                         to run on another ConnectionStrings entry (e.g.
+        //                                                         an admin connection that runs `create database`).
         //
         "Setup": [],
         //
-        // Run-once teardown, ALWAYS (best-effort), reverse order: SqlFile/Sql first, then Command. `Keep` skips it.
+        // Run-once teardown, ALWAYS (best-effort), in the EXACT order written. `Keep` skips it. Same step shapes as Setup.
         //
         "Teardown": []
       },
diff --git a/NpgsqlRestClient/Program.cs b/NpgsqlRestClient/Program.cs
index a10031b6..5444b9b7 100644
--- a/NpgsqlRestClient/Program.cs
+++ b/NpgsqlRestClient/Program.cs
@@ -301,7 +301,7 @@
 var errorHandlingOptions = builder.BuildErrorHandlingOptions();
 var (rateLimiterDefaultPolicy, rateLimiterEnabled) = builder.BuildRateLimiter();
 
-var (connectionString, retryOpts) = builder.BuildConnectionString();
+var (connectionString, retryOpts) = builder.BuildConnectionString(testMode);
 if (connectionString is null)
 {
     return;
@@ -500,7 +500,7 @@
     var logTestNotices = options.LogConnectionNoticeEvents;
     options.LogConnectionNoticeEvents = false;
 
-    testRunner = new NpgsqlRestClient.Testing.TestRunner(options, builder.BuildTestRunnerOptions(), connectionString, builder.TestLogger, logTestNotices);
+    testRunner = new NpgsqlRestClient.Testing.TestRunner(options, builder.BuildTestRunnerOptions(), connectionString, builder.TestLogger, logTestNotices, builder.BuildTestRunnerConnectionStrings());
     if (await testRunner.SetupAsync() is false)
     {
         Environment.ExitCode = NpgsqlRestClient.Testing.TestRunner.ExitConfig;
diff --git a/NpgsqlRestClient/Testing/HttpFileRequestParser.cs b/NpgsqlRestClient/Testing/HttpFileRequestParser.cs
index e5939a60..edc05564 100644
--- a/NpgsqlRestClient/Testing/HttpFileRequestParser.cs
+++ b/NpgsqlRestClient/Testing/HttpFileRequestParser.cs
@@ -2,7 +2,7 @@ namespace NpgsqlRestClient.Testing;
 
 /// <summary>
 /// Parses a single HTTP request out of a block-comment body, using a single-request subset of the
-/// Microsoft .http syntax plus the test directives <c># @claim</c>, <c># @expect-status</c>, <c># @response</c>.
+/// Microsoft .http syntax plus the test directives <c># @claim</c> and <c># @response</c>.
 /// Returns null when the block is not an HTTP request (ordinary SQL comment).
 /// </summary>
 public static class HttpFileRequestParser
@@ -36,7 +36,6 @@ public static class HttpFileRequestParser
 
         var headers = new List<(string, string)>();
         var claims = new List<(string, string)>();
-        int? expectStatus = null;
         string? responseTable = null;
         int bodyStart = -1;
 
@@ -57,7 +56,7 @@ public static class HttpFileRequestParser
             {
                 if (directive.StartsWith('@'))
                 {
-                    ParseDirective(directive[1..].Trim(), claims, ref expectStatus, ref responseTable);
+                    ParseDirective(directive[1..].Trim(), claims, ref responseTable);
                 }
                 // plain comment line → ignore
                 continue;
@@ -79,7 +78,7 @@ public static class HttpFileRequestParser
             if (bodyText.Length > 0) body = bodyText;
         }
 
-        return new HttpStep(method, path, headers, claims, body, expectStatus, responseTable, lineNumber);
+        return new HttpStep(method, path, headers, claims, body, responseTable, lineNumber);
     }
 
     // [HTTP] METHOD /path [HTTP/x]. Method required (GET|PUT|POST|DELETE); path must start with '/';
@@ -123,7 +122,6 @@ private static bool TryParseRequestLine(string line, out string method, out stri
     private static void ParseDirective(
         string directive,
         List<(string, string)> claims,
-        ref int? expectStatus,
         ref string? responseTable)
     {
         int sp = directive.IndexOfAny([' ', '\t']);
@@ -138,10 +136,6 @@ private static void ParseDirective(
                 claims.Add((rest[..eq].Trim(), rest[(eq + 1)..].Trim()));
             }
         }
-        else if (string.Equals(keyword, "expect-status", StringComparison.OrdinalIgnoreCase))
-        {
-            if (int.TryParse(rest, out var code)) expectStatus = code;
-        }
         else if (string.Equals(keyword, "response", StringComparison.OrdinalIgnoreCase))
         {
             if (rest.Length > 0) responseTable = rest;
diff --git a/NpgsqlRestClient/Testing/TestRunner.cs b/NpgsqlRestClient/Testing/TestRunner.cs
index 2e55446d..07386f8d 100644
--- a/NpgsqlRestClient/Testing/TestRunner.cs
+++ b/NpgsqlRestClient/Testing/TestRunner.cs
@@ -33,6 +33,7 @@ public sealed class TestRunner
     private readonly NpgsqlRestOptions _rest;
     private readonly TestRunnerOptions _opt;
     private readonly string _connString;
+    private readonly IReadOnlyDictionary<string, string> _named;
     private readonly ILogger? _log;
     private readonly bool _logNotices;
     private readonly Out _out = new();
@@ -44,9 +45,9 @@ private enum Outcome { Pass, Fail, Error }
     // only becomes a result when it errors). Name/Message describe the assertion when Emit=true.
     private readonly record struct StepResult(bool Emit, Outcome Outcome, string? Message, string? Name);
 
-    // One reported test = one assertion: a boolean-returning SELECT, a DO block (passes unless it raises,
-    // e.g. via ASSERT), or an HTTP step with `# @expect-status`. Errors from any step are also recorded
-    // here so they surface and count.
+    // One reported test = one assertion: a boolean-returning SELECT, or a DO block (passes unless it
+    // raises, e.g. via ASSERT). Errors from any step (SQL or HTTP) are also recorded here so they surface
+    // and count.
     private sealed class AssertionResult
     {
         public required string Name { get; init; }
@@ -71,12 +72,17 @@ private sealed class FileResult
             Outcome.Pass;
     }
 
-    public TestRunner(NpgsqlRestOptions rest, TestRunnerOptions opt, string baseConnectionString, ILogger? logger, bool logConnectionNotices = false)
+    public TestRunner(NpgsqlRestOptions rest, TestRunnerOptions opt, string baseConnectionString, ILogger? logger,
+        bool logConnectionNotices = false, IReadOnlyDictionary<string, string>? namedConnections = null)
     {
         _rest = rest;
         _opt = opt;
         // Always non-pooled: a fresh physical session per test (no temp-table / GUC / prepared-statement carryover).
+        // In test mode baseConnectionString is already the test connection (TestRunner.ConnectionName, when set).
         _connString = new NpgsqlConnectionStringBuilder(baseConnectionString) { Pooling = false }.ConnectionString;
+        // Named ConnectionStrings entries for Setup/Teardown steps that target another connection (e.g. an
+        // "Admin" maintenance connection that runs create/drop database).
+        _named = namedConnections ?? new Dictionary<string, string>();
         _log = logger;
         _logNotices = logConnectionNotices;
         // Wire the ambient accessor once; null when no test flow is active → zero effect on discovery/normal ops.
@@ -91,21 +97,14 @@ public async Task<bool> SetupAsync(CancellationToken ct = default)
             // Response-table names are validated and created per HTTP block (no pre-run permanent-table
             // collision check needed: writes are pg_temp-qualified and CREATE TEMP TABLE (no IF NOT EXISTS)
             // fails loudly on a real duplicate).
-            _log?.LogDebug("setup: {Commands} command(s), {Sql} sql step(s)",
-                _opt.Setup.Count(s => s.IsCommand), _opt.Setup.Count(s => !s.IsCommand));
+            _log?.LogDebug("setup: {Count} step(s)", _opt.Setup.Count);
 
-            // Commands first (provision infra), then SqlFile/Sql (migrations/seed), in declared order within each group.
-            foreach (var step in _opt.Setup.Where(s => s.IsCommand))
+            // Strict declared order: each step runs in the order it is written (no Command-first grouping).
+            // To run something first, write it first. Each Sql/SqlFile step runs on its own connection
+            // (ConnectionName, else the test connection); Command steps run via the OS shell.
+            foreach (var step in _opt.Setup)
             {
-                await RunCommandAsync(step, ct);
-            }
-            await using (var conn = new NpgsqlConnection(_connString))
-            {
-                await conn.OpenAsync(ct);
-                foreach (var step in _opt.Setup.Where(s => !s.IsCommand))
-                {
-                    await RunSqlStepAsync(conn, step, ct);
-                }
+                await RunStepAsync(step, ct);
             }
             return true;
         }
@@ -118,6 +117,35 @@ public async Task<bool> SetupAsync(CancellationToken ct = default)
         }
     }
 
+    // Runs one Setup/Teardown step: a shell Command, or a Sql/SqlFile batch on its resolved connection.
+    private async Task RunStepAsync(TestSetupStep step, CancellationToken ct)
+    {
+        if (step.IsCommand)
+        {
+            await RunCommandAsync(step, ct);
+            return;
+        }
+        var connStr = ResolveStepConnection(step);
+        await using var conn = new NpgsqlConnection(connStr);
+        await conn.OpenAsync(ct);
+        await RunSqlStepAsync(conn, step, ct);
+    }
+
+    // A step's connection: its explicit ConnectionName (a ConnectionStrings entry), else the test connection.
+    private string ResolveStepConnection(TestSetupStep step)
+    {
+        if (string.IsNullOrWhiteSpace(step.ConnectionName))
+        {
+            return _connString;
+        }
+        if (_named.TryGetValue(step.ConnectionName, out var cs))
+        {
+            return cs;
+        }
+        throw new InvalidOperationException(
+            $"TestRunner Setup/Teardown step references ConnectionName '{step.ConnectionName}', which has no matching entry under 'ConnectionStrings'.");
+    }
+
     /// <summary>Runs after endpoint discovery: executes the test files and (always) Teardown. Returns the process exit code.</summary>
     public async Task<int> RunAsync(RoutineEndpoint[] endpoints, CancellationToken ct = default)
     {
@@ -204,18 +232,30 @@ private async Task<FileResult> RunFileAsync(string file, IReadOnlyDictionary<str
             foreach (var step in steps)
             {
                 StepResult sr;
-                if (step is SqlStep sql)
-                {
-                    sr = await ExecuteSqlStepAsync(conn, sql, timeoutSecs, ct);
-                }
-                else if (step is HttpStep http)
+                try
                 {
-                    httpOrdinal++;
-                    sr = await InvokeHttpStepAsync(conn, http, ResolveResponseTable(http, httpOrdinal, httpTotal), lookup, ct);
+                    if (step is SqlStep sql)
+                    {
+                        sr = await ExecuteSqlStepAsync(conn, sql, timeoutSecs, ct);
+                    }
+                    else if (step is HttpStep http)
+                    {
+                        httpOrdinal++;
+                        sr = await InvokeHttpStepAsync(conn, http, ResolveResponseTable(http, httpOrdinal, httpTotal), lookup, ct);
+                    }
+                    else
+                    {
+                        continue;
+                    }
                 }
-                else
+                catch (OperationCanceledException) { throw; }                          // timeout — outer handler
+                catch (PostgresException pg) when (pg.SqlState == "57014") { throw; }  // timeout — outer handler
+                catch (Exception ex)
                 {
-                    continue;
+                    // Attribute the failure to THIS step (line number, name) instead of a file-level
+                    // "execution error" — e.g. a duplicate `# @response` table (42P07) or an invalid name.
+                    sr = new StepResult(true, Outcome.Error,
+                        ex is PostgresException pgEx ? $"{pgEx.SqlState}: {pgEx.MessageText}" : ex.Message, null);
                 }
 
                 if (sr.Emit)
@@ -321,6 +361,8 @@ private async Task<StepResult> InvokeHttpStepAsync(
                 return new StepResult(true, Outcome.Error, $"SSE endpoints are not supported in test mode: {httpName}", httpName);
             if (ep.Upload)
                 return new StepResult(true, Outcome.Error, $"upload endpoints are not supported in test mode: {httpName}", httpName);
+            if (ep.Login || ep.Logout)
+                return new StepResult(true, Outcome.Error, $"login/logout endpoints are not supported in test mode (inject the principal with `# @claim` instead): {httpName}", httpName);
             if (ep.IsProxy)
             {
                 var host = ep.ProxyHost ?? _rest.ProxyOptions?.Host;
@@ -328,6 +370,13 @@ private async Task<StepResult> InvokeHttpStepAsync(
                     return new StepResult(true, Outcome.Error, $"outbound proxy/HTTP-type endpoints are disallowed in test mode: {httpName}", httpName);
             }
         }
+        else
+        {
+            // Not fatal — the request still runs (a test may assert the 404 deliberately) — but the most
+            // common cause is a path typo or a missing UrlPathPrefix (default "/api"), so surface a warning.
+            _log?.LogWarning("no endpoint matches {Method} {Path} — the response will be a 404; check the path (including UrlPathPrefix, default \"/api\")",
+                step.Method, pathOnly);
+        }
 
         var user = BuildPrincipal(step.Claims);
 
@@ -351,15 +400,9 @@ private async Task<StepResult> InvokeHttpStepAsync(
 
         await WriteResponseAsync(conn, responseTable, response, ct);
 
-        // An HTTP block is a reported assertion only when it carries `# @expect-status`; otherwise it is an
-        // act step (capture the response into the temp table) and produces no test of its own.
-        if (step.ExpectStatus.HasValue)
-        {
-            var name = $"{httpName} (expect {step.ExpectStatus.Value})";
-            return response.StatusCode == step.ExpectStatus.Value
-                ? new StepResult(true, Outcome.Pass, null, name)
-                : new StepResult(true, Outcome.Fail, $"expected status {step.ExpectStatus.Value} but got {response.StatusCode} for {httpName}", name);
-        }
+        // An HTTP block is an act step: it captures the response into the temp table and produces no test
+        // of its own — the assertions are the boolean SELECTs that follow it. It only surfaces as a result
+        // when it errors (unsupported endpoint kind above, or an exception attributed by the step loop).
         return new StepResult(false, Outcome.Pass, null, null);
     }
 
@@ -487,22 +530,11 @@ private async Task TeardownAsync(CancellationToken ct)
     {
         if (_opt.Keep || _opt.Teardown.Count == 0) return;
         _log?.LogDebug("teardown: {Steps} step(s)", _opt.Teardown.Count);
-        try
-        {
-            await using var conn = new NpgsqlConnection(_connString);
-            await conn.OpenAsync(ct);
-            foreach (var step in _opt.Teardown.Where(s => !s.IsCommand)) // SQL first
-            {
-                try { await RunSqlStepAsync(conn, step, ct); }
-                catch (Exception ex) { _log?.LogWarning(ex, "teardown SQL step failed"); }
-            }
-        }
-        catch (Exception ex) { _log?.LogWarning(ex, "teardown connection failed"); }
-
-        foreach (var step in _opt.Teardown.Where(s => s.IsCommand)) // commands last (e.g. docker down)
+        // Strict declared order, best-effort: a failing step is logged and the rest still run.
+        foreach (var step in _opt.Teardown)
         {
-            try { await RunCommandAsync(step, ct); }
-            catch (Exception ex) { _log?.LogWarning(ex, "teardown command failed"); }
+            try { await RunStepAsync(step, ct); }
+            catch (Exception ex) { _log?.LogWarning(ex, "teardown step failed"); }
         }
     }
 
@@ -545,12 +577,12 @@ private static Dictionary<string, RoutineEndpoint> BuildEndpointLookup(RoutineEn
         return d;
     }
 
-    // Print the failing statement under the message (dimmed). Capped to its first line unless --verbose.
+    // Print the failing statement under the message (dimmed). Capped to its first line unless DetailedReport.
     private void WriteFailingSql(string? sql)
     {
         if (string.IsNullOrWhiteSpace(sql)) return;
         var text = sql.Trim();
-        if (_opt.Verbose)
+        if (_opt.DetailedReport)
         {
             _out.Line("        " + text.Replace("\n", "\n        "), ConsoleColor.DarkGray);
             return;
@@ -564,9 +596,9 @@ private void WriteFailingSql(string? sql)
 
     private void ReportConsole(List<FileResult> results)
     {
-        // Counts are at assertion granularity (each boolean SELECT / DO block / `# @expect-status` HTTP
-        // step is one test); files are the grouping unit. A file is fail-fast, so on failure the assertions
-        // listed are those that ran up to and including the first failure.
+        // Counts are at assertion granularity (each boolean SELECT / DO block is one test); files are the
+        // grouping unit. A file is fail-fast, so on failure the assertions listed are those that ran up to
+        // and including the first failure.
         int passed = 0, failed = 0, errored = 0, totalAssertions = 0;
         foreach (var fr in results)
         {
@@ -585,7 +617,7 @@ private void ReportConsole(List<FileResult> results)
             else if (fr.Outcome == Outcome.Pass)
             {
                 _out.Line($"PASS  {rel}  ({aPass} assertion{(aPass == 1 ? "" : "s")}, {fr.ElapsedMs}ms)", ConsoleColor.Green);
-                if (_opt.Verbose)
+                if (_opt.DetailedReport)
                     foreach (var a in fr.Assertions) _out.Line($"        ✓ {a.Name}", ConsoleColor.DarkGray);
             }
             else
@@ -596,7 +628,7 @@ private void ReportConsole(List<FileResult> results)
                 {
                     if (a.Outcome == Outcome.Pass)
                     {
-                        if (_opt.Verbose) _out.Line($"        ✓ {a.Name}", ConsoleColor.DarkGray);
+                        if (_opt.DetailedReport) _out.Line($"        ✓ {a.Name}", ConsoleColor.DarkGray);
                         continue;
                     }
                     var loc = a.Line is null ? "" : $"  [{rel}:{a.Line}]";
@@ -606,7 +638,7 @@ private void ReportConsole(List<FileResult> results)
                 }
             }
 
-            if (fr.Notices.Count > 0 && (_opt.Verbose || fr.Outcome != Outcome.Pass))
+            if (fr.Notices.Count > 0 && (_opt.DetailedReport || fr.Outcome != Outcome.Pass))
                 foreach (var n in fr.Notices) _out.Line($"        notice: {n}", ConsoleColor.DarkGray);
         }
 
@@ -685,7 +717,7 @@ private static string FirstLine(string text)
     }
 
     // Fallback display name when a step has no inherent label (a boolean SELECT without a description column,
-    // a DO block, or a non-`# @expect-status` HTTP step that errored).
+    // a DO block, or an HTTP step that errored).
     private static string DefaultAssertionName(TestStep step) => step switch
     {
         SqlStep { IsDoBlock: true } => $"assert block (line {step.LineNumber})",
diff --git a/NpgsqlRestClient/Testing/TestRunnerOptions.cs b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
index 2ccf7a55..53b47018 100644
--- a/NpgsqlRestClient/Testing/TestRunnerOptions.cs
+++ b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
@@ -6,6 +6,15 @@ public class TestRunnerOptions
     /// <summary>Glob (same engine as SqlFileSource) selecting *.test.sql files. Empty disables the runner.</summary>
     public string FilePattern { get; set; } = "";
 
+    /// <summary>
+    /// Name of a <c>ConnectionStrings</c> entry to run the tests against, instead of the app's main connection.
+    /// In test mode it becomes the connection used for endpoint type-checking (Describe) and execution, so it
+    /// can point at a dedicated test database. The database need not exist at startup — a <c>Setup</c> step
+    /// (e.g. <c>create database …</c> on a maintenance connection) can create it first. Null/empty = use the
+    /// app's main connection (the Phase-1 behavior).
+    /// </summary>
+    public string? ConnectionName { get; set; } = null;
+
     /// <summary>Max concurrent test files. 0 => Environment.ProcessorCount.</summary>
     public int MaxParallelism { get; set; } = 0;
 
@@ -21,8 +30,13 @@ public class TestRunnerOptions
     /// <summary>Skip Teardown so a failed run's state can be inspected.</summary>
     public bool Keep { get; set; } = false;
 
-    /// <summary>Show captured `raise notice` output for all tests, not just failed/errored ones.</summary>
-    public bool Verbose { get; set; } = false;
+    /// <summary>
+    /// Detailed console REPORT: list passed assertions (✓), print the full failing SQL statement, and show
+    /// captured `raise notice` output for passing tests too. This shapes the report only — for diagnostic
+    /// logging of every executed query/HTTP call, raise the log channel instead (Log:MinimalLevels, see
+    /// <see cref="LoggerName"/>).
+    /// </summary>
+    public bool DetailedReport { get; set; } = false;
 
     /// <summary>Zero tests discovered => exit 0 instead of 4.</summary>
     public bool AllowEmpty { get; set; } = false;
@@ -79,5 +93,13 @@ public class TestSetupStep
     /// <summary>Working directory for <see cref="Command"/> (cwd-relative); null => current directory.</summary>
     public string? WorkingDirectory { get; set; }
 
+    /// <summary>
+    /// For a <see cref="Sql"/>/<see cref="SqlFile"/> step: name of the <c>ConnectionStrings</c> entry to run it
+    /// on. Use this to run maintenance statements (e.g. <c>create database</c> / <c>drop database</c>) on an
+    /// admin connection pointed at a maintenance database. Null = run on the test connection
+    /// (<see cref="TestRunnerOptions.ConnectionName"/>, or the app's main connection). Ignored for Command steps.
+    /// </summary>
+    public string? ConnectionName { get; set; }
+
     public bool IsCommand => !string.IsNullOrWhiteSpace(Command);
 }
diff --git a/NpgsqlRestClient/Testing/TestStep.cs b/NpgsqlRestClient/Testing/TestStep.cs
index 2ffeb0ae..25434d80 100644
--- a/NpgsqlRestClient/Testing/TestStep.cs
+++ b/NpgsqlRestClient/Testing/TestStep.cs
@@ -49,8 +49,6 @@ public sealed class HttpStep : TestStep
     public IReadOnlyList<(string Name, string Value)> Claims { get; }
     /// <summary>Request body (verbatim), or null when none.</summary>
     public string? Body { get; }
-    /// <summary>Expected status from <c># @expect-status NNN</c>, or null.</summary>
-    public int? ExpectStatus { get; }
     /// <summary>Response temp-table name override from <c># @response name</c>, or null (use the configured default).</summary>
     public string? ResponseTable { get; }
 
@@ -60,7 +58,6 @@ public HttpStep(
         IReadOnlyList<(string Name, string Value)> headers,
         IReadOnlyList<(string Name, string Value)> claims,
         string? body,
-        int? expectStatus,
         string? responseTable,
         int lineNumber) : base(TestStepKind.Http, lineNumber)
     {
@@ -69,7 +66,6 @@ public HttpStep(
         Headers = headers;
         Claims = claims;
         Body = body;
-        ExpectStatus = expectStatus;
         ResponseTable = responseTable;
     }
 }
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index db81a5c2..f61922b2 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -1439,6 +1439,14 @@
     //
     "FilePattern": "",
     //
+    // Optional: a ConnectionStrings entry to run the tests against instead of the app's main connection. In
+    // test mode it becomes the connection used for endpoint type-checking (Describe) and execution, so it can
+    // point at a dedicated test database that a Setup step creates first (it need not exist at startup).
+    // Empty = use the main connection. Tip: {rnd1}..{rnd10} are random lowercase tokens (length = the digit),
+    // stable for the whole run, usable in any connection string or Setup/Teardown SQL (e.g. Database=app_test_{rnd6}).
+    //
+    "ConnectionName": "",
+    //
     // Max test files run concurrently. 0 => processor count. Each test uses its own non-pooled connection.
     //
     "MaxParallelism": 0,
@@ -1459,9 +1467,11 @@
     //
     "Keep": false,
     //
-    // Show captured `raise notice` output for all tests, not just failed/errored ones.
+    // Detailed console REPORT: list passed assertions, print the full failing SQL statement, and show
+    // captured `raise notice` output for passing tests too. This shapes the report only — for diagnostic
+    // logging of every executed query/HTTP call, raise the log channel instead (Log:MinimalLevels + LoggerName).
     //
-    "Verbose": false,
+    "DetailedReport": false,
     //
     // Treat "no tests discovered" as success (exit 0) instead of exit 4.
     //
@@ -1490,13 +1500,15 @@
       }
     },
     //
-    // Run-once setup, BEFORE endpoint discovery. Command steps run first (provision infra, e.g. docker),
-    // then SqlFile/Sql steps (migrations/seed) — declared order preserved within each group. Each entry:
-    //   { "Command": "...", "WorkingDirectory": "..." } | { "SqlFile": "..." } | { "Sql": "..." }
+    // Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written. Each entry is one of:
+    //   { "Command": "...", "WorkingDirectory": "..." }    — runs via the OS shell
+    //   { "Sql": "..." } | { "SqlFile": "..." }            — runs on the test connection; set "ConnectionName"
+    //                                                         to run on another ConnectionStrings entry (e.g.
+    //                                                         an admin connection that runs `create database`).
     //
     "Setup": [],
     //
-    // Run-once teardown, ALWAYS (best-effort), reverse order: SqlFile/Sql first, then Command. `Keep` skips it.
+    // Run-once teardown, ALWAYS (best-effort), in the EXACT order written. `Keep` skips it. Same step shapes as Setup.
     //
     "Teardown": []
   },
diff --git a/NpgsqlRestTests/TestRunnerTests/ParserTests/HttpFileRequestParserTests.cs b/NpgsqlRestTests/TestRunnerTests/ParserTests/HttpFileRequestParserTests.cs
index 09ca1252..2c8ab641 100644
--- a/NpgsqlRestTests/TestRunnerTests/ParserTests/HttpFileRequestParserTests.cs
+++ b/NpgsqlRestTests/TestRunnerTests/ParserTests/HttpFileRequestParserTests.cs
@@ -89,10 +89,11 @@ public void Repeated_Claim_Type_Yields_Multiple_Values()
     }
 
     [Fact]
-    public void Expect_Status_And_Response_Directives_Are_Parsed()
+    public void Response_Directive_Is_Parsed_And_Unknown_Directives_Are_Ignored()
     {
+        // `@expect-status` was removed (assert on the response temp table's status column instead);
+        // an unknown directive is silently ignored rather than breaking the block.
         var s = Parse("GET /x\n# @expect-status 404\n# @response listing");
-        s.ExpectStatus.Should().Be(404);
         s.ResponseTable.Should().Be("listing");
     }
 
diff --git a/changelog/v3.19.0.md b/changelog/v3.19.0.md
index f5ef3c21..36ec163c 100644
--- a/changelog/v3.19.0.md
+++ b/changelog/v3.19.0.md
@@ -1,46 +1,269 @@
 # Changelog v3.19.0
 
-## Version [3.19.0](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.19.0) (2026-06-30)
+## Version [3.19.0](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.19.0) (2026-07-02)
 
 [Full Changelog](https://github.com/NpgsqlRest/NpgsqlRest/compare/3.18.2...3.19.0)
 
-Minor release adding two small, independent configuration options: a **skip glob for the SQL file source** (exclude files from endpoint discovery) and the ability to **mute an individual logger** via `Log:MinimalLevels`.
+This release introduces the **SQL test runner** (`npgsqlrest --test`) — write tests for your endpoints as plain `.sql` files, invoke endpoints in-process from inside a test, and assert on both the HTTP response and the database state, all within the test's own transaction. Also included: a **skip glob for the SQL file source** and the ability to **mute an individual logger**.
 
-## What changed
+---
 
-### 1. `SqlFileSource.SkipPattern` — exclude files from endpoint discovery
+## 1. SQL test runner (`--test`)
+
+```
+npgsqlrest ./config.json --test
+```
+
+The runner discovers `.sql` test files, executes each on its own isolated connection, and reports per-assertion results to the console (and optionally JUnit XML for CI). A test file is ordinary SQL — arrange data, call an endpoint, assert on the result:
+
+```sql
+-- tests/get_users_excludes_caller.test.sql
+begin;
+
+insert into app.users (id, email, name) values (100, 'x@example.com', 'Fixture');
+
+/*
+GET /api/get-users
+# @claim user_id=1
+*/
+select (select status from _response) = 200,
+       'authenticated caller gets 200';
+select (select body::jsonb @> '[{"email": "x@example.com"}]' from _response),
+       'the fixture user is listed';
+
+rollback;
+```
+
+```
+NpgsqlRest test runner — 9 file(s)
+PASS  tests/get_users_excludes_caller.test.sql  (2 assertions, 52ms)
+...
+19 passed, 0 failed, 0 error(s)  —  19 assertions in 9 files
+```
+
+### How it works
+
+In `--test` mode the client builds the full endpoint middleware exactly as in normal operation (endpoints from database routines and/or SQL files, authentication, custom parameters — everything), but instead of starting the web server it runs the test files and exits with a result code. Endpoint calls made from a test are **in-process**: no network, no running server — the complete endpoint pipeline (routing, authorization, parameter binding, execution, serialization) runs against a synthetic HTTP context.
+
+The critical property is **connection affinity**: the in-process endpoint call runs on the *test's own connection*, inside the *test's own transaction*. A test can `begin`, insert fixture rows, call an endpoint that sees those uncommitted rows, assert on the response, and `rollback` — leaving no trace. Each test file gets its own **non-pooled** physical connection (fresh session: no temp-table, GUC, or prepared-statement carryover), and files run **in parallel** (`MaxParallelism`, default = processor count). If a file never rolls back, closing its physical connection aborts the open transaction — that is the safety net.
+
+Test-mode invariants, applied automatically:
+
+- `WrapInTransaction` is forced off (the test file owns transaction control — the runner never injects `BEGIN`/`COMMIT`/`ROLLBACK`).
+- Response caching is disabled (a test never sees another test's cached response).
+- Code generation (HTTP files, TypeScript client, OpenAPI) is **skipped** — a test run never rewrites generated artifacts.
+
+### Test file anatomy
+
+A test file is a sequence of SQL statements and HTTP blocks, executed strictly in order. Files are executed **statement by statement** (like `psql`): each statement runs in autocommit unless the file opens its own transaction. Semicolon splitting understands line/block comments, string literals with `''` escapes, and dollar-quoted bodies — a `do $$ … $$;` block stays whole.
+
+**Assertions** — a reported test is one of:
+
+- **A boolean-returning `SELECT`.** If the first column is `boolean`, the statement is an assertion: the first row's value must be true (`false` or `null` fails; zero rows passes vacuously; only the first row is examined). The optional **second column is the assertion's name/message**, shown in the report and used as the JUnit test-case name:
+  ```sql
+  select count(*) = 3, 'exactly three users are seeded' from app.users;
+  ```
+- **A `do` block.** Passes unless it raises — `assert` inside a DO block raises SQLSTATE `P0004`, reported as a failure with the assert message. One DO block = one reported test (multiple `assert`s inside it are opaque to the runner):
+  ```sql
+  do $$ begin
+      assert app.normalize_email(' X@Y.z ') = 'x@y.z', 'should trim and lowercase';
+  end $$;
+  ```
+
+Any other statement is *arrange/act* — not counted as a test; it only surfaces if it errors. Any SQL error (other than an assert) is reported as an **error** with its SQLSTATE, message, statement text, and `file:line`.
+
+Failing behavior is **fail-fast per file**: after the first failed/errored assertion the rest of the file does not run (a failed DO-block assert aborts the transaction anyway). Assertions that passed before the failure are still credited.
+
+### HTTP blocks — invoking endpoints
+
+An HTTP request is embedded in a **block comment** whose first non-comment line is a request line — a single-request subset of the standard `.http` file syntax:
+
+```sql
+/*
+POST /api/create-user
+Content-Type: application/json
+# @claim user_id=42
+# @claim roles=admin
+# @response created
+
+{"name": "Grace Hopper", "email": "grace@example.com"}
+*/
+```
+
+Syntax rules:
+
+- **Request line:** `[HTTP] METHOD /path[?query] [HTTP/x]` — the method is one of `GET`, `POST`, `PUT`, `DELETE` (the methods NpgsqlRest endpoints support); the path must start with `/` and must equal the endpoint's full path **including `UrlPathPrefix`** (default `/api`); the leading `HTTP` keyword and a trailing HTTP-version token are optional. A block comment whose first line is not a valid request line is an ordinary SQL comment — ignored.
+- **Headers:** `Name: Value` lines after the request line. `Content-Type` is picked up for the request body.
+- **Directives** (lines starting with `# @` or `// @`, placed after the request line, before the body):
+  - `# @claim name=value` — adds a claim to the acting principal. Repeatable, including the same claim type twice (e.g. two `roles` claims). Any `# @claim` makes the request **authenticated**; no `# @claim` means **anonymous** (an `@authorize` endpoint returns 401). Role checks and claim-to-parameter mappings (`@user_parameters`, `ParameterNameClaimsMapping`) work exactly as in production — tests exercise the real authorization path.
+  - `# @response name` — capture this block's response into a temp table with the given name instead of the default.
+- **Body:** everything after the first **blank line**, verbatim. (Limitation: a literal `*/` inside the body ends the SQL comment early.)
+- Plain `#` or `//` lines are comments; unknown `@` directives are ignored.
+
+An HTTP block is an **act** step, not an assertion — it captures the response and produces no test result of its own. The assertions are the SQL statements that follow it. One request per block; use multiple blocks for multiple calls.
+
+Endpoint kinds that cannot work meaningfully in-process are rejected with a clear error: **SSE**, **upload**, **login/logout** (inject the principal with `# @claim` instead), and **outbound proxy/HTTP-type** endpoints (tests must not call external services). A request whose path matches **no endpoint** still runs (a test may assert the 404 deliberately) but logs a **warning** — the most common cause is a path typo or a missing `/api` prefix.
+
+### The response temp table
+
+Each HTTP block's response is captured into its own **temp table** on the test's connection, created fresh (no `IF NOT EXISTS` — a duplicate name, e.g. a repeated `# @response` name, fails the test loudly). Default columns:
+
+| Column | Type | Content |
+|---|---|---|
+| `status` | `int` | HTTP status code |
+| `body` | `text` | response body (cast to `::jsonb` to assert on JSON) |
+| `content_type` | `text` | response content type |
+| `headers` | `jsonb` | response headers |
+| `is_success` | `boolean` | true for 2xx |
+
+Naming: a file with **one** HTTP block uses `ResponseTempTable.Name` (default **`_response`**); a file with **two or more** uses `ResponseTempTable.MultiNamePattern` (default **`_response_{n}`**) where `{n}` is the block's 1-based position — `_response_1`, `_response_2`, … A block with `# @response name` uses that name instead (it still counts in the numbering of the others). Column names are configurable; setting one to null/empty omits that column.
+
+```sql
+select (select body::jsonb ->> 'email' from _response) = 'grace@example.com',
+       'email is normalized to lowercase';
+```
+
+### Setup and Teardown
+
+Run-once steps around the whole test session. **`Setup` runs before endpoint discovery** (so it can create/migrate the very schema the endpoints are built from); **`Teardown` always runs** at the end — even when tests fail or Setup itself fails (best-effort; `Keep: true` skips it to let you inspect state). Steps execute in the **exact order written**; each entry is one of:
+
+- `{ "Sql": "..." }` — inline SQL,
+- `{ "SqlFile": "path" }` — a SQL file (executed statement by statement, like test files),
+- `{ "Command": "...", "WorkingDirectory": "..." }` — a shell command (e.g. `docker compose up -d`, an external migration tool). Non-zero exit fails Setup.
+
+`Sql`/`SqlFile` steps run on the test connection by default, or on any named `ConnectionStrings` entry via a per-step `"ConnectionName"` — which enables maintenance operations like `create database` without the runner ever issuing DDL on its own.
+
+### A dedicated test database
+
+`TestRunner.ConnectionName` points the whole test session — endpoint type-checking (SQL-file Describe), endpoint execution, and the tests — at a named `ConnectionStrings` entry instead of the app's main connection. That database **need not exist at startup**: it is never opened before Setup, so the first Setup step can create it.
+
+```jsonc
+"ConnectionStrings": {
+  "Default": "Host={PGHOST};Database=appdb;...",                     // the real app DB — untouched by tests
+  "Admin":   "Host={PGHOST};Database=postgres;...",                  // maintenance (needs CREATEDB)
+  "Test":    "Host={PGHOST};Database=app_test_{rnd6};..."            // the throwaway test DB
+},
+"TestRunner": {
+  "ConnectionName": "Test",
+  "FilePattern": "./tests/**/*.test.sql",
+  "Setup": [
+    { "Sql": "create database app_test_{rnd6}", "ConnectionName": "Admin" },
+    { "SqlFile": "./migrations/schema.sql" }                         // runs on "Test"
+  ],
+  "Teardown": [
+    { "Sql": "drop database app_test_{rnd6} with (force)", "ConnectionName": "Admin" }
+  ]
+}
+```
+
+**`{rnd1}`…`{rnd10}`** are random lowercase tokens (length = the digit), generated once per run and substituted everywhere `{ENV}` placeholders work — connection strings, Setup/Teardown SQL, and Commands. The same token yields the same value across the whole config, so the connection string, the `create`, and the `drop` all name the same database; concurrent suites on a shared server can't collide. (Trade-off: a hard crash that skips Teardown orphans that run's database. A static name with a leading `drop database if exists … with (force);` in Setup is the self-healing alternative.)
+
+The same Setup/Teardown machinery covers the neighboring workflows with no additional features: clone a prepared **template** (`create database … template app_template` — near-instant), start a **Docker** Postgres (`Command` steps: `docker run` → wait for `pg_isready` → migrate; `docker rm -f` in Teardown), or run an **external migrator** (EF Core, Django, Flyway) as a `Command`.
+
+### Reporting
+
+Results are **per assertion** (like pgTAP/xUnit — each boolean `SELECT` / DO block is one test), grouped per file:
+
+```
+PASS  tests/login_succeeds.test.sql  (3 assertions, 50ms)
+FAIL  tests/get_users.test.sql  (49ms)
+        ✗ the caller is excluded — 2 of 3 users listed  [tests/get_users.test.sql:17]
+        select (select jsonb_array_length(body::jsonb) from _response) = 2, …
+
+18 passed, 1 failed, 0 error(s)  —  19 assertions in 9 files
+```
+
+Failures show the assertion name, `file:line`, and the failing statement. `DetailedReport: true` additionally lists passed assertions (`✓`), full failing SQL, and captured `raise notice` output for passing tests (notices always show under failing tests). This shapes the console report only — it is distinct from raising the `NpgsqlRestTest` *log* level, which controls diagnostics (see Logging below). A file with no recognizable assertions is flagged (yellow) rather than silently counted. Colors are disabled automatically when output is redirected.
+
+**JUnit XML** (`JUnitOutput: "path.xml"`): one `<testcase>` per assertion (name = the assertion message, classname = the file), `<failure>`/`<error>` with message and `file:line`, captured notices in `<system-out>`, files without assertions marked `<skipped>` — works with any CI dashboard.
+
+**Exit codes:** `0` all passed · `1` at least one failure · `2` at least one error (SQL error, timeout, unsupported endpoint) · `3` setup/configuration error · `4` no test files found (`AllowEmpty: true` turns this into `0`).
+
+### Logging
+
+The runner logs through its own channel — **`NpgsqlRestTest`** (configurable via `TestRunner.LoggerName`) — leveled independently under `Log:MinimalLevels` (defaults to `Information` when absent, i.e. quiet):
+
+- **Verbose** — every SQL statement and every HTTP invocation (`GET /api/x → 200, captured into "_response"`),
+- **Debug** — discovery, per-file parse results, per-file outcomes, Setup/Teardown steps, degree of parallelism,
+- **Warning** — a request that matches no endpoint, failed teardown steps,
+- `raise notice`/`warning` from the database — logged **by their severity**, tagged with the test file that emitted them.
+
+```jsonc
+"Log": { "MinimalLevels": { "NpgsqlRest": "Off", "NpgsqlRestClient": "Off", "NpgsqlRestTest": "Verbose" } }
+```
+
+### Configuration reference (`TestRunner` section)
+
+```jsonc
+"TestRunner": {
+  "FilePattern": "",                    // glob selecting test files (same engine as SqlFileSource); empty disables
+  "ConnectionName": "",                 // ConnectionStrings entry to test against; empty = the main connection
+  "MaxParallelism": 0,                  // concurrent test files; 0 = processor count
+  "FailFast": false,                    // stop scheduling new files after the first failure (in-flight finish)
+  "PerTestTimeout": "30s",              // per-file timeout: "30s", "5m", "1h", plain seconds, "hh:mm:ss"; 0 disables
+  "JUnitOutput": null,                  // optional path for a JUnit XML report
+  "Keep": false,                        // skip Teardown (inspect state after a failed run)
+  "DetailedReport": false,              // detailed console report: passed ✓ lines, full failing SQL, notices for passing tests
+  "AllowEmpty": false,                  // exit 0 instead of 4 when no tests are found
+  "LoggerName": "NpgsqlRestTest",       // the runner's log channel (leveled via Log:MinimalLevels)
+  "ResponseTempTable": {
+    "Name": "_response",                // table name when a file has ONE HTTP block
+    "MultiNamePattern": "_response_{n}",// name pattern for 2+ blocks; {n} = 1-based block position
+    "Columns": {                        // response → column mapping; null/empty omits the column
+      "Status": "status", "Body": "body", "ContentType": "content_type",
+      "Headers": "headers", "IsSuccess": "is_success"
+    }
+  },
+  "Setup": [],                          // run-once, BEFORE endpoint discovery, in written order
+  "Teardown": []                        // run-once, ALWAYS, in written order (Keep skips)
+}
+```
+
+A practical convention is to keep the `TestRunner` block (and quiet log levels) in a separate `test-config.json` layered on only for test runs: `npgsqlrest ./config.json ./test-config.json --test`.
+
+### Project layout
+
+Two equally supported conventions — the difference is just the globs:
+
+- **Co-located:** `sql/get_users.sql` + `sql/get_users.test.sql`. Pair the endpoint glob with the new `SqlFileSource.SkipPattern` (below) so test files are never exposed as endpoints.
+- **Separate tree:** endpoints in `sql/`, tests in `tests/` (named by scenario). The globs never overlap, so no `SkipPattern` is needed.
+
+---
+
+## 2. `SqlFileSource.SkipPattern` — exclude files from endpoint discovery
 
 New option **`SkipPattern`** on the SQL file source (config key `NpgsqlRest:SqlFileSource:SkipPattern`, default **`"*.test.sql"`**). Files whose full path matches this glob are excluded from endpoint discovery: a `.sql` file becomes an endpoint only when it matches **`FilePattern`** *and* does **not** match **`SkipPattern`**.
 
-This lets you keep auxiliary `.sql` files that live alongside your endpoint files — for example co-located SQL files following the `*.test.sql` naming convention — without them being turned into HTTP endpoints. The pattern uses the same glob engine and semantics as `FilePattern` (`*.ext` matches by suffix). Set it to an empty string (`""`) to disable the exclusion.
+This is what makes the co-located test layout safe: without it, a test file's `/* GET /x */` block would be read as an HTTP annotation and exposed as an endpoint. The pattern uses the same glob engine and semantics as `FilePattern` (`*.ext` matches by suffix). Set it to an empty string (`""`) to disable the exclusion.
 
 > **Behavior change:** the default is `"*.test.sql"`, so files matching that suffix are **no longer exposed** as endpoints out of the box. If you previously relied on serving `*.test.sql` files, set `SkipPattern` to `""` to restore the old behavior.
 
-### 2. Mute an individual logger with `"Off"` in `Log:MinimalLevels`
+## 3. Mute an individual logger with `"Off"` in `Log:MinimalLevels`
 
 Each entry under **`Log:MinimalLevels`** now accepts **`"Off"`** (aliases **`"None"`** and **`"Silent"`**, case-insensitive) to **fully silence** that logger. Previously the only accepted values were the Serilog levels `Verbose…Fatal`, and there was no way to turn a logger off completely.
 
 - `"Off"` / `"None"` / `"Silent"` → the logger emits nothing (implemented as a minimum level above `Fatal`, since Serilog's `LogEventLevel` has no native "off").
 - `null`, an omitted key, or an unrecognized value → unchanged: the logger keeps its built-in default level.
 
-Each named logger is controlled independently, so you can, for example, mute the `System`/`Microsoft` framework logs entirely while keeping the application loggers at `Information`:
+Each named logger is controlled independently — e.g. mute the application loggers entirely while watching the test runner:
 
 ```json
 "Log": {
   "MinimalLevels": {
-    "NpgsqlRest": "Information",
-    "NpgsqlRestClient": "Information",
-    "System": "Off",
-    "Microsoft": "Off"
+    "NpgsqlRest": "Off",
+    "NpgsqlRestClient": "Off",
+    "NpgsqlRestTest": "Verbose"
   }
 }
 ```
 
 ## Notes
 
-- Both options are wired through the client configuration: `appsettings.json`, the JSON-schema descriptions, and the `--config` template (which continues to match `appsettings.json` byte-for-byte).
-- Fully additive apart from the `SkipPattern` default noted above; no API changes.
+- The test runner's core hooks are additive and inert outside `--test`: an ambient-connection accessor on the endpoint pipeline (null by default) and response headers on the internal invocation result. Normal server operation is unchanged.
+- Test files run **statement by statement** (the client operates Npgsql with SQL rewriting disabled — one statement per command), which is also `psql`'s default execution model; explicit `begin`/`commit`/`rollback` in a file work as ordinary statements. `Setup`/`Teardown` `Sql`/`SqlFile` steps execute the same way — which is why `create database` works as a plain step.
+- All new options are wired through the client configuration: `appsettings.json`, the JSON-schema descriptions, and the `--config` template.
+- Working examples: [`examples/19_testing_basic`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/19_testing_basic) (co-located layout, multi-step scenario files) and [`examples/20_testing_newdb`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/20_testing_newdb) (separate `tests/` tree, one test per file, fresh test database per run, deferrable-constraint fixtures, authorization + user parameters).
 
 ## Tests
 
-Full test suite green (2334). The new configuration keys are covered by the configuration round-trip tests (the `--config` template output matches `appsettings.json`).
+Full test suite green (2334), including 33 parser unit tests for the test-file and HTTP-block parsers (`NpgsqlRestTests/TestRunnerTests/ParserTests/`). Both documentation examples verified end-to-end against live PostgreSQL (19 assertions in 9 files for example 20, including create-database-per-run with a `{rnd}` name and teardown drop). The new configuration keys are covered by the configuration round-trip tests (the `--config` template output matches `appsettings.json`).

From 58ae087ee05d12b1d1a4bf5f4e0c87fef53f6f67 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Thu, 2 Jul 2026 17:24:24 +0200
Subject: [PATCH 14/25] feat(test-runner): script includes, named steps,
 per-file setup/teardown/connection
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Script reuse — \i / \ir includes (psql syntax, paste semantics):
- `\i path` (cwd-relative) / `\ir path` (relative to the including file) on
  its own line splices the included file's content in place, as if pasted:
  SQL statements, assertions (attributed to the included file), HTTP blocks
  (participate in _response_{n} numbering), and header annotations (a shared
  annotation "profile" attaches with one include line).
- Recognized only between statements (never inside strings/dollar-quotes;
  no statement fragments — use functions/views). Nested, cycle-safe,
  depth-capped. Works in Setup/Teardown SqlFile steps. Errors report the
  included file's name and line. Quoted paths and a trailing ';' accepted;
  other backslash lines pass through to PostgreSQL untouched.

Named steps (TestRunner.Steps):
- name -> step dictionary (same idiom as ConnectionStrings/Profiles);
  Setup/Teardown arrays mix name references and inline step objects;
  unknown name is a configuration error (exit 3). Step logs show
  phase + name + resolved code: `setup step CreateTemplate: create
  database app_template_abc`.

Per-file header annotations (leading -- comments, before the first statement):
- `-- @setup Name [Name ...]`  runs named steps before the file
- `-- @teardown Name [Name ...]` runs after the file — always, best-effort,
  after the file's connection closes (so `drop database ... with (force)`
  works), on the run token (survives per-test timeout)
- `-- @connection Name` runs the file, including its in-process endpoint
  calls, on a named ConnectionStrings entry
- Repeatable; names whitespace- or comma-separated; accumulate and execute
  in written order (teardown not reversed); setup fail-fast, teardown
  best-effort. Together these enable per-test database isolation: clone a
  template, run in the clone, drop it (deterministic sequence ids).

{rnd} indexed instances:
- {rndN_1}..{rndN_9} are independent random tokens per length (all stable
  per run) for when several distinct same-length names are needed.

Changelog updated (paste-model includes, named steps, per-file annotations,
indexed tokens, example 21). Config synced across appsettings.json,
ConfigTemplate.cs, ConfigDefaults.cs, ConfigSchemaGenerator.cs. Full suite
green (2351) incl. 50 parser tests; examples 19/20/21 verified end-to-end
(21: two parallel per-test clones from one template, shared annotation
profile via \ir, Command step with {rnd} substitution).
---
 NpgsqlRestClient/Builder.cs                   |  50 ++++-
 NpgsqlRestClient/Config.cs                    |   9 +-
 NpgsqlRestClient/ConfigDefaults.cs            |   1 +
 NpgsqlRestClient/ConfigSchemaGenerator.cs     |   7 +-
 NpgsqlRestClient/ConfigTemplate.cs            |  17 +-
 NpgsqlRestClient/Program.cs                   |  13 +-
 NpgsqlRestClient/Testing/SqlTestFileParser.cs |  63 +++++-
 NpgsqlRestClient/Testing/TestFileLoader.cs    | 168 +++++++++++++++
 NpgsqlRestClient/Testing/TestRunner.cs        | 151 ++++++++++++--
 NpgsqlRestClient/Testing/TestRunnerOptions.cs |  13 +-
 NpgsqlRestClient/Testing/TestStep.cs          |  25 +++
 NpgsqlRestClient/appsettings.json             |  17 +-
 .../TestFileHeaderAndIncludeTests.cs          | 196 ++++++++++++++++++
 changelog/v3.19.0.md                          |  92 ++++++--
 14 files changed, 764 insertions(+), 58 deletions(-)
 create mode 100644 NpgsqlRestClient/Testing/TestFileLoader.cs
 create mode 100644 NpgsqlRestTests/TestRunnerTests/ParserTests/TestFileHeaderAndIncludeTests.cs

diff --git a/NpgsqlRestClient/Builder.cs b/NpgsqlRestClient/Builder.cs
index 882ba793..f6be212f 100644
--- a/NpgsqlRestClient/Builder.cs
+++ b/NpgsqlRestClient/Builder.cs
@@ -3094,6 +3094,18 @@ public TestRunnerOptions BuildTestRunnerOptions()
             }
         }
 
+        // Named step registry (name → step), referenced by name from Setup/Teardown and test file headers.
+        foreach (var child in section.GetSection("Steps").GetChildren())
+        {
+            if (string.IsNullOrWhiteSpace(child.Key)) continue;
+            var step = ReadStep(child);
+            if (step is not null)
+            {
+                step.Name = child.Key;
+                opt.Steps[child.Key] = step;
+            }
+        }
+
         opt.Setup = ReadTestSteps(section.GetSection("Setup"));
         opt.Teardown = ReadTestSteps(section.GetSection("Teardown"));
         return opt;
@@ -3106,21 +3118,43 @@ public TestRunnerOptions BuildTestRunnerOptions()
             return string.IsNullOrWhiteSpace(s.Value) ? null : s.Value;
         }
 
+        TestSetupStep? ReadStep(IConfigurationSection child)
+        {
+            var step = new TestSetupStep
+            {
+                Sql = _config.GetConfigStr("Sql", child),
+                SqlFile = _config.GetConfigStr("SqlFile", child),
+                Command = _config.GetConfigStr("Command", child),
+                WorkingDirectory = _config.GetConfigStr("WorkingDirectory", child),
+                ConnectionName = _config.GetConfigStr("ConnectionName", child),
+            };
+            return step.Sql is not null || step.SqlFile is not null || step.Command is not null ? step : null;
+        }
+
         List<TestSetupStep> ReadTestSteps(IConfigurationSection stepsSection)
         {
             var list = new List<TestSetupStep>();
             if (stepsSection.Exists() is false) return list;
             foreach (var child in stepsSection.GetChildren())
             {
-                var step = new TestSetupStep
+                // A string element is a reference to a named step from the Steps registry; an object element
+                // is an inline step. Both can be mixed in the same array.
+                if (string.IsNullOrWhiteSpace(child.Value) is false)
                 {
-                    Sql = _config.GetConfigStr("Sql", child),
-                    SqlFile = _config.GetConfigStr("SqlFile", child),
-                    Command = _config.GetConfigStr("Command", child),
-                    WorkingDirectory = _config.GetConfigStr("WorkingDirectory", child),
-                    ConnectionName = _config.GetConfigStr("ConnectionName", child),
-                };
-                if (step.Sql is not null || step.SqlFile is not null || step.Command is not null)
+                    var name = child.Value.Trim();
+                    if (opt.Steps.TryGetValue(name, out var named))
+                    {
+                        list.Add(named);
+                    }
+                    else
+                    {
+                        throw new InvalidOperationException(
+                            $"TestRunner Setup/Teardown references unknown step '{name}' — define it under TestRunner:Steps.");
+                    }
+                    continue;
+                }
+                var step = ReadStep(child);
+                if (step is not null)
                 {
                     list.Add(step);
                 }
diff --git a/NpgsqlRestClient/Config.cs b/NpgsqlRestClient/Config.cs
index 2678f8cf..ba1cf919 100644
--- a/NpgsqlRestClient/Config.cs
+++ b/NpgsqlRestClient/Config.cs
@@ -109,9 +109,16 @@ public void Build(string[] args, string[] skip)
             // process and stable across the whole config — usable wherever {ENV} placeholders are
             // (connection strings, TestRunner Setup/Teardown). E.g. a test DB named per run:
             //   "ConnectionStrings:Test": "...;Database=app_test_{rnd6};..."  +  "create database app_test_{rnd6}".
+            // When several DISTINCT tokens of the same length are needed, indexed instances {rndN_1}..{rndN_9}
+            // are each independent (e.g. {rnd3}, {rnd3_1} and {rnd3_2} are three different 3-char tokens).
             for (int n = 1; n <= 10; n++)
             {
-                EnvDict[string.Concat("rnd", n.ToString(System.Globalization.CultureInfo.InvariantCulture))] = RandomToken(n);
+                var nStr = n.ToString(System.Globalization.CultureInfo.InvariantCulture);
+                EnvDict[string.Concat("rnd", nStr)] = RandomToken(n);
+                for (int m = 1; m <= 9; m++)
+                {
+                    EnvDict[string.Concat("rnd", nStr, "_", m.ToString(System.Globalization.CultureInfo.InvariantCulture))] = RandomToken(n);
+                }
             }
         }
 
diff --git a/NpgsqlRestClient/ConfigDefaults.cs b/NpgsqlRestClient/ConfigDefaults.cs
index b47ec6da..f6e6a7f6 100644
--- a/NpgsqlRestClient/ConfigDefaults.cs
+++ b/NpgsqlRestClient/ConfigDefaults.cs
@@ -1123,6 +1123,7 @@ private static JsonObject GetTestRunnerDefaults()
                     ["IsSuccess"] = "is_success"
                 }
             },
+            ["Steps"] = new JsonObject(),
             ["Setup"] = new JsonArray(),
             ["Teardown"] = new JsonArray()
         };
diff --git a/NpgsqlRestClient/ConfigSchemaGenerator.cs b/NpgsqlRestClient/ConfigSchemaGenerator.cs
index 959d8a45..01f0031f 100644
--- a/NpgsqlRestClient/ConfigSchemaGenerator.cs
+++ b/NpgsqlRestClient/ConfigSchemaGenerator.cs
@@ -248,7 +248,7 @@ public static partial class ConfigSchemaGenerator
         ["Stats:ActivityPath"] = "Path for current database activity.\nReturns data from pg_stat_activity showing active sessions, queries, and wait events.\nSecurity Consideration: Shows currently running queries which may contain sensitive data.",
         ["TestRunner"] = "SQL test runner. Invoked with the `--test` command-line flag (otherwise inert).\nDiscovers *.test.sql files, runs each in an isolated non-pooled connection, can invoke endpoints in-process from an embedded `/* GET /path */` block (response captured into a temp table), and asserts via boolean-returning SELECTs or `do $$ ... assert ... $$;` blocks.\nExit codes: 0 pass, 1 failures, 2 errors, 3 config/runner error, 4 no tests found.",
         ["TestRunner:FilePattern"] = "Glob (same engine as SqlFileSource) selecting *.test.sql files. Empty disables discovery.\nCo-located convention: app.sql (endpoint) next to app.test.sql (test).",
-        ["TestRunner:ConnectionName"] = "Optional: a ConnectionStrings entry to run the tests against instead of the app's main connection.\nIn test mode it becomes the connection used for endpoint type-checking (Describe) and execution, so it can point at a dedicated test database that a Setup step creates first (it need not exist at startup). Empty = use the main connection.\nTip: {rnd1}..{rnd10} are random lowercase tokens (length = the digit), stable for the whole run, usable in any connection string or Setup/Teardown SQL (e.g. Database=app_test_{rnd6}).",
+        ["TestRunner:ConnectionName"] = "Optional: a ConnectionStrings entry to run the tests against instead of the app's main connection.\nIn test mode it becomes the connection used for endpoint type-checking (Describe) and execution, so it can point at a dedicated test database that a Setup step creates first (it need not exist at startup). Empty = use the main connection.\nTip: {rnd1}..{rnd10} are random lowercase tokens (length = the digit), stable for the whole run, usable in any connection string or Setup/Teardown SQL (e.g. Database=app_test_{rnd6}). Need several distinct tokens of the same length? Indexed instances {rndN_1}..{rndN_9} are each independent.",
         ["TestRunner:MaxParallelism"] = "Max test files run concurrently. 0 => processor count. Each test uses its own non-pooled connection.",
         ["TestRunner:FailFast"] = "Stop scheduling new tests after the first failure/error (in-flight tests still finish).",
         ["TestRunner:PerTestTimeout"] = "Per-test timeout. Accepts \"30s\", \"5m\", \"1h\", a plain number of seconds, or \"hh:mm:ss\". 0 disables.",
@@ -260,8 +260,9 @@ public static partial class ConfigSchemaGenerator
         ["TestRunner:ResponseTempTable:Name"] = "Temp table name used when a test file has exactly ONE HTTP block.\nEach HTTP block gets its own fresh temp table (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified. Per-block override: `# @response <name>`.",
         ["TestRunner:ResponseTempTable:MultiNamePattern"] = "Temp table name pattern used when a test file has 2+ HTTP blocks.\n{n} is the 1-based block ordinal, e.g. \"_response_{n}\" => _response_1, _response_2, …",
         ["TestRunner:ResponseTempTable:Columns"] = "Maps each response component to a column name. A null or empty name omits that column.",
-        ["TestRunner:Setup"] = "Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written.\nEach entry is one of: { \"Command\": \"...\", \"WorkingDirectory\": \"...\" } (OS shell); { \"Sql\": \"...\" } | { \"SqlFile\": \"...\" } which run on the test connection, or set \"ConnectionName\" to run on another ConnectionStrings entry (e.g. an admin connection that runs `create database`).",
-        ["TestRunner:Teardown"] = "Run-once teardown, ALWAYS (best-effort), in the EXACT order written. Same step shapes as Setup (e.g. a `drop database` on an admin connection). The `Keep` option skips it.",
+        ["TestRunner:Steps"] = "Named, reusable steps (name → step; same shape as Setup/Teardown entries). Reference them by name in Setup/Teardown, or from an individual test file's leading header comments:\n-- @setup StepName [StepName ...] (runs before that file); -- @teardown StepName [StepName ...] (runs after that file, always, best-effort); -- @connection Name (runs that file on a named ConnectionStrings entry).\nAnnotations are repeatable; names may be whitespace- or comma-separated and run in the order written.\nTest files can also reuse SQL scripts in place with psql-style includes: `\\i file` (cwd-relative) or `\\ir file` (relative to the including file) — executed on the test's connection, inside its transaction.",
+        ["TestRunner:Setup"] = "Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written.\nEach entry is a step NAME from \"Steps\", or an inline object: { \"Command\": \"...\", \"WorkingDirectory\": \"...\" } (OS shell); { \"Sql\": \"...\" } | { \"SqlFile\": \"...\" } which run on the test connection, or set \"ConnectionName\" to run on another ConnectionStrings entry (e.g. an admin connection that runs `create database`).",
+        ["TestRunner:Teardown"] = "Run-once teardown, ALWAYS (best-effort), in the EXACT order written. Same entries as Setup (step names or inline objects, e.g. a `drop database` on an admin connection). The `Keep` option skips it.",
         ["CommandRetryOptions"] = "Command retry strategies and options for client and middleware commands.",
         ["CommandRetryOptions:Strategies:default:RetrySequenceSeconds"] = "Retry sequence in seconds. Accepts decimal numbers (0.25 is quarter of a second). The length of the array determines the maximum number of retries.",
         ["CommandRetryOptions:Strategies:default:ErrorCodes"] = "Error codes that will trigger a retry when executing a command. See https://www.postgresql.org/docs/current/errcodes-appendix.html",
diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index fe68090e..f0fe916f 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -1453,6 +1453,7 @@ public static partial class ConfigSchemaGenerator
         // point at a dedicated test database that a Setup step creates first (it need not exist at startup).
         // Empty = use the main connection. Tip: {rnd1}..{rnd10} are random lowercase tokens (length = the digit),
         // stable for the whole run, usable in any connection string or Setup/Teardown SQL (e.g. Database=app_test_{rnd6}).
+        // Need several distinct tokens of the same length? Indexed instances {rndN_1}..{rndN_9} are each independent.
         //
         "ConnectionName": "",
         //
@@ -1509,7 +1510,19 @@ public static partial class ConfigSchemaGenerator
           }
         },
         //
-        // Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written. Each entry is one of:
+        // Named, reusable steps (name → step; same shape as Setup/Teardown entries). Reference them by name in
+        // Setup/Teardown below, or from an individual test file's leading header comments:
+        //   -- @setup StepName [StepName ...]      runs before that file
+        //   -- @teardown StepName [StepName ...]   runs after that file (always, best-effort)
+        //   -- @connection Name                    runs that file on a named ConnectionStrings entry
+        // Annotations are repeatable; names may be whitespace- or comma-separated and run in the order written.
+        // Test files can also reuse SQL scripts in place with psql-style includes: `\i file` (cwd-relative) or
+        // `\ir file` (relative to the including file) — executed on the test's connection, inside its transaction.
+        //
+        "Steps": {},
+        //
+        // Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written. Each entry is a step
+        // NAME from "Steps" above, or an inline step object:
         //   { "Command": "...", "WorkingDirectory": "..." }    — runs via the OS shell
         //   { "Sql": "..." } | { "SqlFile": "..." }            — runs on the test connection; set "ConnectionName"
         //                                                         to run on another ConnectionStrings entry (e.g.
@@ -1517,7 +1530,7 @@ public static partial class ConfigSchemaGenerator
         //
         "Setup": [],
         //
-        // Run-once teardown, ALWAYS (best-effort), in the EXACT order written. `Keep` skips it. Same step shapes as Setup.
+        // Run-once teardown, ALWAYS (best-effort), in the EXACT order written. `Keep` skips it. Same entries as Setup.
         //
         "Teardown": []
       },
diff --git a/NpgsqlRestClient/Program.cs b/NpgsqlRestClient/Program.cs
index 5444b9b7..090a2e22 100644
--- a/NpgsqlRestClient/Program.cs
+++ b/NpgsqlRestClient/Program.cs
@@ -500,7 +500,18 @@
     var logTestNotices = options.LogConnectionNoticeEvents;
     options.LogConnectionNoticeEvents = false;
 
-    testRunner = new NpgsqlRestClient.Testing.TestRunner(options, builder.BuildTestRunnerOptions(), connectionString, builder.TestLogger, logTestNotices, builder.BuildTestRunnerConnectionStrings());
+    try
+    {
+        testRunner = new NpgsqlRestClient.Testing.TestRunner(options, builder.BuildTestRunnerOptions(), connectionString, builder.TestLogger, logTestNotices, builder.BuildTestRunnerConnectionStrings());
+    }
+    catch (Exception ex)
+    {
+        // Configuration error (e.g. a Setup/Teardown entry referencing an unknown named step).
+        new Out().Line($"Test runner configuration error: {ex.Message}", ConsoleColor.Red);
+        builder.TestLogger?.LogError(ex, "Test runner configuration error");
+        Environment.ExitCode = NpgsqlRestClient.Testing.TestRunner.ExitConfig;
+        return;
+    }
     if (await testRunner.SetupAsync() is false)
     {
         Environment.ExitCode = NpgsqlRestClient.Testing.TestRunner.ExitConfig;
diff --git a/NpgsqlRestClient/Testing/SqlTestFileParser.cs b/NpgsqlRestClient/Testing/SqlTestFileParser.cs
index bc8bc385..029501e6 100644
--- a/NpgsqlRestClient/Testing/SqlTestFileParser.cs
+++ b/NpgsqlRestClient/Testing/SqlTestFileParser.cs
@@ -3,16 +3,46 @@
 namespace NpgsqlRestClient.Testing;
 
 /// <summary>
-/// Splits a .test.sql file into an ordered list of steps (SQL statements and embedded HTTP requests),
-/// preserving interleaving. A char-by-char state machine handles ';' statement splitting, line/block
-/// comments, single quotes (with '' escapes), and dollar-quoted strings / DO blocks (so semicolons inside
-/// them don't split). A block comment whose first line is a request line becomes an <see cref="HttpStep"/>;
-/// any other comment is ignored.
+/// Splits a .test.sql file into an ordered list of steps (SQL statements, embedded HTTP requests, and
+/// include lines), preserving interleaving. A char-by-char state machine handles ';' statement splitting,
+/// line/block comments, single quotes (with '' escapes), and dollar-quoted strings / DO blocks (so
+/// semicolons inside them don't split). A block comment whose first line is a request line becomes an
+/// <see cref="HttpStep"/>; any other comment is ignored. A line starting with <c>\i</c>/<c>\ir</c> between
+/// statements becomes an <see cref="IncludeStep"/> (expanded by <see cref="TestFileLoader"/>).
 /// </summary>
 public static class SqlTestFileParser
 {
     private enum State { Normal, BlockComment, SingleQuote, DollarQuote }
 
+    /// <summary>
+    /// Parses one line as an include: <c>\i path</c> (cwd-relative) or <c>\ir path</c> (relative to the
+    /// including file). The path may be single-quoted; a trailing ';' is forgiven. Returns false for any
+    /// other line (including other backslash commands).
+    /// </summary>
+    internal static bool TryParseIncludeLine(string line, out string path, out bool relativeToFile)
+    {
+        path = "";
+        relativeToFile = false;
+        var t = line.Trim();
+        bool relative = t.StartsWith("\\ir", StringComparison.OrdinalIgnoreCase)
+            && (t.Length == 3 || char.IsWhiteSpace(t[3]));
+        bool plain = !relative && t.StartsWith("\\i", StringComparison.OrdinalIgnoreCase)
+            && (t.Length == 2 || char.IsWhiteSpace(t[2]));
+        if (!relative && !plain) return false;
+
+        var p = t[(relative ? 3 : 2)..].Trim();
+        if (p.EndsWith(';')) p = p[..^1].TrimEnd();          // forgive a trailing ;
+        if (p.Length > 1 && p[0] == '\'' && p[^1] == '\'')
+        {
+            p = p[1..^1];                                     // psql-style quoted path
+        }
+        if (p.Length == 0) return false;
+
+        path = p;
+        relativeToFile = relative;
+        return true;
+    }
+
     public static List<TestStep> Parse(string content)
     {
         var steps = new List<TestStep>();
@@ -63,6 +93,29 @@ void FlushSql()
             switch (state)
             {
                 case State.Normal:
+                    // include: \i <path> (cwd-relative) or \ir <path> (relative to the including file) —
+                    // psql semantics. Recognized only between statements (pending statement is blank), so a
+                    // backslash inside SQL text/strings/dollar-quotes is never misread. Consumes the line.
+                    if (c == '\\' && !stmtHasContent)
+                    {
+                        int lineEnd = i;
+                        while (lineEnd < len && content[lineEnd] != '\n') lineEnd++;
+                        var includeLine = content[i..lineEnd].TrimEnd('\r').TrimEnd();
+                        if (TryParseIncludeLine(includeLine, out var path, out var relative))
+                        {
+                            steps.Add(new IncludeStep(path, relative, currentLine));
+                            i = lineEnd; // consume the include line; the newline is handled by the main loop
+                            continue;
+                        }
+                        // Not \i/\ir: keep just the backslash as SQL text and let normal parsing continue
+                        // (';' still splits; PostgreSQL will report the stray backslash clearly).
+                        stmt.Append(c);
+                        MarkContent();
+                        lastToken = "";
+                        lastTokenIsWord = false;
+                        i++;
+                        continue;
+                    }
                     // line comment: -- (skip to end of line, never an HTTP step)
                     if (c == '-' && i + 1 < len && content[i + 1] == '-')
                     {
diff --git a/NpgsqlRestClient/Testing/TestFileLoader.cs b/NpgsqlRestClient/Testing/TestFileLoader.cs
new file mode 100644
index 00000000..310bc45f
--- /dev/null
+++ b/NpgsqlRestClient/Testing/TestFileLoader.cs
@@ -0,0 +1,168 @@
+namespace NpgsqlRestClient.Testing;
+
+/// <summary>
+/// Per-file header annotations, read from the LEADING line comments of a test file (scanning stops at the
+/// first line that is neither blank, a <c>--</c> comment, nor an include):
+/// <code>
+/// -- @setup StepName [StepName ...]      (run before this file; names from TestRunner:Steps)
+/// -- @teardown StepName [StepName ...]   (run after this file, always, best-effort)
+/// -- @connection Name                    (run this file on a named ConnectionStrings entry)
+/// </code>
+/// Annotations are repeatable and names accumulate in written order; multiple names on one line may be
+/// separated by whitespace or commas (`@setup A B` == `@setup A, B` — the NpgsqlRest annotation idiom).
+/// Other comment lines are ignored, so ordinary file documentation can freely surround the annotations.
+/// An include (<c>\i</c>/<c>\ir</c>) in the header region is scanned AS IF PASTED: annotations in the
+/// included file's own leading comments count, and the header ends where the pasted content's first
+/// statement would be — so a shared "profile" file of annotations can be attached with one include line.
+/// </summary>
+public sealed class TestFileHeader
+{
+    public List<string> Setup { get; } = [];
+    public List<string> Teardown { get; } = [];
+    public string? ConnectionName { get; private set; }
+
+    public static TestFileHeader Parse(string content, string? sourceFile = null)
+    {
+        var header = new TestFileHeader();
+        var visited = new HashSet<string>(StringComparer.Ordinal);
+        if (sourceFile is not null)
+        {
+            visited.Add(Path.GetFullPath(sourceFile));
+        }
+        Scan(content, sourceFile, header, visited, depth: 0);
+        return header;
+    }
+
+    // Scans the leading header region; returns false when a statement ended the header (so an including
+    // file must stop scanning too — paste semantics), true when the whole content was header material.
+    private static bool Scan(string content, string? sourceFile, TestFileHeader header, HashSet<string> visited, int depth)
+    {
+        foreach (var rawLine in content.Split('\n'))
+        {
+            var line = rawLine.TrimEnd('\r').Trim();
+            if (line.Length == 0) continue;
+
+            if (line.StartsWith("--"))
+            {
+                var comment = line[2..].TrimStart();
+                if (!comment.StartsWith('@')) continue;
+
+                // Names are separated by whitespace and/or commas (CSV works: `@setup A, B` == `@setup A B`).
+                var tokens = comment[1..].Split([' ', '\t', ','], StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+                if (tokens.Length < 2) continue;
+
+                if (string.Equals(tokens[0], "setup", StringComparison.OrdinalIgnoreCase))
+                {
+                    header.Setup.AddRange(tokens[1..]);
+                }
+                else if (string.Equals(tokens[0], "teardown", StringComparison.OrdinalIgnoreCase))
+                {
+                    header.Teardown.AddRange(tokens[1..]);
+                }
+                else if (string.Equals(tokens[0], "connection", StringComparison.OrdinalIgnoreCase))
+                {
+                    header.ConnectionName = tokens[1];
+                }
+                // any other @word is an ordinary comment — ignored
+                continue;
+            }
+
+            if (SqlTestFileParser.TryParseIncludeLine(line, out var incPath, out var relative))
+            {
+                if (depth >= 16)
+                {
+                    throw new InvalidOperationException($"include nesting deeper than 16 at '{incPath}' while reading header annotations");
+                }
+                var baseDir = relative && sourceFile is not null
+                    ? Path.GetDirectoryName(Path.GetFullPath(sourceFile))!
+                    : Environment.CurrentDirectory;
+                var fullPath = Path.GetFullPath(incPath, baseDir);
+                if (!File.Exists(fullPath))
+                {
+                    throw new InvalidOperationException($"include not found: '{incPath}' resolved to '{fullPath}' while reading header annotations");
+                }
+                if (!visited.Add(fullPath))
+                {
+                    throw new InvalidOperationException($"circular include: '{fullPath}' while reading header annotations");
+                }
+                var keepScanning = Scan(File.ReadAllText(fullPath), fullPath, header, visited, depth + 1);
+                visited.Remove(fullPath);
+                if (!keepScanning)
+                {
+                    return false; // the pasted content contained a statement — the header ends there
+                }
+                continue; // comments/annotations-only include — the header continues in this file
+            }
+
+            return false; // first statement (or HTTP block start) ends the header
+        }
+        return true;
+    }
+}
+
+/// <summary>
+/// Loads parsed steps with <c>\i</c>/<c>\ir</c> includes expanded in place — paste semantics: each include
+/// line is replaced by the included file's parsed steps (SQL statements and HTTP blocks alike), recursively
+/// (cycle-safe, depth-capped). Included steps carry <see cref="TestStep.SourceFile"/> so failures are
+/// attributed to the included file and line.
+/// </summary>
+public static class TestFileLoader
+{
+    private const int MaxIncludeDepth = 16;
+
+    /// <summary>
+    /// Parses <paramref name="content"/> and expands include steps. <paramref name="sourceFile"/> is the
+    /// full path of the file the content came from (used to resolve <c>\ir</c> and for attribution); null
+    /// for inline SQL, in which case <c>\ir</c> falls back to cwd-relative like <c>\i</c>.
+    /// </summary>
+    public static List<TestStep> LoadSteps(string content, string? sourceFile)
+    {
+        var visited = new HashSet<string>(StringComparer.Ordinal);
+        if (sourceFile is not null)
+        {
+            visited.Add(Path.GetFullPath(sourceFile));
+        }
+        return Expand(SqlTestFileParser.Parse(content), sourceFile, isIncluded: false, visited, depth: 0);
+    }
+
+    private static List<TestStep> Expand(List<TestStep> steps, string? sourceFile, bool isIncluded, HashSet<string> visited, int depth)
+    {
+        var result = new List<TestStep>(steps.Count);
+        foreach (var step in steps)
+        {
+            if (step is not IncludeStep inc)
+            {
+                if (isIncluded)
+                {
+                    step.SourceFile = sourceFile;
+                }
+                result.Add(step);
+                continue;
+            }
+
+            var from = isIncluded ? sourceFile : null;
+            var baseDir = inc.RelativeToFile && sourceFile is not null
+                ? Path.GetDirectoryName(Path.GetFullPath(sourceFile))!
+                : Environment.CurrentDirectory;
+            var fullPath = Path.GetFullPath(inc.Path, baseDir);
+
+            if (depth >= MaxIncludeDepth)
+            {
+                throw new InvalidOperationException($"include nesting deeper than {MaxIncludeDepth} at '{inc.Path}' (line {inc.LineNumber}{(from is null ? "" : $" of {from}")})");
+            }
+            if (!File.Exists(fullPath))
+            {
+                throw new InvalidOperationException($"include not found: '{inc.Path}' resolved to '{fullPath}' (line {inc.LineNumber}{(from is null ? "" : $" of {from}")})");
+            }
+            if (!visited.Add(fullPath))
+            {
+                throw new InvalidOperationException($"circular include: '{fullPath}' (line {inc.LineNumber}{(from is null ? "" : $" of {from}")})");
+            }
+
+            var inner = SqlTestFileParser.Parse(File.ReadAllText(fullPath));
+            result.AddRange(Expand(inner, fullPath, isIncluded: true, visited, depth + 1));
+            visited.Remove(fullPath);
+        }
+        return result;
+    }
+}
diff --git a/NpgsqlRestClient/Testing/TestRunner.cs b/NpgsqlRestClient/Testing/TestRunner.cs
index 07386f8d..4f27bcc0 100644
--- a/NpgsqlRestClient/Testing/TestRunner.cs
+++ b/NpgsqlRestClient/Testing/TestRunner.cs
@@ -55,6 +55,8 @@ private sealed class AssertionResult
         public Outcome Outcome { get; init; }
         public string? Message { get; init; }
         public string? Sql { get; init; }
+        /// <summary>Full path of the included file this assertion came from (via \i/\ir); null = the test file.</summary>
+        public string? SourceFile { get; init; }
     }
 
     // A test file groups its assertions; the file's outcome is the worst of them (Error > Fail > Pass).
@@ -104,7 +106,7 @@ public async Task<bool> SetupAsync(CancellationToken ct = default)
             // (ConnectionName, else the test connection); Command steps run via the OS shell.
             foreach (var step in _opt.Setup)
             {
-                await RunStepAsync(step, ct);
+                await RunStepAsync(step, "setup", ct);
             }
             return true;
         }
@@ -118,17 +120,18 @@ public async Task<bool> SetupAsync(CancellationToken ct = default)
     }
 
     // Runs one Setup/Teardown step: a shell Command, or a Sql/SqlFile batch on its resolved connection.
-    private async Task RunStepAsync(TestSetupStep step, CancellationToken ct)
+    // `phase` ("setup" | "teardown") is only used to label the step's log lines.
+    private async Task RunStepAsync(TestSetupStep step, string phase, CancellationToken ct)
     {
         if (step.IsCommand)
         {
-            await RunCommandAsync(step, ct);
+            await RunCommandAsync(step, phase, ct);
             return;
         }
         var connStr = ResolveStepConnection(step);
         await using var conn = new NpgsqlConnection(connStr);
         await conn.OpenAsync(ct);
-        await RunSqlStepAsync(conn, step, ct);
+        await RunSqlStepAsync(conn, step, phase, ct);
     }
 
     // A step's connection: its explicit ConnectionName (a ConnectionStrings entry), else the test connection.
@@ -209,9 +212,76 @@ private async Task<FileResult> RunFileAsync(string file, IReadOnlyDictionary<str
         var ct = perTestCts.Token;
         int timeoutSecs = _opt.PerTestTimeout > TimeSpan.Zero ? (int)Math.Ceiling(_opt.PerTestTimeout.TotalSeconds) : 0;
 
+        // Header annotations (leading -- comments): per-file setup/teardown step names + connection override.
+        string content;
+        TestFileHeader header;
         try
         {
-            conn = new NpgsqlConnection(_connString);
+            content = await File.ReadAllTextAsync(file, ct);
+            header = TestFileHeader.Parse(content, file);
+        }
+        catch (Exception ex)
+        {
+            result.Assertions.Add(new AssertionResult { Name = "file read error", Outcome = Outcome.Error, Message = ex.Message });
+            result.ElapsedMs = sw.ElapsedMilliseconds;
+            return result;
+        }
+
+        // `-- @connection Name` runs this file (and its in-process endpoint calls) on a named connection —
+        // e.g. a per-test database that a `-- @setup` step below creates from a template.
+        string connString = _connString;
+        if (header.ConnectionName is not null)
+        {
+            if (_named.TryGetValue(header.ConnectionName, out var cs))
+            {
+                connString = cs;
+            }
+            else
+            {
+                result.Assertions.Add(new AssertionResult
+                {
+                    Name = $"-- @connection {header.ConnectionName}",
+                    Outcome = Outcome.Error,
+                    Message = $"'{header.ConnectionName}' has no matching entry under 'ConnectionStrings'",
+                });
+                result.ElapsedMs = sw.ElapsedMilliseconds;
+                return result;
+            }
+        }
+
+        // Per-file setup steps — BEFORE the file's connection opens (a step may create the very database
+        // the connection targets). Each runs like a global step: own connection, committed work.
+        bool setupOk = true;
+        foreach (var name in header.Setup)
+        {
+            if (!_opt.Steps.TryGetValue(name, out var st))
+            {
+                result.Assertions.Add(new AssertionResult
+                {
+                    Name = $"-- @setup {name}",
+                    Outcome = Outcome.Error,
+                    Message = $"unknown step '{name}' — define it under TestRunner:Steps",
+                });
+                setupOk = false;
+                break;
+            }
+            try
+            {
+                _log?.LogDebug("{File}: @setup {Step}", contextName, name);
+                await RunStepAsync(st, "setup", ct);
+            }
+            catch (Exception ex)
+            {
+                result.Assertions.Add(new AssertionResult { Name = $"-- @setup {name}", Outcome = Outcome.Error, Message = ex.Message });
+                setupOk = false;
+                break;
+            }
+        }
+
+        if (setupOk)
+        try
+        {
+            conn = new NpgsqlConnection(connString);
             conn.Notice += (_, e) =>
             {
                 // Route notices through the test runner's own log channel, tagged with this test file. The
@@ -224,7 +294,10 @@ private async Task<FileResult> RunFileAsync(string file, IReadOnlyDictionary<str
             await conn.OpenAsync(ct);
             Ambient.Value = conn;
 
-            var steps = SqlTestFileParser.Parse(await File.ReadAllTextAsync(file, ct));
+            // Parse + expand \i/\ir includes — paste semantics: included statements AND HTTP blocks execute
+            // in place (HTTP blocks participate in _response_{n} numbering exactly as if pasted); included
+            // steps carry SourceFile so failures are attributed to the included file and line.
+            var steps = TestFileLoader.LoadSteps(content, file);
 
             int httpTotal = steps.Count(s => s is HttpStep);
             int httpOrdinal = 0;
@@ -267,6 +340,7 @@ private async Task<FileResult> RunFileAsync(string file, IReadOnlyDictionary<str
                         Outcome = sr.Outcome,
                         Message = sr.Message,
                         Sql = step is SqlStep s ? s.Text : null,
+                        SourceFile = step.SourceFile,
                     });
                 }
                 // Fail-fast within a file: a failed/errored step (a failing DO-block assert aborts the PG
@@ -297,6 +371,27 @@ private async Task<FileResult> RunFileAsync(string file, IReadOnlyDictionary<str
             if (conn is not null) await conn.DisposeAsync();
         }
 
+        // Per-file teardown — ALWAYS (best-effort), even when setup or the body failed, and AFTER the
+        // file's connection is closed (so e.g. `drop database ... with (force)` succeeds). Uses the run
+        // token, not the per-test one, so a timed-out test still gets its teardown.
+        foreach (var name in header.Teardown)
+        {
+            if (!_opt.Steps.TryGetValue(name, out var st))
+            {
+                _log?.LogWarning("{File}: @teardown references unknown step '{Step}' — define it under TestRunner:Steps", contextName, name);
+                continue;
+            }
+            try
+            {
+                _log?.LogDebug("{File}: @teardown {Step}", contextName, name);
+                await RunStepAsync(st, "teardown", runCt);
+            }
+            catch (Exception ex)
+            {
+                _log?.LogWarning(ex, "{File}: @teardown step '{Step}' failed", contextName, name);
+            }
+        }
+
         result.ElapsedMs = sw.ElapsedMilliseconds;
         result.Notices = notices;
         _log?.LogDebug("{File}: {Outcome} ({Count} assertion(s), {Ms}ms)",
@@ -471,7 +566,7 @@ private string ResolveResponseTable(HttpStep http, int ordinal, int httpTotal)
 
     // -------- Setup/Teardown step execution --------
 
-    private async Task RunCommandAsync(TestSetupStep step, CancellationToken ct)
+    private async Task RunCommandAsync(TestSetupStep step, string phase, CancellationToken ct)
     {
         var psi = new ProcessStartInfo
         {
@@ -486,7 +581,14 @@ private async Task RunCommandAsync(TestSetupStep step, CancellationToken ct)
         psi.ArgumentList.Add(OperatingSystem.IsWindows() ? "/c" : "-c");
         psi.ArgumentList.Add(step.Command!);
 
-        _log?.LogDebug("setup/teardown command: {Command}", step.Command);
+        if (step.Name is not null)
+        {
+            _log?.LogDebug("{Phase} command step {Step}: {Command}", phase, step.Name, step.Command);
+        }
+        else
+        {
+            _log?.LogDebug("{Phase} command: {Command}", phase, step.Command);
+        }
         using var proc = new Process { StartInfo = psi };
         proc.Start();
         var stdout = await proc.StandardOutput.ReadToEndAsync(ct);
@@ -500,22 +602,34 @@ private async Task RunCommandAsync(TestSetupStep step, CancellationToken ct)
         }
     }
 
-    private async Task RunSqlStepAsync(NpgsqlConnection conn, TestSetupStep step, CancellationToken ct)
+    private async Task RunSqlStepAsync(NpgsqlConnection conn, TestSetupStep step, string phase, CancellationToken ct)
     {
         string sql;
+        string? sourceFile = null;
         if (!string.IsNullOrWhiteSpace(step.SqlFile))
         {
-            sql = await File.ReadAllTextAsync(Path.GetFullPath(step.SqlFile), ct);
+            sourceFile = Path.GetFullPath(step.SqlFile);
+            sql = await File.ReadAllTextAsync(sourceFile, ct);
         }
         else
         {
             sql = step.Sql ?? "";
         }
         if (string.IsNullOrWhiteSpace(sql)) return;
-        _log?.LogDebug("setup/teardown sql: {Source}", step.SqlFile ?? "(inline)");
-        // Split into individual statements (SQL-rewriting is disabled → one statement per command).
-        // Reuses the test-file parser; DO blocks / dollar-quoted bodies stay whole.
-        foreach (var parsed in SqlTestFileParser.Parse(sql))
+        // Announce phase + name + what it does: the file path for SqlFile steps (their statements log at
+        // Verbose), or the (placeholder-resolved) SQL itself for inline steps, capped to its first line.
+        var code = !string.IsNullOrWhiteSpace(step.SqlFile) ? step.SqlFile : FirstLine(sql);
+        if (step.Name is not null)
+        {
+            _log?.LogDebug("{Phase} step {Step}: {Code}", phase, step.Name, code);
+        }
+        else
+        {
+            _log?.LogDebug("{Phase} sql step: {Code}", phase, code);
+        }
+        // Split into individual statements (SQL-rewriting is disabled → one statement per command) with
+        // \i/\ir includes expanded. Reuses the test-file parser; DO blocks / dollar-quoted bodies stay whole.
+        foreach (var parsed in TestFileLoader.LoadSteps(sql, sourceFile))
         {
             if (parsed is SqlStep s)
             {
@@ -533,7 +647,7 @@ private async Task TeardownAsync(CancellationToken ct)
         // Strict declared order, best-effort: a failing step is logged and the rest still run.
         foreach (var step in _opt.Teardown)
         {
-            try { await RunStepAsync(step, ct); }
+            try { await RunStepAsync(step, "teardown", ct); }
             catch (Exception ex) { _log?.LogWarning(ex, "teardown step failed"); }
         }
     }
@@ -631,7 +745,8 @@ private void ReportConsole(List<FileResult> results)
                         if (_opt.DetailedReport) _out.Line($"        ✓ {a.Name}", ConsoleColor.DarkGray);
                         continue;
                     }
-                    var loc = a.Line is null ? "" : $"  [{rel}:{a.Line}]";
+                    var locFile = a.SourceFile is null ? rel : Path.GetRelativePath(Environment.CurrentDirectory, a.SourceFile);
+                    var loc = a.Line is null ? "" : $"  [{locFile}:{a.Line}]";
                     _out.LineAnsi($"        ✗ {a.Name}{loc}", AnsiFail);
                     if (!string.IsNullOrWhiteSpace(a.Message) && a.Message != a.Name) _out.LineAnsi($"          {a.Message}", AnsiFail);
                     WriteFailingSql(a.Sql);
@@ -689,9 +804,9 @@ private static void WriteJUnit(List<FileResult> results, string path)
                     new XAttribute("classname", fr.File),
                     new XAttribute("time", caseTimeStr));
                 if (a.Outcome == Outcome.Fail)
-                    tc.Add(new XElement("failure", new XAttribute("message", a.Message ?? "assertion failed"), $"{fr.File}{(a.Line is null ? "" : $":{a.Line}")}"));
+                    tc.Add(new XElement("failure", new XAttribute("message", a.Message ?? "assertion failed"), $"{a.SourceFile ?? fr.File}{(a.Line is null ? "" : $":{a.Line}")}"));
                 else if (a.Outcome == Outcome.Error)
-                    tc.Add(new XElement("error", new XAttribute("message", a.Message ?? "error"), $"{fr.File}{(a.Line is null ? "" : $":{a.Line}")}"));
+                    tc.Add(new XElement("error", new XAttribute("message", a.Message ?? "error"), $"{a.SourceFile ?? fr.File}{(a.Line is null ? "" : $":{a.Line}")}"));
                 if (a.Outcome != Outcome.Pass && fr.Notices.Count > 0)
                     tc.Add(new XElement("system-out", string.Join('\n', fr.Notices)));
                 suite.Add(tc);
diff --git a/NpgsqlRestClient/Testing/TestRunnerOptions.cs b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
index 53b47018..d61133e9 100644
--- a/NpgsqlRestClient/Testing/TestRunnerOptions.cs
+++ b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
@@ -50,10 +50,16 @@ public class TestRunnerOptions
 
     public ResponseTempTableOptions ResponseTempTable { get; set; } = new();
 
-    /// <summary>Run-once setup, before endpoint discovery. Commands run first, then SqlFile/Sql (declared order within each group).</summary>
+    /// <summary>
+    /// Named, reusable steps (name → step). Referenced by name from <see cref="Setup"/>/<see cref="Teardown"/>
+    /// or from an individual test file header (<c>-- @setup Name</c> / <c>-- @teardown Name</c>).
+    /// </summary>
+    public Dictionary<string, TestSetupStep> Steps { get; set; } = new(StringComparer.OrdinalIgnoreCase);
+
+    /// <summary>Run-once setup, before endpoint discovery, in the exact order written.</summary>
     public List<TestSetupStep> Setup { get; set; } = [];
 
-    /// <summary>Run-once teardown, always (best-effort). Reverse: SqlFile/Sql first, then Commands.</summary>
+    /// <summary>Run-once teardown, always (best-effort), in the exact order written.</summary>
     public List<TestSetupStep> Teardown { get; set; } = [];
 }
 
@@ -81,6 +87,9 @@ public class ResponseColumnOptions
 /// <summary>One Setup/Teardown step — exactly one of Sql / SqlFile / Command.</summary>
 public class TestSetupStep
 {
+    /// <summary>Registry name when the step is defined under <c>Steps</c>; null for inline steps. Used in logs.</summary>
+    public string? Name { get; set; }
+
     /// <summary>Inline SQL executed as a single batch.</summary>
     public string? Sql { get; set; }
 
diff --git a/NpgsqlRestClient/Testing/TestStep.cs b/NpgsqlRestClient/Testing/TestStep.cs
index 25434d80..6d729b68 100644
--- a/NpgsqlRestClient/Testing/TestStep.cs
+++ b/NpgsqlRestClient/Testing/TestStep.cs
@@ -7,6 +7,8 @@ public enum TestStepKind
     Sql,
     /// <summary>An embedded HTTP request (a /* ... */ block whose first line is a request line).</summary>
     Http,
+    /// <summary>An include line (<c>\i file</c> or <c>\ir file</c>) — expanded into the included file's steps.</summary>
+    Include,
 }
 
 /// <summary>One ordered step in a parsed .test.sql file.</summary>
@@ -15,6 +17,11 @@ public abstract class TestStep
     public TestStepKind Kind { get; }
     /// <summary>1-based line in the source file where this step starts (for error reporting).</summary>
     public int LineNumber { get; }
+    /// <summary>
+    /// Full path of the file this step came from when it was spliced in via <c>\i</c>/<c>\ir</c>;
+    /// null when the step belongs to the file being executed itself.
+    /// </summary>
+    public string? SourceFile { get; set; }
 
     protected TestStep(TestStepKind kind, int lineNumber)
     {
@@ -23,6 +30,24 @@ protected TestStep(TestStepKind kind, int lineNumber)
     }
 }
 
+/// <summary>
+/// An include line: <c>\i path</c> (path relative to the current working directory, like every other
+/// configured path) or <c>\ir path</c> (relative to the file containing the include) — psql semantics.
+/// Expanded by <see cref="TestFileLoader"/> into the included file's steps, as if the content were pasted.
+/// </summary>
+public sealed class IncludeStep : TestStep
+{
+    public string Path { get; }
+    /// <summary>True for <c>\ir</c> (relative to the including file), false for <c>\i</c> (cwd-relative).</summary>
+    public bool RelativeToFile { get; }
+
+    public IncludeStep(string path, bool relativeToFile, int lineNumber) : base(TestStepKind.Include, lineNumber)
+    {
+        Path = path;
+        RelativeToFile = relativeToFile;
+    }
+}
+
 /// <summary>A SQL statement step — executed via ExecuteReader; a boolean first column is an assertion.</summary>
 public sealed class SqlStep : TestStep
 {
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index f61922b2..e6e83f68 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -1444,6 +1444,7 @@
     // point at a dedicated test database that a Setup step creates first (it need not exist at startup).
     // Empty = use the main connection. Tip: {rnd1}..{rnd10} are random lowercase tokens (length = the digit),
     // stable for the whole run, usable in any connection string or Setup/Teardown SQL (e.g. Database=app_test_{rnd6}).
+    // Need several distinct tokens of the same length? Indexed instances {rndN_1}..{rndN_9} are each independent.
     //
     "ConnectionName": "",
     //
@@ -1500,7 +1501,19 @@
       }
     },
     //
-    // Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written. Each entry is one of:
+    // Named, reusable steps (name → step; same shape as Setup/Teardown entries). Reference them by name in
+    // Setup/Teardown below, or from an individual test file's leading header comments:
+    //   -- @setup StepName [StepName ...]      runs before that file
+    //   -- @teardown StepName [StepName ...]   runs after that file (always, best-effort)
+    //   -- @connection Name                    runs that file on a named ConnectionStrings entry
+    // Annotations are repeatable; names may be whitespace- or comma-separated and run in the order written.
+    // Test files can also reuse SQL scripts in place with psql-style includes: `\i file` (cwd-relative) or
+    // `\ir file` (relative to the including file) — executed on the test's connection, inside its transaction.
+    //
+    "Steps": {},
+    //
+    // Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written. Each entry is a step
+    // NAME from "Steps" above, or an inline step object:
     //   { "Command": "...", "WorkingDirectory": "..." }    — runs via the OS shell
     //   { "Sql": "..." } | { "SqlFile": "..." }            — runs on the test connection; set "ConnectionName"
     //                                                         to run on another ConnectionStrings entry (e.g.
@@ -1508,7 +1521,7 @@
     //
     "Setup": [],
     //
-    // Run-once teardown, ALWAYS (best-effort), in the EXACT order written. `Keep` skips it. Same step shapes as Setup.
+    // Run-once teardown, ALWAYS (best-effort), in the EXACT order written. `Keep` skips it. Same entries as Setup.
     //
     "Teardown": []
   },
diff --git a/NpgsqlRestTests/TestRunnerTests/ParserTests/TestFileHeaderAndIncludeTests.cs b/NpgsqlRestTests/TestRunnerTests/ParserTests/TestFileHeaderAndIncludeTests.cs
new file mode 100644
index 00000000..9be06a46
--- /dev/null
+++ b/NpgsqlRestTests/TestRunnerTests/ParserTests/TestFileHeaderAndIncludeTests.cs
@@ -0,0 +1,196 @@
+using NpgsqlRestClient.Testing;
+
+namespace NpgsqlRestTests.TestRunnerTests.ParserTests;
+
+public class TestFileHeaderTests
+{
+    [Fact]
+    public void Header_Parses_Setup_Teardown_And_Connection()
+    {
+        var h = TestFileHeader.Parse("-- @setup CreateDb ApplyMigrations\n-- @teardown DropDb\n-- @connection Isolated\n\nselect 1;");
+        h.Setup.Should().Equal("CreateDb", "ApplyMigrations");
+        h.Teardown.Should().Equal("DropDb");
+        h.ConnectionName.Should().Be("Isolated");
+    }
+
+    [Fact]
+    public void Header_Annotations_Are_Repeatable_And_Case_Insensitive()
+    {
+        var h = TestFileHeader.Parse("-- @SETUP A\n-- @Setup B\nselect 1;");
+        h.Setup.Should().Equal("A", "B");
+    }
+
+    [Fact]
+    public void Names_May_Be_Separated_By_Whitespace_Or_Commas()
+    {
+        var h = TestFileHeader.Parse("-- @setup A, B\n-- @setup C,D  E\n-- @teardown X , Y\nselect 1;");
+        h.Setup.Should().Equal("A", "B", "C", "D", "E");
+        h.Teardown.Should().Equal("X", "Y");
+    }
+
+    [Fact]
+    public void Header_Scan_Stops_At_First_Statement()
+    {
+        var h = TestFileHeader.Parse("-- @setup A\nselect 1;\n-- @setup B");
+        h.Setup.Should().Equal("A");
+    }
+
+    [Fact]
+    public void Plain_Comments_And_Blank_Lines_Do_Not_End_The_Header()
+    {
+        var h = TestFileHeader.Parse("-- Test: something.\n\n-- more docs\n-- @teardown Drop\nselect 1;");
+        h.Teardown.Should().Equal("Drop");
+    }
+
+    [Fact]
+    public void Unknown_Annotations_And_Bare_Keywords_Are_Ignored()
+    {
+        var h = TestFileHeader.Parse("-- @author me\n-- @setup\n-- @setup X\nselect 1;");
+        h.Setup.Should().Equal("X");
+        h.Teardown.Should().BeEmpty();
+        h.ConnectionName.Should().BeNull();
+    }
+}
+
+public class IncludeParseTests
+{
+    [Fact]
+    public void Include_Lines_Are_Recognized_Between_Statements()
+    {
+        var steps = SqlTestFileParser.Parse("begin;\n\\ir fixtures/users.sql\n\\i ./global/seed.sql\nselect 1;\nrollback;");
+        steps.Should().HaveCount(5);
+        steps[1].Should().BeOfType<IncludeStep>().Which.RelativeToFile.Should().BeTrue();
+        ((IncludeStep)steps[1]).Path.Should().Be("fixtures/users.sql");
+        steps[2].Should().BeOfType<IncludeStep>().Which.RelativeToFile.Should().BeFalse();
+        ((IncludeStep)steps[2]).Path.Should().Be("./global/seed.sql");
+    }
+
+    [Fact]
+    public void Quoted_Path_And_Trailing_Semicolon_Are_Handled()
+    {
+        var steps = SqlTestFileParser.Parse("\\ir 'my fixtures/data.sql';\n");
+        steps.Should().ContainSingle().Which.Should().BeOfType<IncludeStep>()
+            .Which.Path.Should().Be("my fixtures/data.sql");
+    }
+
+    [Fact]
+    public void Backslash_Inside_A_Statement_Or_String_Is_Not_An_Include()
+    {
+        var steps = SqlTestFileParser.Parse("select '\\ir not-an-include.sql';");
+        steps.Should().ContainSingle().Which.Should().BeOfType<SqlStep>()
+            .Which.Text.Should().Contain("\\ir not-an-include.sql");
+    }
+
+    [Fact]
+    public void Unrecognized_Backslash_Line_Stays_Sql_Text()
+    {
+        var steps = SqlTestFileParser.Parse("\\echo hello;\nselect 1;");
+        steps.Should().HaveCount(2);
+        steps[0].Should().BeOfType<SqlStep>().Which.Text.Should().StartWith("\\echo");
+    }
+}
+
+public class IncludeExpansionTests : IDisposable
+{
+    private readonly string _dir = Directory.CreateTempSubdirectory("npgsqlrest-include-tests").FullName;
+
+    public void Dispose() => Directory.Delete(_dir, recursive: true);
+
+    private string Write(string name, string content)
+    {
+        var path = Path.Combine(_dir, name);
+        Directory.CreateDirectory(Path.GetDirectoryName(path)!);
+        File.WriteAllText(path, content);
+        return path;
+    }
+
+    [Fact]
+    public void Included_Statements_Are_Spliced_In_Place_With_Source_Attribution()
+    {
+        var inc = Write("fixtures/users.sql", "insert into t values (1);\ninsert into t values (2);");
+        var main = Write("main.test.sql", "begin;\n\\ir fixtures/users.sql\nselect true, 'ok';\nrollback;");
+
+        var steps = TestFileLoader.LoadSteps(File.ReadAllText(main), main);
+
+        steps.Should().HaveCount(5);
+        steps[0].SourceFile.Should().BeNull();                       // begin (main file)
+        steps[1].SourceFile.Should().Be(inc);                        // spliced insert 1
+        steps[2].SourceFile.Should().Be(inc);                        // spliced insert 2
+        ((SqlStep)steps[1]).Text.Should().Contain("values (1)");
+        steps[3].SourceFile.Should().BeNull();                       // the assertion (main file)
+    }
+
+    [Fact]
+    public void Nested_Includes_Resolve_Relative_To_The_Including_File()
+    {
+        Write("a/inner.sql", "select 'inner';");
+        Write("a/outer.sql", "\\ir inner.sql");
+        var main = Write("main.test.sql", "\\ir a/outer.sql");
+
+        var steps = TestFileLoader.LoadSteps(File.ReadAllText(main), main);
+
+        steps.Should().ContainSingle().Which.Should().BeOfType<SqlStep>()
+            .Which.Text.Should().Contain("inner");
+    }
+
+    [Fact]
+    public void Circular_Include_Is_Reported()
+    {
+        Write("x.sql", "\\ir y.sql");
+        Write("y.sql", "\\ir x.sql");
+        var main = Write("main.test.sql", "\\ir x.sql");
+
+        var act = () => TestFileLoader.LoadSteps(File.ReadAllText(main), main);
+        act.Should().Throw<InvalidOperationException>().WithMessage("*circular include*");
+    }
+
+    [Fact]
+    public void Missing_Include_Is_Reported_With_Path_And_Line()
+    {
+        var main = Write("main.test.sql", "select 1;\n\\ir nope.sql");
+        var act = () => TestFileLoader.LoadSteps(File.ReadAllText(main), main);
+        act.Should().Throw<InvalidOperationException>().WithMessage("*include not found*nope.sql*");
+    }
+
+    [Fact]
+    public void Http_Blocks_In_Included_Files_Are_Spliced_Like_Everything_Else()
+    {
+        var inc = Write("shared/login_call.sql", "/*\nPOST /api/login\n# @response shared_login\n\n{\"email\": \"x\"}\n*/");
+        var main = Write("main.test.sql", "begin;\n\\ir shared/login_call.sql\nselect true, 'ok';\nrollback;");
+
+        var steps = TestFileLoader.LoadSteps(File.ReadAllText(main), main);
+
+        steps.Should().HaveCount(4);
+        var http = steps[1].Should().BeOfType<HttpStep>().Subject;
+        http.SourceFile.Should().Be(inc);
+        http.Method.Should().Be("POST");
+        http.ResponseTable.Should().Be("shared_login");
+    }
+
+    [Fact]
+    public void Header_Annotations_In_Included_Files_Count_As_If_Pasted()
+    {
+        // A shared "profile": annotations only — the header continues in the host after it.
+        Write("shared/iso_profile.sql", "-- shared isolation profile\n-- @setup CreateIso\n-- @teardown DropIso\n-- @connection Isolated\n");
+        var main = Write("main.test.sql", "-- docs\n\\ir shared/iso_profile.sql\n-- @setup HostStep\nselect 1;");
+
+        var h = TestFileHeader.Parse(File.ReadAllText(main), main);
+
+        h.Setup.Should().Equal("CreateIso", "HostStep");
+        h.Teardown.Should().Equal("DropIso");
+        h.ConnectionName.Should().Be("Isolated");
+    }
+
+    [Fact]
+    public void An_Include_Containing_Statements_Ends_The_Header_Like_A_Paste_Would()
+    {
+        // The fixture's own leading annotation is in the pasted header region (counts); the host
+        // annotation AFTER the include is behind the fixture's first statement (does not count).
+        Write("fixture.sql", "-- @setup FromFixture\ninsert into t values (1);");
+        var main = Write("main.test.sql", "\\ir fixture.sql\n-- @setup TooLate\nselect 1;");
+
+        var h = TestFileHeader.Parse(File.ReadAllText(main), main);
+
+        h.Setup.Should().Equal("FromFixture");
+    }
+}
diff --git a/changelog/v3.19.0.md b/changelog/v3.19.0.md
index 36ec163c..fefdf6c5 100644
--- a/changelog/v3.19.0.md
+++ b/changelog/v3.19.0.md
@@ -123,16 +123,75 @@ select (select body::jsonb ->> 'email' from _response) = 'grace@example.com',
        'email is normalized to lowercase';
 ```
 
-### Setup and Teardown
+### Reusing scripts: `\i` and `\ir` includes
 
-Run-once steps around the whole test session. **`Setup` runs before endpoint discovery** (so it can create/migrate the very schema the endpoints are built from); **`Teardown` always runs** at the end — even when tests fail or Setup itself fails (best-effort; `Keep: true` skips it to let you inspect state). Steps execute in the **exact order written**; each entry is one of:
+Shared SQL — fixture inserts, utility scripts — can be spliced into any test with psql's include syntax on its own line:
+
+```sql
+begin;
+
+\ir fixtures/extra_users.sql    -- path relative to THIS file (psql \ir semantics)
+\i  ./shared/reset_counters.sql -- path relative to the cwd, like every other configured path
+
+/* GET /api/get-users */
+select (select jsonb_array_length(body::jsonb) from _response) = 5, 'seed + fixture users listed';
+
+rollback;
+```
+
+An include behaves **as if you pasted the file's content at that spot**: SQL statements, assertions (counted as tests, attributed to the included file), **HTTP blocks** (they participate in `_response_{n}` numbering exactly as if pasted), and even **header annotations** — `-- @setup`/`-- @teardown`/`-- @connection` in an included file's leading comments count when the include sits in the host file's header region. That last one enables a **shared profile** idiom: put an annotation set in one file and attach it with a single include line (see example 21's `shared/isolated_database.sql` — one `\ir` line gives a test its own cloned database). Everything runs **on the test's connection, inside the test's transaction** — a fixture included this way rolls back with the test, so it is invisible to every other test and leaves no residue.
+
+Two footnotes where "pasted" is refined rather than literal:
+
+- An include must stand **between complete statements** — it cannot sit inside an unfinished statement or contribute a *fragment* of one (for reusable SQL fragments, use what PostgreSQL already provides: functions and views).
+- Error attribution is **better than a paste**: a failure inside an included file is reported with the *included file's* name and line (the same thing psql does), not a line number in an imaginary merged file.
+
+Includes nest (cycle-safe, depth-capped) and work in `Setup`/`Teardown` `SqlFile` steps too. A path may be single-quoted (`\ir 'my fixtures/data.sql'`) and a trailing `;` is forgiven; a non-include backslash line is passed through to PostgreSQL untouched (no other psql meta-commands are supported).
+
+### Setup and Teardown, and named steps
+
+Run-once steps around the whole test session. **`Setup` runs before endpoint discovery** (so it can create/migrate the very schema the endpoints are built from); **`Teardown` always runs** at the end — even when tests fail or Setup itself fails (best-effort; `Keep: true` skips it to let you inspect state). Steps execute in the **exact order written**; a step is one of:
 
 - `{ "Sql": "..." }` — inline SQL,
-- `{ "SqlFile": "path" }` — a SQL file (executed statement by statement, like test files),
+- `{ "SqlFile": "path" }` — a SQL file (executed statement by statement, like test files; `\i`/`\ir` includes work),
 - `{ "Command": "...", "WorkingDirectory": "..." }` — a shell command (e.g. `docker compose up -d`, an external migration tool). Non-zero exit fails Setup.
 
 `Sql`/`SqlFile` steps run on the test connection by default, or on any named `ConnectionStrings` entry via a per-step `"ConnectionName"` — which enables maintenance operations like `create database` without the runner ever issuing DDL on its own.
 
+Steps can be defined once in the **`Steps` registry** (name → step, like `ConnectionStrings` or `CacheOptions.Profiles`) and referenced by name; `Setup`/`Teardown` arrays accept names and inline objects mixed. Referencing an unknown name is a configuration error (exit 3).
+
+```jsonc
+"Steps": {
+  "CreateDatabase":  { "Sql": "create database app_test_{rnd5}", "ConnectionName": "Admin" },
+  "ApplyMigrations": { "SqlFile": "./migrations/schema.sql" },
+  "DropDatabase":    { "Sql": "drop database if exists app_test_{rnd5} with (force)", "ConnectionName": "Admin" }
+},
+"Setup":    ["CreateDatabase", "ApplyMigrations"],
+"Teardown": ["DropDatabase"]
+```
+
+### Per-file setup, teardown, and connection (header annotations)
+
+An individual test file can attach named steps — and pick its own connection — with leading `--` comment annotations (the same annotation idiom endpoint `.sql` files use), placed before the first statement:
+
+```sql
+-- @setup CreateIsolatedDb
+-- @teardown DropIsolatedDb
+-- @connection Isolated
+```
+
+- `-- @setup Name [Name …]` — runs the named steps **before this file** (own connections, committed work — e.g. clone a database this file will use). An unknown step name fails the file with an error.
+- `-- @teardown Name [Name …]` — runs **after this file, always** (best-effort, even when the test fails or times out), after the file's connection is closed — so a `drop database … with (force)` teardown works. An unknown step name logs a warning.
+- `-- @connection Name` — runs this file, **including its in-process endpoint calls**, on a named `ConnectionStrings` entry instead of the test connection. An unknown name fails the file with an error.
+
+`@setup` and `@teardown` are **repeatable**, and one line may carry **several names, separated by whitespace or commas** (the NpgsqlRest annotation idiom — `-- @setup A B`, `-- @setup A, B`, and two `-- @setup` lines are all equivalent). Names accumulate and execute in **exactly the order written** — the same contract as the global `Setup`/`Teardown` arrays; teardown is *not* reversed, so write the step you want last, last. Setup is fail-fast (the first failing or unknown step stops the chain, the file body never runs, teardown still runs); each teardown step is best-effort (a failure logs a warning and the remaining steps still run).
+
+Annotations can also come from an **include in the header region** — includes behave as if pasted, so a shared annotation "profile" file attaches with one line: `\ir shared/isolated_database.sql` (see the includes section above).
+
+Since every word after `@setup`/`@teardown` is read as a step name, don't *describe* these annotations in a file's header comments using their literal syntax (`-- @setup CreateDb creates the db…` would try to run steps named `creates`, `the`, `db…`). Other `--` comment lines in the header are ignored as usual.
+
+Together these give **per-test database isolation**: a file's setup clones a migrated template (`create database … template …` — a near-instant file-level copy), `@connection` points the file at the clone, and teardown drops it. That is the escalation path for state that transaction rollback cannot isolate — most prominently **sequences**, which advance even when the transaction rolls back, so generated ids are only deterministic in a fresh clone. Per-file steps commit to shared state, so steps that mutate the *shared* test database should be idempotent or run under `MaxParallelism: 1`; in-transaction fixture reuse belongs to `\ir` instead.
+
 ### A dedicated test database
 
 `TestRunner.ConnectionName` points the whole test session — endpoint type-checking (SQL-file Describe), endpoint execution, and the tests — at a named `ConnectionStrings` entry instead of the app's main connection. That database **need not exist at startup**: it is never opened before Setup, so the first Setup step can create it.
@@ -146,19 +205,19 @@ Run-once steps around the whole test session. **`Setup` runs before endpoint dis
 "TestRunner": {
   "ConnectionName": "Test",
   "FilePattern": "./tests/**/*.test.sql",
-  "Setup": [
-    { "Sql": "create database app_test_{rnd6}", "ConnectionName": "Admin" },
-    { "SqlFile": "./migrations/schema.sql" }                         // runs on "Test"
-  ],
-  "Teardown": [
-    { "Sql": "drop database app_test_{rnd6} with (force)", "ConnectionName": "Admin" }
-  ]
+  "Steps": {
+    "CreateDatabase":  { "Sql": "create database app_test_{rnd6}", "ConnectionName": "Admin" },
+    "ApplyMigrations": { "SqlFile": "./migrations/schema.sql" },     // runs on "Test"
+    "DropDatabase":    { "Sql": "drop database if exists app_test_{rnd6} with (force)", "ConnectionName": "Admin" }
+  },
+  "Setup":    ["CreateDatabase", "ApplyMigrations"],
+  "Teardown": ["DropDatabase"]
 }
 ```
 
-**`{rnd1}`…`{rnd10}`** are random lowercase tokens (length = the digit), generated once per run and substituted everywhere `{ENV}` placeholders work — connection strings, Setup/Teardown SQL, and Commands. The same token yields the same value across the whole config, so the connection string, the `create`, and the `drop` all name the same database; concurrent suites on a shared server can't collide. (Trade-off: a hard crash that skips Teardown orphans that run's database. A static name with a leading `drop database if exists … with (force);` in Setup is the self-healing alternative.)
+**`{rnd1}`…`{rnd10}`** are random lowercase tokens (length = the digit), generated once per run and substituted everywhere `{ENV}` placeholders work — connection strings, Setup/Teardown SQL, and Commands. The same token yields the same value across the whole config, so the connection string, the `create`, and the `drop` all name the same database; concurrent suites on a shared server can't collide. When several **distinct** tokens of the same length are needed, the indexed instances **`{rndN_1}`…`{rndN_9}`** are each independent — `{rnd3}`, `{rnd3_1}` and `{rnd3_2}` are three different 3-character tokens, each stable for the run. (Trade-off: a hard crash that skips Teardown orphans that run's database. A static name with a leading `drop database if exists … with (force);` in Setup is the self-healing alternative.)
 
-The same Setup/Teardown machinery covers the neighboring workflows with no additional features: clone a prepared **template** (`create database … template app_template` — near-instant), start a **Docker** Postgres (`Command` steps: `docker run` → wait for `pg_isready` → migrate; `docker rm -f` in Teardown), or run an **external migrator** (EF Core, Django, Flyway) as a `Command`.
+The same Setup/Teardown machinery covers the neighboring workflows with no additional features: clone a prepared **template** (`create database … template app_template` — near-instant; migrate the template once in Setup and clone it for the run *and* for `-- @setup`-annotated per-test databases), start a **Docker** Postgres (`Command` steps: `docker run` → wait for `pg_isready` → migrate; `docker rm -f` in Teardown), or run an **external migrator** (EF Core, Django, Flyway) as a `Command`.
 
 ### Reporting
 
@@ -214,8 +273,9 @@ The runner logs through its own channel — **`NpgsqlRestTest`** (configurable v
       "Headers": "headers", "IsSuccess": "is_success"
     }
   },
-  "Setup": [],                          // run-once, BEFORE endpoint discovery, in written order
-  "Teardown": []                        // run-once, ALWAYS, in written order (Keep skips)
+  "Steps": {},                          // named, reusable steps (name → step) for Setup/Teardown and -- @setup/-- @teardown
+  "Setup": [],                          // run-once, BEFORE endpoint discovery, in written order (step names or inline objects)
+  "Teardown": []                        // run-once, ALWAYS, in written order (Keep skips; same entries as Setup)
 }
 ```
 
@@ -262,8 +322,8 @@ Each named logger is controlled independently — e.g. mute the application logg
 - The test runner's core hooks are additive and inert outside `--test`: an ambient-connection accessor on the endpoint pipeline (null by default) and response headers on the internal invocation result. Normal server operation is unchanged.
 - Test files run **statement by statement** (the client operates Npgsql with SQL rewriting disabled — one statement per command), which is also `psql`'s default execution model; explicit `begin`/`commit`/`rollback` in a file work as ordinary statements. `Setup`/`Teardown` `Sql`/`SqlFile` steps execute the same way — which is why `create database` works as a plain step.
 - All new options are wired through the client configuration: `appsettings.json`, the JSON-schema descriptions, and the `--config` template.
-- Working examples: [`examples/19_testing_basic`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/19_testing_basic) (co-located layout, multi-step scenario files) and [`examples/20_testing_newdb`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/20_testing_newdb) (separate `tests/` tree, one test per file, fresh test database per run, deferrable-constraint fixtures, authorization + user parameters).
+- Working examples: [`examples/19_testing_basic`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/19_testing_basic) (co-located layout, multi-step scenario files), [`examples/20_testing_newdb`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/20_testing_newdb) (separate `tests/` tree, one test per file, fresh test database per run via named steps, deferrable-constraint fixtures, authorization + user parameters), and [`examples/21_testing_isolation`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/21_testing_isolation) (template-clone workflow; two parallel per-test isolated databases — named apart with the indexed `{rnd5_1}`/`{rnd5_2}` tokens — proving deterministic sequence ids; a shared annotation profile attached via `\ir`; a `Command` step mixed with named-step references in Setup).
 
 ## Tests
 
-Full test suite green (2334), including 33 parser unit tests for the test-file and HTTP-block parsers (`NpgsqlRestTests/TestRunnerTests/ParserTests/`). Both documentation examples verified end-to-end against live PostgreSQL (19 assertions in 9 files for example 20, including create-database-per-run with a `{rnd}` name and teardown drop). The new configuration keys are covered by the configuration round-trip tests (the `--config` template output matches `appsettings.json`).
+Full test suite green (2351), including 50 parser unit tests for the test-file, HTTP-block, header-annotation, and include parsers (`NpgsqlRestTests/TestRunnerTests/ParserTests/`). All three documentation examples verified end-to-end against live PostgreSQL — including example 21's template-clone workflow (template migrated once; the shared run database and **two parallel per-test isolated databases** cloned from it concurrently; deterministic sequence ids asserted independently in both clones; everything dropped on teardown). The new configuration keys are covered by the configuration round-trip tests (the `--config` template output matches `appsettings.json`).

From bd4fed55a6019e69750645abd583591402516c38 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Thu, 2 Jul 2026 18:34:42 +0200
Subject: [PATCH 15/25] feat(test-runner): filtering, watch mode, tags,
 endpoint coverage (Phase 3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Test filtering (TestRunner.Filter):
- Narrow the discovered set: a value without wildcards is a case-insensitive
  substring match against the cwd-relative path (--testrunner:filter=login);
  with wildcards it uses the same glob engine as FilePattern. Setup/Teardown
  still run; zero matches exits 4 (AllowEmpty applies).

Watch mode (--watch / TestRunner.Watch, interactive/dev-only):
- Setup once, run once, then watch the FilePattern base directory recursively
  for *.sql changes (debounced): a changed test file re-runs alone (Filter
  applies); any other changed .sql (an included fixture/profile) re-runs
  everything. Endpoint sources are not watched — restart to rebuild.
- Teardown runs ONCE, on exit: SIGINT and SIGTERM are intercepted via
  PosixSignalRegistration (Console.CancelKeyPress proved unreliable headless;
  plain SIGTERM previously killed the process without teardown, leaking the
  test database). Graceful stop exits 0 — not for CI gating.
- Extracted ExecuteDiscoveredFilesAsync (run core without teardown); RunAsync
  keeps teardown-in-finally for CI mode.

Tags (-- @tag name [name ...] header annotation):
- TestRunner.Tag runs only files carrying at least one listed tag;
  TestRunner.ExcludeTag skips files carrying any (exclude wins). CSV or
  whitespace-separated, case-insensitive, composes with Filter. Tags travel
  through profile includes (as-if-pasted), so e.g. every clone-isolated test
  is automatically tagged slow by its profile.

Endpoint coverage (TestRunner.Coverage / CoverageThreshold):
- After the run: exercised N of M testable endpoints + the list of untested
  ones (kinds the runner rejects — SSE, upload, login/logout, outbound proxy —
  are excluded from the ratio and counted separately). CoverageThreshold
  (0-100, implies Coverage) fails an otherwise-passing run with exit 2 —
  CI gating for "every endpoint has a test". Covered = invoked at least once.

Config synced across appsettings.json, ConfigTemplate.cs, ConfigDefaults.cs,
ConfigSchemaGenerator.cs; --watch whitelisted; --help updated. Changelog
v3.19.0.md updated with all four features. Full suite green (2364) incl. 63
runner unit tests; examples 19/20/21 verified end-to-end (filter modes, watch
rerun-on-change + signal teardown, tag taxonomies incl. profile-carried tags,
coverage report + failing threshold gate).
---
 NpgsqlRestClient/Builder.cs                   |  12 +
 NpgsqlRestClient/Config.cs                    |   2 +-
 NpgsqlRestClient/ConfigDefaults.cs            |   6 +
 NpgsqlRestClient/ConfigSchemaGenerator.cs     |   4 +
 NpgsqlRestClient/ConfigTemplate.cs            |  30 ++
 NpgsqlRestClient/Program.cs                   |  14 +-
 NpgsqlRestClient/Testing/TestFileLoader.cs    |   7 +
 NpgsqlRestClient/Testing/TestRunner.cs        | 330 ++++++++++++++++--
 NpgsqlRestClient/Testing/TestRunnerOptions.cs |  38 ++
 NpgsqlRestClient/appsettings.json             |  30 ++
 .../TestFileHeaderAndIncludeTests.cs          |  40 +++
 changelog/v3.19.0.md                          |  50 ++-
 12 files changed, 531 insertions(+), 32 deletions(-)

diff --git a/NpgsqlRestClient/Builder.cs b/NpgsqlRestClient/Builder.cs
index f6be212f..74b4c395 100644
--- a/NpgsqlRestClient/Builder.cs
+++ b/NpgsqlRestClient/Builder.cs
@@ -3068,6 +3068,9 @@ public TestRunnerOptions BuildTestRunnerOptions()
         if (section.Exists() is false) return opt;
 
         opt.FilePattern = _config.GetConfigStr("FilePattern", section) ?? "";
+        opt.Filter = _config.GetConfigStr("Filter", section);
+        opt.Tags = SplitNames(_config.GetConfigStr("Tag", section));
+        opt.ExcludeTags = SplitNames(_config.GetConfigStr("ExcludeTag", section));
         opt.ConnectionName = _config.GetConfigStr("ConnectionName", section);
         opt.MaxParallelism = _config.GetConfigInt("MaxParallelism", section) ?? 0;
         opt.FailFast = _config.GetConfigBool("FailFast", section, false);
@@ -3076,6 +3079,9 @@ public TestRunnerOptions BuildTestRunnerOptions()
         opt.Keep = _config.GetConfigBool("Keep", section, false);
         opt.DetailedReport = _config.GetConfigBool("DetailedReport", section, false);
         opt.AllowEmpty = _config.GetConfigBool("AllowEmpty", section, false);
+        opt.Watch = _config.GetConfigBool("Watch", section, false);
+        opt.CoverageThreshold = _config.GetConfigInt("CoverageThreshold", section);
+        opt.Coverage = _config.GetConfigBool("Coverage", section, false) || opt.CoverageThreshold is not null;
 
         var rt = section.GetSection("ResponseTempTable");
         if (rt.Exists())
@@ -3110,6 +3116,12 @@ public TestRunnerOptions BuildTestRunnerOptions()
         opt.Teardown = ReadTestSteps(section.GetSection("Teardown"));
         return opt;
 
+        // "a, b" or "a b" → ["a","b"] (same separators as the header annotations).
+        static List<string> SplitNames(string? value) =>
+            string.IsNullOrWhiteSpace(value)
+                ? []
+                : [.. value.Split([',', ' ', '\t'], StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)];
+
         // Absent key => keep default name; explicit empty string => omit the column.
         string? ReadColumnName(IConfigurationSection cols, string key, string? def)
         {
diff --git a/NpgsqlRestClient/Config.cs b/NpgsqlRestClient/Config.cs
index ba1cf919..4efa46b5 100644
--- a/NpgsqlRestClient/Config.cs
+++ b/NpgsqlRestClient/Config.cs
@@ -1145,7 +1145,7 @@ private static void LoadEnvFile(string path)
                 {
                     commandLineArgs.Add(arg);
                 }
-                else if (lower is "--json" or "--validate" or "--endpoints" or "--test")
+                else if (lower is "--json" or "--validate" or "--endpoints" or "--test" or "--watch")
                 {
                     // Known flags handled by Program.cs, skip silently
                 }
diff --git a/NpgsqlRestClient/ConfigDefaults.cs b/NpgsqlRestClient/ConfigDefaults.cs
index f6e6a7f6..57439532 100644
--- a/NpgsqlRestClient/ConfigDefaults.cs
+++ b/NpgsqlRestClient/ConfigDefaults.cs
@@ -1101,6 +1101,9 @@ private static JsonObject GetTestRunnerDefaults()
         return new JsonObject
         {
             ["FilePattern"] = "",
+            ["Filter"] = "",
+            ["Tag"] = "",
+            ["ExcludeTag"] = "",
             ["ConnectionName"] = "",
             ["MaxParallelism"] = 0,
             ["FailFast"] = false,
@@ -1109,6 +1112,9 @@ private static JsonObject GetTestRunnerDefaults()
             ["Keep"] = false,
             ["DetailedReport"] = false,
             ["AllowEmpty"] = false,
+            ["Watch"] = false,
+            ["Coverage"] = false,
+            ["CoverageThreshold"] = null,
             ["LoggerName"] = "NpgsqlRestTest",
             ["ResponseTempTable"] = new JsonObject
             {
diff --git a/NpgsqlRestClient/ConfigSchemaGenerator.cs b/NpgsqlRestClient/ConfigSchemaGenerator.cs
index 01f0031f..895d01e5 100644
--- a/NpgsqlRestClient/ConfigSchemaGenerator.cs
+++ b/NpgsqlRestClient/ConfigSchemaGenerator.cs
@@ -248,6 +248,9 @@ public static partial class ConfigSchemaGenerator
         ["Stats:ActivityPath"] = "Path for current database activity.\nReturns data from pg_stat_activity showing active sessions, queries, and wait events.\nSecurity Consideration: Shows currently running queries which may contain sensitive data.",
         ["TestRunner"] = "SQL test runner. Invoked with the `--test` command-line flag (otherwise inert).\nDiscovers *.test.sql files, runs each in an isolated non-pooled connection, can invoke endpoints in-process from an embedded `/* GET /path */` block (response captured into a temp table), and asserts via boolean-returning SELECTs or `do $$ ... assert ... $$;` blocks.\nExit codes: 0 pass, 1 failures, 2 errors, 3 config/runner error, 4 no tests found.",
         ["TestRunner:FilePattern"] = "Glob (same engine as SqlFileSource) selecting *.test.sql files. Empty disables discovery.\nCo-located convention: app.sql (endpoint) next to app.test.sql (test).",
+        ["TestRunner:Filter"] = "Optional filter narrowing the discovered set — the fast path for iterating on one test: npgsqlrest ... --test --testrunner:filter=login\nMatched against each file's cwd-relative path: a value without wildcards is a substring match; with wildcards it is the same glob engine as FilePattern. Empty = run everything discovered.",
+        ["TestRunner:Tag"] = "Run only test files carrying at least one of these tags (comma- or whitespace-separated; case-insensitive). A file declares tags with a `-- @tag name [name ...]` header annotation. Composes with ExcludeTag and Filter.",
+        ["TestRunner:ExcludeTag"] = "Skip test files carrying any of these tags (comma- or whitespace-separated; case-insensitive; exclude wins over Tag).",
         ["TestRunner:ConnectionName"] = "Optional: a ConnectionStrings entry to run the tests against instead of the app's main connection.\nIn test mode it becomes the connection used for endpoint type-checking (Describe) and execution, so it can point at a dedicated test database that a Setup step creates first (it need not exist at startup). Empty = use the main connection.\nTip: {rnd1}..{rnd10} are random lowercase tokens (length = the digit), stable for the whole run, usable in any connection string or Setup/Teardown SQL (e.g. Database=app_test_{rnd6}). Need several distinct tokens of the same length? Indexed instances {rndN_1}..{rndN_9} are each independent.",
         ["TestRunner:MaxParallelism"] = "Max test files run concurrently. 0 => processor count. Each test uses its own non-pooled connection.",
         ["TestRunner:FailFast"] = "Stop scheduling new tests after the first failure/error (in-flight tests still finish).",
@@ -256,6 +259,7 @@ public static partial class ConfigSchemaGenerator
         ["TestRunner:Keep"] = "Skip Teardown so a failed run's state can be inspected.",
         ["TestRunner:DetailedReport"] = "Detailed console REPORT: list passed assertions, print the full failing SQL statement, and show captured `raise notice` output for passing tests too.\nThis shapes the report only — for diagnostic logging of every executed query/HTTP call, raise the log channel instead (Log:MinimalLevels + LoggerName).",
         ["TestRunner:AllowEmpty"] = "Treat \"no tests discovered\" as success (exit 0) instead of exit 4.",
+        ["TestRunner:Watch"] = "Watch mode (interactive/dev-only; CLI flag: --watch): run everything once, then re-run on file changes until Ctrl+C.\nA changed test file re-runs alone; any other changed .sql under the watched tree (e.g. an included fixture) re-runs everything. Endpoint sources are not watched — restart to rebuild endpoints. Teardown runs once, on exit; a graceful stop exits 0 (not for CI gating).",
         ["TestRunner:LoggerName"] = "SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels (defaults to Information).\nDiscovery/parsing log at Debug, each query and HTTP invocation at Verbose, `raise notice` by severity. The console PASS/FAIL report is separate.",
         ["TestRunner:ResponseTempTable:Name"] = "Temp table name used when a test file has exactly ONE HTTP block.\nEach HTTP block gets its own fresh temp table (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified. Per-block override: `# @response <name>`.",
         ["TestRunner:ResponseTempTable:MultiNamePattern"] = "Temp table name pattern used when a test file has 2+ HTTP blocks.\n{n} is the 1-based block ordinal, e.g. \"_response_{n}\" => _response_1, _response_2, …",
diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index f0fe916f..7382ddcc 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -1448,6 +1448,21 @@ public static partial class ConfigSchemaGenerator
         //
         "FilePattern": "",
         //
+        // Optional filter narrowing the discovered set — the fast path for iterating on one test:
+        //   npgsqlrest ... --test --testrunner:filter=login
+        // Matched against each file's cwd-relative path: a value without wildcards is a substring match;
+        // with wildcards it is the same glob engine as FilePattern. Empty = run everything discovered.
+        //
+        "Filter": "",
+        //
+        // Tag filtering (comma- or whitespace-separated lists; case-insensitive). A test file declares tags
+        // with a `-- @tag name [name ...]` header annotation. "Tag" runs only files carrying at least one of
+        // the listed tags; "ExcludeTag" skips files carrying any of them (exclude wins). Composes with Filter.
+        //   npgsqlrest ... --test --testrunner:tag=smoke --testrunner:excludetag=slow
+        //
+        "Tag": "",
+        "ExcludeTag": "",
+        //
         // Optional: a ConnectionStrings entry to run the tests against instead of the app's main connection. In
         // test mode it becomes the connection used for endpoint type-checking (Describe) and execution, so it can
         // point at a dedicated test database that a Setup step creates first (it need not exist at startup).
@@ -1487,6 +1502,21 @@ public static partial class ConfigSchemaGenerator
         //
         "AllowEmpty": false,
         //
+        // Watch mode (interactive/dev-only; CLI flag: --watch): run everything once, then re-run on file
+        // changes until Ctrl+C. A changed test file re-runs alone; any other changed .sql under the watched
+        // tree (e.g. an included fixture) re-runs everything. Endpoint sources are not watched — restart to
+        // rebuild endpoints. Teardown runs once, on exit; a graceful stop exits 0 (not for CI gating).
+        //
+        "Watch": false,
+        //
+        // Endpoint-coverage summary after the run: exercised N of M testable endpoints + the list of untested
+        // ones (endpoint kinds the runner rejects — SSE, upload, login/logout, outbound proxy — are excluded
+        // from the ratio and counted separately). CoverageThreshold (0-100, implies Coverage) fails an
+        // otherwise-passing run with exit 2 when coverage is below it — CI gating for "every endpoint has a test".
+        //
+        "Coverage": false,
+        "CoverageThreshold": null,
+        //
         // SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels.
         // Discovery/parsing log at Debug, each query and HTTP invocation at Verbose, `raise notice` by severity.
         //
diff --git a/NpgsqlRestClient/Program.cs b/NpgsqlRestClient/Program.cs
index 090a2e22..c17764f9 100644
--- a/NpgsqlRestClient/Program.cs
+++ b/NpgsqlRestClient/Program.cs
@@ -39,6 +39,7 @@
         ("npgsqlrest --annotations", "Output all supported comment annotations as JSON. Syntax highlighted in terminal, plain JSON when piped."),
         ("npgsqlrest [files...] --endpoints", "Connect to database, discover endpoints, output as JSON, then exit. Syntax highlighted in terminal, plain JSON when piped."),
         ("npgsqlrest [files...] --test", "Run SQL test files (TestRunner config), then exit. Exit codes: 0 pass, 1 failures, 2 errors, 3 config error, 4 no tests."),
+        ("npgsqlrest [files...] --test --watch", "Watch mode: run the tests, then re-run on file changes until Ctrl+C (interactive/dev-only; teardown runs on exit)."),
         (" ", " "),
         ("npgsqlrest --hash [value]", "Hash value with default hasher and print to console."),
         ("npgsqlrest --basic_auth [username] [password]", "Print out basic basic auth header value in format 'Authorization: Basic base64(username:password)'."),
@@ -487,6 +488,7 @@
 // SQL test runner: run Setup (Commands then SqlFile/Sql) BEFORE discovery so migrations can build the
 // schema that UseNpgsqlRest then discovers. The runner sets options.AmbientConnectionAccessor in its ctor.
 NpgsqlRestClient.Testing.TestRunner? testRunner = null;
+NpgsqlRestClient.Testing.TestRunnerOptions? testRunnerOptions = null;
 if (testMode)
 {
     // Test-mode invariants: the endpoint must never begin/commit on the test's connection, and caching
@@ -502,7 +504,8 @@
 
     try
     {
-        testRunner = new NpgsqlRestClient.Testing.TestRunner(options, builder.BuildTestRunnerOptions(), connectionString, builder.TestLogger, logTestNotices, builder.BuildTestRunnerConnectionStrings());
+        testRunnerOptions = builder.BuildTestRunnerOptions();
+        testRunner = new NpgsqlRestClient.Testing.TestRunner(options, testRunnerOptions, connectionString, builder.TestLogger, logTestNotices, builder.BuildTestRunnerConnectionStrings());
     }
     catch (Exception ex)
     {
@@ -534,8 +537,13 @@
 
 if (testMode)
 {
-    // Endpoints are now built; run the test files (then Teardown), and exit.
-    Environment.ExitCode = await testRunner!.RunAsync(EndpointCapture.Endpoints);
+    // Endpoints are now built; run the test files (then Teardown), and exit. `--watch` (or
+    // TestRunner:Watch) keeps the process alive and re-runs on file changes until Ctrl+C.
+    bool watchMode = args.Any(a => string.Equals(a, "--watch", StringComparison.OrdinalIgnoreCase))
+        || testRunnerOptions!.Watch;
+    Environment.ExitCode = watchMode
+        ? await testRunner!.RunWatchAsync(EndpointCapture.Endpoints)
+        : await testRunner!.RunAsync(EndpointCapture.Endpoints);
     return;
 }
 
diff --git a/NpgsqlRestClient/Testing/TestFileLoader.cs b/NpgsqlRestClient/Testing/TestFileLoader.cs
index 310bc45f..bb2e0b54 100644
--- a/NpgsqlRestClient/Testing/TestFileLoader.cs
+++ b/NpgsqlRestClient/Testing/TestFileLoader.cs
@@ -7,6 +7,7 @@ namespace NpgsqlRestClient.Testing;
 /// -- @setup StepName [StepName ...]      (run before this file; names from TestRunner:Steps)
 /// -- @teardown StepName [StepName ...]   (run after this file, always, best-effort)
 /// -- @connection Name                    (run this file on a named ConnectionStrings entry)
+/// -- @tag Name [Name ...]                (file tags; filtered with TestRunner Tag/ExcludeTag)
 /// </code>
 /// Annotations are repeatable and names accumulate in written order; multiple names on one line may be
 /// separated by whitespace or commas (`@setup A B` == `@setup A, B` — the NpgsqlRest annotation idiom).
@@ -19,6 +20,8 @@ public sealed class TestFileHeader
 {
     public List<string> Setup { get; } = [];
     public List<string> Teardown { get; } = [];
+    /// <summary>File tags from <c>-- @tag name [name ...]</c> — filtered with TestRunner Tag/ExcludeTag.</summary>
+    public List<string> Tags { get; } = [];
     public string? ConnectionName { get; private set; }
 
     public static TestFileHeader Parse(string content, string? sourceFile = null)
@@ -63,6 +66,10 @@ private static bool Scan(string content, string? sourceFile, TestFileHeader head
                 {
                     header.ConnectionName = tokens[1];
                 }
+                else if (string.Equals(tokens[0], "tag", StringComparison.OrdinalIgnoreCase))
+                {
+                    header.Tags.AddRange(tokens[1..]);
+                }
                 // any other @word is an ordinary comment — ignored
                 continue;
             }
diff --git a/NpgsqlRestClient/Testing/TestRunner.cs b/NpgsqlRestClient/Testing/TestRunner.cs
index 4f27bcc0..953f5a8e 100644
--- a/NpgsqlRestClient/Testing/TestRunner.cs
+++ b/NpgsqlRestClient/Testing/TestRunner.cs
@@ -38,6 +38,8 @@ public sealed class TestRunner
     private readonly bool _logNotices;
     private readonly Out _out = new();
     private volatile bool _failFast;
+    // Endpoints actually invoked during the run (canonical "METHOD path" keys) — the coverage numerator.
+    private readonly ConcurrentDictionary<string, byte> _invoked = new(StringComparer.OrdinalIgnoreCase);
 
     private enum Outcome { Pass, Fail, Error }
 
@@ -154,49 +156,305 @@ public async Task<int> RunAsync(RoutineEndpoint[] endpoints, CancellationToken c
     {
         try
         {
-            var files = DiscoverFiles();
+            return await ExecuteDiscoveredFilesAsync(endpoints, BuildEndpointLookup(endpoints), only: null, ct);
+        }
+        finally
+        {
+            await TeardownAsync(ct);
+        }
+    }
+
+    // Discovers (or takes `only`), filters, runs, reports; returns the exit code. NO teardown — the caller
+    // owns that (RunAsync tears down in finally; watch mode tears down once, on exit).
+    private async Task<int> ExecuteDiscoveredFilesAsync(RoutineEndpoint[] endpoints, IReadOnlyDictionary<string, RoutineEndpoint> lookup, List<string>? only, CancellationToken ct)
+    {
+        _failFast = false; // reset per run (watch mode reuses the runner across iterations)
+        if (only is null) _invoked.Clear(); // coverage counts per full run (partial watch reruns don't report)
+
+        var files = only ?? DiscoverFiles();
+        if (only is null)
+        {
             _log?.LogDebug("discovered {Count} test file(s) matching {Pattern}", files.Count, _opt.FilePattern);
+        }
+        if (!string.IsNullOrWhiteSpace(_opt.Filter))
+        {
+            int discovered = files.Count;
+            files = files.Where(f => MatchesFilter(Path.GetRelativePath(Environment.CurrentDirectory, f), _opt.Filter!)).ToList();
+            _log?.LogDebug("filter {Filter} matched {Count} of {Discovered} discovered file(s)", _opt.Filter, files.Count, discovered);
             if (files.Count == 0)
             {
-                _out.Line("Test runner: no test files matched FilePattern.", ConsoleColor.Yellow);
+                _out.Line($"Test runner: filter '{_opt.Filter}' matched none of the {discovered} discovered test file(s).", ConsoleColor.Yellow);
                 return _opt.AllowEmpty ? ExitPass : ExitNoTests;
             }
+        }
+        if (_opt.Tags.Count > 0 || _opt.ExcludeTags.Count > 0)
+        {
+            int before = files.Count;
+            var include = new HashSet<string>(_opt.Tags, StringComparer.OrdinalIgnoreCase);
+            var exclude = new HashSet<string>(_opt.ExcludeTags, StringComparer.OrdinalIgnoreCase);
+            var selected = new List<string>(files.Count);
+            foreach (var f in files)
+            {
+                List<string> tags;
+                try
+                {
+                    tags = TestFileHeader.Parse(await File.ReadAllTextAsync(f, ct), f).Tags;
+                }
+                catch
+                {
+                    // Unreadable header (e.g. a broken include) — keep the file so the run surfaces the error.
+                    selected.Add(f);
+                    continue;
+                }
+                if (MatchesTags(tags, include, exclude)) selected.Add(f);
+            }
+            files = selected;
+            _log?.LogDebug("tag filter (tag: {Tags}; exclude: {Exclude}) matched {Count} of {Before} file(s)",
+                string.Join(',', _opt.Tags), string.Join(',', _opt.ExcludeTags), files.Count, before);
+            if (files.Count == 0)
+            {
+                _out.Line($"Test runner: tag filter matched none of the {before} test file(s).", ConsoleColor.Yellow);
+                return _opt.AllowEmpty ? ExitPass : ExitNoTests;
+            }
+        }
+        if (files.Count == 0)
+        {
+            _out.Line("Test runner: no test files matched FilePattern.", ConsoleColor.Yellow);
+            return _opt.AllowEmpty ? ExitPass : ExitNoTests;
+        }
 
-            var lookup = BuildEndpointLookup(endpoints);
-            var results = new ConcurrentBag<FileResult>();
-            int dop = _opt.MaxParallelism > 0 ? _opt.MaxParallelism : Environment.ProcessorCount;
+        var results = new ConcurrentBag<FileResult>();
+        int dop = _opt.MaxParallelism > 0 ? _opt.MaxParallelism : Environment.ProcessorCount;
 
-            // Console header stays a clean human report (just the file count, like other test runners). The
-            // parallelism is a diagnostic → log channel at Debug, not the always-on console line.
-            _out.Line($"NpgsqlRest test runner — {files.Count} file(s)", ConsoleColor.Cyan);
-            _log?.LogDebug("running {Count} test file(s) at degree of parallelism {Parallelism}", files.Count, dop);
+        // Console header stays a clean human report (just the file count, like other test runners). The
+        // parallelism is a diagnostic → log channel at Debug, not the always-on console line.
+        _out.Line($"NpgsqlRest test runner — {files.Count} file(s)", ConsoleColor.Cyan);
+        _log?.LogDebug("running {Count} test file(s) at degree of parallelism {Parallelism}", files.Count, dop);
 
-            await Parallel.ForEachAsync(
-                files,
-                new ParallelOptions { MaxDegreeOfParallelism = dop, CancellationToken = ct },
-                async (file, _) =>
-                {
-                    if (_failFast) return; // stop scheduling new work after the first failure (in-flight finish)
-                    var r = await RunFileAsync(file, lookup, ct);
-                    results.Add(r);
-                    if (_opt.FailFast && r.Outcome != Outcome.Pass) _failFast = true;
-                });
+        await Parallel.ForEachAsync(
+            files,
+            new ParallelOptions { MaxDegreeOfParallelism = dop, CancellationToken = ct },
+            async (file, _) =>
+            {
+                if (_failFast) return; // stop scheduling new work after the first failure (in-flight finish)
+                var r = await RunFileAsync(file, lookup, ct);
+                results.Add(r);
+                if (_opt.FailFast && r.Outcome != Outcome.Pass) _failFast = true;
+            });
+
+        var ordered = results.OrderBy(r => r.File, StringComparer.Ordinal).ToList();
+        ReportConsole(ordered);
+        if (!string.IsNullOrWhiteSpace(_opt.JUnitOutput))
+        {
+            WriteJUnit(ordered, _opt.JUnitOutput!);
+        }
+
+        int exit = ordered.Any(r => r.Outcome == Outcome.Error) ? ExitErrors
+            : ordered.Any(r => r.Outcome == Outcome.Fail) ? ExitFailures
+            : ExitPass;
+        if (_opt.Coverage && only is null)
+        {
+            exit = ReportCoverage(endpoints, exit);
+        }
+        return exit;
+    }
 
-            var ordered = results.OrderBy(r => r.File, StringComparer.Ordinal).ToList();
-            ReportConsole(ordered);
-            if (!string.IsNullOrWhiteSpace(_opt.JUnitOutput))
+    // Endpoint-coverage summary: exercised N of M TESTABLE endpoints + the untested list. Kinds the runner
+    // rejects (SSE, upload, login/logout, outbound proxy) are excluded from the ratio and counted apart.
+    // When CoverageThreshold is set and coverage falls below it, an otherwise-passing run fails with exit 2.
+    private int ReportCoverage(RoutineEndpoint[] endpoints, int exit)
+    {
+        var testable = new List<RoutineEndpoint>(endpoints.Length);
+        int untestable = 0;
+        foreach (var ep in endpoints)
+        {
+            bool outboundProxy = ep.IsProxy && (ep.ProxyHost ?? _rest.ProxyOptions?.Host) is { } host && !host.StartsWith('/');
+            if (ep.SseEventsPath is not null || ep.SsePublishEnabled || ep.Upload || ep.Login || ep.Logout || outboundProxy)
             {
-                WriteJUnit(ordered, _opt.JUnitOutput!);
+                untestable++;
+                continue;
             }
+            testable.Add(ep);
+        }
+
+        var untested = testable.Where(ep => !_invoked.ContainsKey($"{ep.Method} {ep.Path}")).ToList();
+        int covered = testable.Count - untested.Count;
+        int pct = testable.Count == 0 ? 100 : covered * 100 / testable.Count;
+        bool gateFailed = _opt.CoverageThreshold is int threshold && pct < threshold;
+
+        var line = $"\nendpoint coverage: {covered}/{testable.Count} ({pct}%)"
+            + (untestable > 0 ? $"  —  {untestable} endpoint(s) excluded (not testable in test mode)" : "");
+        if (gateFailed) _out.LineAnsi(line, AnsiFail);
+        else _out.Line(line, untested.Count == 0 ? ConsoleColor.Green : ConsoleColor.Yellow);
 
-            if (ordered.Any(r => r.Outcome == Outcome.Error)) return ExitErrors;
-            if (ordered.Any(r => r.Outcome == Outcome.Fail)) return ExitFailures;
+        foreach (var ep in untested)
+        {
+            _out.Line($"        untested: {ep.Method} {ep.Path}", ConsoleColor.Yellow);
+        }
+        _log?.LogDebug("endpoint coverage {Covered}/{Testable} ({Pct}%), {Untestable} excluded", covered, testable.Count, pct, untestable);
+
+        if (gateFailed)
+        {
+            _out.LineAnsi($"        coverage {pct}% is below the CoverageThreshold ({_opt.CoverageThreshold}%)", AnsiFail);
+            if (exit == ExitPass) exit = ExitErrors;
+        }
+        return exit;
+    }
+
+    /// <summary>
+    /// Tag filter: with include tags set, the file must carry at least one of them; a file carrying any
+    /// exclude tag is skipped (exclude wins). Sets must be case-insensitive (built once per run, so each
+    /// file is a single pass with O(1) membership checks).
+    /// </summary>
+    public static bool MatchesTags(IReadOnlyList<string> fileTags, IReadOnlySet<string> include, IReadOnlySet<string> exclude)
+    {
+        bool included = include.Count == 0;
+        foreach (var tag in fileTags)
+        {
+            if (exclude.Count > 0 && exclude.Contains(tag))
+            {
+                return false;
+            }
+            if (!included && include.Contains(tag))
+            {
+                included = true;
+            }
+        }
+        return included;
+    }
+
+    /// <summary>
+    /// Watch mode (interactive/dev-only): runs everything once, then re-runs on file changes until
+    /// Ctrl+C. A changed TEST file re-runs just that file; any other changed .sql under the watched tree
+    /// (e.g. a \ir fixture — its dependents are unknown) re-runs everything. Endpoint sources are NOT
+    /// watched (endpoints are built once at startup — restart to rebuild). Teardown runs once, on exit;
+    /// the exit code is always 0 on a graceful stop (watch is not for CI gating).
+    /// </summary>
+    public async Task<int> RunWatchAsync(RoutineEndpoint[] endpoints, CancellationToken ct = default)
+    {
+        var lookup = BuildEndpointLookup(endpoints);
+        using var stop = CancellationTokenSource.CreateLinkedTokenSource(ct);
+        // PosixSignalRegistration (not Console.CancelKeyPress, which is unreliable without a TTY):
+        // intercept both Ctrl+C (SIGINT) and e.g. `docker stop` (SIGTERM), cancel the default kill so the
+        // loop can end gracefully and Teardown can run.
+        void OnSignal(System.Runtime.InteropServices.PosixSignalContext ctx)
+        {
+            ctx.Cancel = true;
+            stop.Cancel();
+        }
+        using var sigInt = System.Runtime.InteropServices.PosixSignalRegistration.Create(
+            System.Runtime.InteropServices.PosixSignal.SIGINT, OnSignal);
+        using var sigTerm = System.Runtime.InteropServices.PosixSignalRegistration.Create(
+            System.Runtime.InteropServices.PosixSignal.SIGTERM, OnSignal);
+
+        try
+        {
+            await ExecuteDiscoveredFilesAsync(endpoints, lookup, only: null, stop.Token);
+
+            var baseDir = GetWatchBaseDir(_opt.FilePattern);
+            if (baseDir is null)
+            {
+                _out.Line("Test runner: cannot watch — FilePattern has no existing base directory.", ConsoleColor.Yellow);
+                return ExitConfig;
+            }
+
+            var changes = System.Threading.Channels.Channel.CreateUnbounded<string>();
+            using var watcher = new FileSystemWatcher(Path.GetFullPath(baseDir), "*.sql")
+            {
+                IncludeSubdirectories = true,
+                NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.FileName | NotifyFilters.Size,
+            };
+            void OnFsEvent(object s, FileSystemEventArgs e) => changes.Writer.TryWrite(e.FullPath);
+            watcher.Changed += OnFsEvent;
+            watcher.Created += OnFsEvent;
+            watcher.Renamed += (s, e) => changes.Writer.TryWrite(e.FullPath);
+            watcher.EnableRaisingEvents = true;
+
+            _out.Line($"\nwatching {Path.GetRelativePath(Environment.CurrentDirectory, baseDir)} for changes — Ctrl+C to stop", ConsoleColor.Cyan);
+
+            while (!stop.IsCancellationRequested)
+            {
+                var changed = await NextChangeBatchAsync(changes.Reader, stop.Token);
+                if (changed is null) break; // cancelled
+
+                // Debounced batch: changed test files rerun individually; any other .sql (fixture/profile
+                // include) forces a full rerun since its dependents are unknown.
+                var testFiles = new List<string>();
+                bool runAll = false;
+                foreach (var path in changed)
+                {
+                    // Watcher paths are absolute; FilePattern is cwd-relative — compare in relative form.
+                    var rel = Path.GetRelativePath(Environment.CurrentDirectory, path).Replace('\\', '/');
+                    var pattern = _opt.FilePattern.Replace('\\', '/');
+                    if (pattern.StartsWith("./")) pattern = pattern[2..];
+                    if (Parser.IsPatternMatch(rel, pattern))
+                    {
+                        if (File.Exists(path)) testFiles.Add(Path.GetFullPath(path));
+                    }
+                    else
+                    {
+                        runAll = true;
+                    }
+                }
+                if (!runAll && testFiles.Count == 0) continue; // e.g. only deletions of test files
+
+                var trigger = Path.GetRelativePath(Environment.CurrentDirectory, changed[0]);
+                _out.Line($"\n— {DateTime.Now:HH:mm:ss} change detected ({trigger}{(changed.Count > 1 ? $" +{changed.Count - 1}" : "")}) —", ConsoleColor.Cyan);
+                await ExecuteDiscoveredFilesAsync(endpoints, lookup, only: runAll ? null : testFiles.Distinct().ToList(), stop.Token);
+                _out.Line($"\nwatching — Ctrl+C to stop", ConsoleColor.Cyan);
+            }
+            return ExitPass;
+        }
+        catch (OperationCanceledException)
+        {
             return ExitPass;
         }
         finally
         {
-            await TeardownAsync(ct);
+            // Teardown must survive the SIGINT/SIGTERM that ended the loop → uncancellable token.
+            await TeardownAsync(CancellationToken.None);
+        }
+    }
+
+    // First change (blocking), then a quiet period so editor write bursts coalesce into one rerun.
+    private static async Task<List<string>?> NextChangeBatchAsync(System.Threading.Channels.ChannelReader<string> reader, CancellationToken ct)
+    {
+        string first;
+        try
+        {
+            first = await reader.ReadAsync(ct);
+        }
+        catch (OperationCanceledException)
+        {
+            return null;
+        }
+        var batch = new List<string> { first };
+        while (true)
+        {
+            try { await Task.Delay(300, ct); } catch (OperationCanceledException) { return null; }
+            bool any = false;
+            while (reader.TryRead(out var more))
+            {
+                batch.Add(more);
+                any = true;
+            }
+            if (!any) return batch;
+        }
+    }
+
+    // The deepest fixed (wildcard-free) directory of the FilePattern — same logic DiscoverFiles uses.
+    private static string? GetWatchBaseDir(string pattern)
+    {
+        if (string.IsNullOrWhiteSpace(pattern)) return null;
+        int firstWildcard = pattern.IndexOfAny(['*', '?']);
+        if (firstWildcard < 0)
+        {
+            var dir = Path.GetDirectoryName(pattern);
+            return string.IsNullOrEmpty(dir) ? "." : dir;
         }
+        int lastSlash = pattern.LastIndexOf('/', firstWildcard);
+        var baseDir = lastSlash >= 0 ? pattern[..lastSlash] : ".";
+        return Directory.Exists(baseDir) ? baseDir : null;
     }
 
     private async Task<FileResult> RunFileAsync(string file, IReadOnlyDictionary<string, RoutineEndpoint> lookup, CancellationToken runCt)
@@ -490,6 +748,10 @@ private async Task<StepResult> InvokeHttpStepAsync(
         Ambient.Value = conn; // ensure this file's connection is used by the endpoint pipeline
         _log?.LogTrace("http {Method} {Path} (line {Line})", step.Method, step.Path, step.LineNumber);
         var response = await RoutineInvoker.InvokeAsync(step.Method, step.Path, headers, step.Body, contentType, user, ct);
+        if (ep is not null)
+        {
+            _invoked[$"{ep.Method} {ep.Path}"] = 1; // endpoint-coverage numerator (canonical key)
+        }
         _log?.LogTrace("http {Method} {Path} → {Status}, captured into temp table \"{Table}\"",
             step.Method, step.Path, response.StatusCode, responseTable);
 
@@ -818,6 +1080,22 @@ private static void WriteJUnit(List<FileResult> results, string path)
         new XDocument(new XDeclaration("1.0", "utf-8", null), suite).Save(path);
     }
 
+    /// <summary>
+    /// Filter match for <c>TestRunner.Filter</c> against a cwd-relative file path: a value without
+    /// wildcards is a case-insensitive substring match (`login` == `*login*`); with wildcards it uses
+    /// the same glob engine as FilePattern. Path separators are normalized to '/'.
+    /// </summary>
+    public static bool MatchesFilter(string relativePath, string filter)
+    {
+        var path = relativePath.Replace('\\', '/');
+        filter = filter.Trim().Replace('\\', '/');
+        if (filter.IndexOfAny(['*', '?']) < 0)
+        {
+            return path.Contains(filter, StringComparison.OrdinalIgnoreCase);
+        }
+        return Parser.IsPatternMatch(path, filter);
+    }
+
     private static string StripQuery(string path)
     {
         int q = path.IndexOf('?');
diff --git a/NpgsqlRestClient/Testing/TestRunnerOptions.cs b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
index d61133e9..935b527f 100644
--- a/NpgsqlRestClient/Testing/TestRunnerOptions.cs
+++ b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
@@ -6,6 +6,36 @@ public class TestRunnerOptions
     /// <summary>Glob (same engine as SqlFileSource) selecting *.test.sql files. Empty disables the runner.</summary>
     public string FilePattern { get; set; } = "";
 
+    /// <summary>
+    /// Optional filter narrowing the discovered set — the fast path for iterating on one test:
+    /// <c>npgsqlrest ... --test --testrunner:filter=login</c>. Matched against each file's cwd-relative
+    /// path: a value without wildcards is a substring match; with wildcards it is the same glob engine
+    /// as <see cref="FilePattern"/>. Empty = run everything discovered.
+    /// </summary>
+    public string? Filter { get; set; } = null;
+
+    /// <summary>
+    /// Run only files carrying at least one of these tags (from a <c>-- @tag name [name ...]</c> header
+    /// annotation). Empty = no tag requirement. Composes with <see cref="ExcludeTags"/> and <see cref="Filter"/>.
+    /// </summary>
+    public List<string> Tags { get; set; } = [];
+
+    /// <summary>Skip files carrying any of these tags (e.g. exclude "slow" locally). Empty = skip nothing.</summary>
+    public List<string> ExcludeTags { get; set; } = [];
+
+    /// <summary>
+    /// Emit an endpoint-coverage summary after the run: exercised N of M testable endpoints plus the list
+    /// of untested ones. Endpoint kinds the runner rejects (SSE, upload, login/logout, outbound proxy) are
+    /// excluded from the ratio and reported separately.
+    /// </summary>
+    public bool Coverage { get; set; } = false;
+
+    /// <summary>
+    /// Fail an otherwise-passing run (exit 2) when endpoint coverage is below this percentage (0-100), for
+    /// CI gating. Setting it implies <see cref="Coverage"/>. Null = no gate.
+    /// </summary>
+    public int? CoverageThreshold { get; set; } = null;
+
     /// <summary>
     /// Name of a <c>ConnectionStrings</c> entry to run the tests against, instead of the app's main connection.
     /// In test mode it becomes the connection used for endpoint type-checking (Describe) and execution, so it
@@ -41,6 +71,14 @@ public class TestRunnerOptions
     /// <summary>Zero tests discovered => exit 0 instead of 4.</summary>
     public bool AllowEmpty { get; set; } = false;
 
+    /// <summary>
+    /// Watch mode (interactive/dev-only; CLI: <c>--watch</c>): run everything once, then re-run on file
+    /// changes until Ctrl+C. A changed test file re-runs alone; any other changed .sql under the watched
+    /// tree re-runs everything (an included fixture's dependents are unknown). Endpoint sources are not
+    /// watched — restart to rebuild endpoints. Teardown runs once, on exit; graceful exit code is 0.
+    /// </summary>
+    public bool Watch { get; set; } = false;
+
     /// <summary>
     /// SourceContext name for the runner's own log channel — discovery/parsing at Debug, each query and HTTP
     /// invocation at Verbose, captured `raise notice` by its severity. Set its level independently via
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index e6e83f68..1b00ba09 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -1439,6 +1439,21 @@
     //
     "FilePattern": "",
     //
+    // Optional filter narrowing the discovered set — the fast path for iterating on one test:
+    //   npgsqlrest ... --test --testrunner:filter=login
+    // Matched against each file's cwd-relative path: a value without wildcards is a substring match;
+    // with wildcards it is the same glob engine as FilePattern. Empty = run everything discovered.
+    //
+    "Filter": "",
+    //
+    // Tag filtering (comma- or whitespace-separated lists; case-insensitive). A test file declares tags
+    // with a `-- @tag name [name ...]` header annotation. "Tag" runs only files carrying at least one of
+    // the listed tags; "ExcludeTag" skips files carrying any of them (exclude wins). Composes with Filter.
+    //   npgsqlrest ... --test --testrunner:tag=smoke --testrunner:excludetag=slow
+    //
+    "Tag": "",
+    "ExcludeTag": "",
+    //
     // Optional: a ConnectionStrings entry to run the tests against instead of the app's main connection. In
     // test mode it becomes the connection used for endpoint type-checking (Describe) and execution, so it can
     // point at a dedicated test database that a Setup step creates first (it need not exist at startup).
@@ -1478,6 +1493,21 @@
     //
     "AllowEmpty": false,
     //
+    // Watch mode (interactive/dev-only; CLI flag: --watch): run everything once, then re-run on file
+    // changes until Ctrl+C. A changed test file re-runs alone; any other changed .sql under the watched
+    // tree (e.g. an included fixture) re-runs everything. Endpoint sources are not watched — restart to
+    // rebuild endpoints. Teardown runs once, on exit; a graceful stop exits 0 (not for CI gating).
+    //
+    "Watch": false,
+    //
+    // Endpoint-coverage summary after the run: exercised N of M testable endpoints + the list of untested
+    // ones (endpoint kinds the runner rejects — SSE, upload, login/logout, outbound proxy — are excluded
+    // from the ratio and counted separately). CoverageThreshold (0-100, implies Coverage) fails an
+    // otherwise-passing run with exit 2 when coverage is below it — CI gating for "every endpoint has a test".
+    //
+    "Coverage": false,
+    "CoverageThreshold": null,
+    //
     // SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels.
     // Discovery/parsing log at Debug, each query and HTTP invocation at Verbose, `raise notice` by severity.
     //
diff --git a/NpgsqlRestTests/TestRunnerTests/ParserTests/TestFileHeaderAndIncludeTests.cs b/NpgsqlRestTests/TestRunnerTests/ParserTests/TestFileHeaderAndIncludeTests.cs
index 9be06a46..3b1f6623 100644
--- a/NpgsqlRestTests/TestRunnerTests/ParserTests/TestFileHeaderAndIncludeTests.cs
+++ b/NpgsqlRestTests/TestRunnerTests/ParserTests/TestFileHeaderAndIncludeTests.cs
@@ -50,6 +50,46 @@ public void Unknown_Annotations_And_Bare_Keywords_Are_Ignored()
         h.Teardown.Should().BeEmpty();
         h.ConnectionName.Should().BeNull();
     }
+
+    [Fact]
+    public void Tags_Are_Parsed_With_Whitespace_Or_Commas()
+    {
+        var h = TestFileHeader.Parse("-- @tag smoke, regression\n-- @tag slow\nselect 1;");
+        h.Tags.Should().Equal("smoke", "regression", "slow");
+    }
+}
+
+public class TagFilterTests
+{
+    [Theory]
+    [InlineData(new[] { "smoke" }, new string[0], new string[0], true)]                 // no filters => runs
+    [InlineData(new[] { "smoke" }, new[] { "smoke" }, new string[0], true)]             // include hit
+    [InlineData(new[] { "smoke" }, new[] { "SMOKE" }, new string[0], true)]             // case-insensitive
+    [InlineData(new string[0], new[] { "smoke" }, new string[0], false)]                // include set, file untagged
+    [InlineData(new[] { "smoke", "slow" }, new string[0], new[] { "slow" }, false)]     // exclude hit
+    [InlineData(new[] { "smoke", "slow" }, new[] { "smoke" }, new[] { "slow" }, false)] // exclude wins over include
+    public void Tag_Filter_Matches(string[] fileTags, string[] include, string[] exclude, bool expected)
+    {
+        NpgsqlRestClient.Testing.TestRunner.MatchesTags(
+            fileTags,
+            new HashSet<string>(include, StringComparer.OrdinalIgnoreCase),
+            new HashSet<string>(exclude, StringComparer.OrdinalIgnoreCase)).Should().Be(expected);
+    }
+}
+
+public class FilterMatchTests
+{
+    [Theory]
+    [InlineData("tests/login_succeeds.test.sql", "login", true)]                  // no wildcard => substring
+    [InlineData("tests/login_succeeds.test.sql", "LOGIN", true)]                  // substring is case-insensitive
+    [InlineData("tests/get_users.test.sql", "login", false)]
+    [InlineData("tests/login_succeeds.test.sql", "*login*", true)]                // wildcard => glob
+    [InlineData("tests/sub/deep.test.sql", "tests/sub/*", true)]
+    [InlineData("tests\\win\\style.test.sql", "tests/win/*", true)]               // separators normalized
+    public void Filter_Matches_Substring_Or_Glob(string path, string filter, bool expected)
+    {
+        NpgsqlRestClient.Testing.TestRunner.MatchesFilter(path, filter).Should().Be(expected);
+    }
 }
 
 public class IncludeParseTests
diff --git a/changelog/v3.19.0.md b/changelog/v3.19.0.md
index fefdf6c5..4a5be38d 100644
--- a/changelog/v3.19.0.md
+++ b/changelog/v3.19.0.md
@@ -183,6 +183,7 @@ An individual test file can attach named steps — and pick its own connection 
 - `-- @setup Name [Name …]` — runs the named steps **before this file** (own connections, committed work — e.g. clone a database this file will use). An unknown step name fails the file with an error.
 - `-- @teardown Name [Name …]` — runs **after this file, always** (best-effort, even when the test fails or times out), after the file's connection is closed — so a `drop database … with (force)` teardown works. An unknown step name logs a warning.
 - `-- @connection Name` — runs this file, **including its in-process endpoint calls**, on a named `ConnectionStrings` entry instead of the test connection. An unknown name fails the file with an error.
+- `-- @tag Name [Name …]` — declares the file's tags, filtered with the `Tag`/`ExcludeTag` options (see the filtering section below).
 
 `@setup` and `@teardown` are **repeatable**, and one line may carry **several names, separated by whitespace or commas** (the NpgsqlRest annotation idiom — `-- @setup A B`, `-- @setup A, B`, and two `-- @setup` lines are all equivalent). Names accumulate and execute in **exactly the order written** — the same contract as the global `Setup`/`Teardown` arrays; teardown is *not* reversed, so write the step you want last, last. Setup is fail-fast (the first failing or unknown step stops the chain, the file body never runs, teardown still runs); each teardown step is best-effort (a failure logs a warning and the remaining steps still run).
 
@@ -256,6 +257,9 @@ The runner logs through its own channel — **`NpgsqlRestTest`** (configurable v
 ```jsonc
 "TestRunner": {
   "FilePattern": "",                    // glob selecting test files (same engine as SqlFileSource); empty disables
+  "Filter": "",                         // narrow the discovered set: substring, or glob when it contains wildcards
+  "Tag": "",                            // run only files carrying at least one of these tags (-- @tag name ...)
+  "ExcludeTag": "",                     // skip files carrying any of these tags (wins over Tag)
   "ConnectionName": "",                 // ConnectionStrings entry to test against; empty = the main connection
   "MaxParallelism": 0,                  // concurrent test files; 0 = processor count
   "FailFast": false,                    // stop scheduling new files after the first failure (in-flight finish)
@@ -264,6 +268,9 @@ The runner logs through its own channel — **`NpgsqlRestTest`** (configurable v
   "Keep": false,                        // skip Teardown (inspect state after a failed run)
   "DetailedReport": false,              // detailed console report: passed ✓ lines, full failing SQL, notices for passing tests
   "AllowEmpty": false,                  // exit 0 instead of 4 when no tests are found
+  "Watch": false,                       // watch mode (CLI: --watch): re-run on file changes until Ctrl+C; teardown on exit
+  "Coverage": false,                    // endpoint-coverage summary: exercised N/M testable + the untested list
+  "CoverageThreshold": null,            // 0-100 (implies Coverage): fail an otherwise-passing run (exit 2) below it
   "LoggerName": "NpgsqlRestTest",       // the runner's log channel (leveled via Log:MinimalLevels)
   "ResponseTempTable": {
     "Name": "_response",                // table name when a file has ONE HTTP block
@@ -281,6 +288,45 @@ The runner logs through its own channel — **`NpgsqlRestTest`** (configurable v
 
 A practical convention is to keep the `TestRunner` block (and quiet log levels) in a separate `test-config.json` layered on only for test runs: `npgsqlrest ./config.json ./test-config.json --test`.
 
+**Iterating on one test:** `Filter` narrows the run to matching files, and like every option it can be set from the command line:
+
+```
+npgsqlrest ./config.json ./test-config.json --test --testrunner:filter=login
+```
+
+A value without wildcards is a case-insensitive **substring** match against each file's cwd-relative path (`login` runs every `*login*` file); a value with wildcards uses the same glob engine as `FilePattern` (`**/get_users_shows*`). `Setup` and `Teardown` still run — the filtered subset executes in the complete environment — and a filter that matches nothing exits with code `4` (`AllowEmpty` applies).
+
+**Tags** group tests orthogonally to the directory layout. A file declares them with a header annotation, and runs are narrowed with `Tag` (include — the file must carry at least one) and `ExcludeTag` (skip — wins over include); both accept comma- or whitespace-separated lists, case-insensitive, and compose with `Filter`:
+
+```sql
+-- @tag smoke, regression
+```
+
+```
+npgsqlrest ... --test --testrunner:tag=smoke --testrunner:excludetag=slow
+```
+
+Since includes behave as if pasted, tags travel through a **shared profile** too: a profile file carrying `-- @tag isolation, slow` next to its `-- @setup`/`-- @connection` annotations tags *every test that attaches it* — e.g. all clone-isolated tests are automatically `slow`, so the everyday dev loop is just `--testrunner:excludetag=slow`, with zero per-file bookkeeping.
+
+**Endpoint coverage** (`Coverage: true`, or just set a threshold) is something only an integrated runner can offer: the runner knows the **entire API surface** it built *and* records every endpoint the tests actually invoked, so after the run it reports the API-level analogue of code coverage — including the exact endpoints no test touches:
+
+```
+19 passed, 0 failed, 0 error(s)  —  19 assertions in 9 files
+
+endpoint coverage: 1/2 (50%)
+        untested: GET /api/get-users
+```
+
+Endpoint kinds the runner rejects (SSE, upload, login/logout, outbound proxy) are excluded from the ratio and counted separately, so the number is honest. **`CoverageThreshold`** (0–100, implies `Coverage`) turns it into a CI gate: an otherwise-passing run below the threshold exits `2` — set it to `100` and forgetting to write a test for a new endpoint fails the build, naming the endpoint. "Covered" means *invoked at least once by a test* — execution, not assertion depth (the same semantics as code coverage).
+
+**Watch mode** (`--watch`, or `TestRunner:Watch`) keeps the process alive and re-runs on change — and because the endpoint middleware is built once at startup, re-runs are near-instant:
+
+```
+npgsqlrest ./config.json ./test-config.json --test --watch
+```
+
+`Setup` runs once, then everything runs once, then the `FilePattern` base directory is watched recursively for `*.sql` changes (debounced): a changed **test file** re-runs alone (the `Filter` still applies); any **other** changed `.sql` — an included fixture or profile, whose dependents are unknown — re-runs everything. `Teardown` runs **once, on exit**: Ctrl+C (SIGINT) and SIGTERM (e.g. `docker stop`) are intercepted so the test database is still dropped cleanly. Interactive/dev-only: a graceful stop exits `0` regardless of test outcomes — watch is not for CI gating. Endpoint *sources* are not watched (endpoints are built once) — restart to rebuild them.
+
 ### Project layout
 
 Two equally supported conventions — the difference is just the globs:
@@ -322,8 +368,8 @@ Each named logger is controlled independently — e.g. mute the application logg
 - The test runner's core hooks are additive and inert outside `--test`: an ambient-connection accessor on the endpoint pipeline (null by default) and response headers on the internal invocation result. Normal server operation is unchanged.
 - Test files run **statement by statement** (the client operates Npgsql with SQL rewriting disabled — one statement per command), which is also `psql`'s default execution model; explicit `begin`/`commit`/`rollback` in a file work as ordinary statements. `Setup`/`Teardown` `Sql`/`SqlFile` steps execute the same way — which is why `create database` works as a plain step.
 - All new options are wired through the client configuration: `appsettings.json`, the JSON-schema descriptions, and the `--config` template.
-- Working examples: [`examples/19_testing_basic`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/19_testing_basic) (co-located layout, multi-step scenario files), [`examples/20_testing_newdb`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/20_testing_newdb) (separate `tests/` tree, one test per file, fresh test database per run via named steps, deferrable-constraint fixtures, authorization + user parameters), and [`examples/21_testing_isolation`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/21_testing_isolation) (template-clone workflow; two parallel per-test isolated databases — named apart with the indexed `{rnd5_1}`/`{rnd5_2}` tokens — proving deterministic sequence ids; a shared annotation profile attached via `\ir`; a `Command` step mixed with named-step references in Setup).
+- Working examples: [`examples/19_testing_basic`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/19_testing_basic) (co-located layout, multi-step scenario files), [`examples/20_testing_newdb`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/20_testing_newdb) (separate `tests/` tree, one test per file, fresh test database per run via named steps, deferrable-constraint fixtures, authorization + user parameters, a tag taxonomy — `smoke`/`auth`/`fixtures`/`login` — on every file), and [`examples/21_testing_isolation`](https://github.com/NpgsqlRest/npgsqlrest-docs/tree/master/examples/21_testing_isolation) (template-clone workflow; two parallel per-test isolated databases — named apart with the indexed `{rnd5_1}`/`{rnd5_2}` tokens — proving deterministic sequence ids; a shared annotation profile attached via `\ir` that also carries the `isolation, slow` tags; a `Command` step mixed with named-step references in Setup).
 
 ## Tests
 
-Full test suite green (2351), including 50 parser unit tests for the test-file, HTTP-block, header-annotation, and include parsers (`NpgsqlRestTests/TestRunnerTests/ParserTests/`). All three documentation examples verified end-to-end against live PostgreSQL — including example 21's template-clone workflow (template migrated once; the shared run database and **two parallel per-test isolated databases** cloned from it concurrently; deterministic sequence ids asserted independently in both clones; everything dropped on teardown). The new configuration keys are covered by the configuration round-trip tests (the `--config` template output matches `appsettings.json`).
+Full test suite green (2364), including 63 unit tests for the test-file, HTTP-block, header-annotation, and include parsers plus the filter and tag matchers (`NpgsqlRestTests/TestRunnerTests/ParserTests/`). All three documentation examples verified end-to-end against live PostgreSQL — including example 21's template-clone workflow (template migrated once; the shared run database and **two parallel per-test isolated databases** cloned from it concurrently; deterministic sequence ids asserted independently in both clones; everything dropped on teardown), watch mode (single-file rerun on a test change, full rerun on a fixture change, teardown on SIGINT/SIGTERM), path and tag filtering (including tags carried through a profile include), and the coverage report with a failing threshold gate. The new configuration keys are covered by the configuration round-trip tests (the `--config` template output matches `appsettings.json`).

From 45a5e81d2b374a8efc7423768222572411d774ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Thu, 2 Jul 2026 20:06:29 +0200
Subject: [PATCH 16/25] feat(test-runner): watch rebuilds endpoints, guaranteed
 teardown, themed report
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Watch mode — endpoint source tree (SqlFileSource):
- When the SQL file source is enabled, watch mode also watches its tree: a
  changed endpoint file triggers an in-process endpoint rebuild (UseNpgsqlRest
  re-reads + re-describes against the test database and atomically swaps the
  endpoint registry; a failed rebuild keeps the previous endpoints) followed
  by a full rerun. The endpoint delta is reported after each rebuild
  (+ METHOD path / - METHOD path "endpoint dropped - check its SQL file"), so
  breaking an endpoint mid-session is visible immediately and fixing it
  recovers - no restart. Watch mode forces SqlFileSource.ErrorMode from Exit
  to Skip (a broken file must not kill the session); non-watch --test keeps
  Exit for CI.

Guaranteed teardown (fixes two database-leak classes):
- From Setup onward, SIGINT (Ctrl+C) and SIGTERM are intercepted and Teardown
  runs SYNCHRONOUSLY in the signal handler - wrappers like `bun run` forward
  Ctrl+C to the process group and kill their children immediately, so the old
  cooperative unwind lost the race and leaked the test database. A second
  signal force-quits. Non-watch --test previously had no handler at all.
- An AppDomain.ProcessExit hook covers hard exits: SqlFileSource
  ErrorMode=Exit's Environment.Exit(1) previously leaked the just-created
  test database; exit code unchanged, Teardown now runs first.
- All paths funnel into a run-once teardown that hands every caller the SAME
  task (a fire-once no-op guard let the process exit mid-DROP).
- An interrupted non-watch run exits 2.

Console report themed to Serilog's Code theme:
- FAIL/ERROR labels render as the byte-identical chip the Code theme uses for
  its ERR/FTL level (red-197 on grey-238); PASS uses the same chip grammar in
  the mirror green-47; line text stays in the terminal's normal color; ALL
  failure text unified on the theme's red-197 foreground (two stragglers used
  16-color ConsoleColor.Red, which renders orange in some themes).
  Out.LineChip renders chips, plain when redirected.

Changelog updated (endpoint watching, teardown guarantees, report theming,
exit codes). Full suite green (2364); verified live: benign endpoint edit ->
rebuild + green, broken endpoint -> dropped-endpoint delta + failing tests,
fix -> recovery; broken-endpoint hard exit -> exit 1 with ZERO leaked
databases; watch SIGTERM -> full teardown, zero leftovers.
---
 NpgsqlRestClient/App.cs                       |  10 +-
 NpgsqlRestClient/ConfigSchemaGenerator.cs     |   2 +-
 NpgsqlRestClient/ConfigTemplate.cs            |   8 +-
 NpgsqlRestClient/Out.cs                       |  25 +-
 NpgsqlRestClient/Program.cs                   |  39 ++-
 NpgsqlRestClient/Testing/TestRunner.cs        | 250 ++++++++++++++----
 NpgsqlRestClient/Testing/TestRunnerOptions.cs |   7 +-
 NpgsqlRestClient/appsettings.json             |   8 +-
 changelog/v3.19.0.md                          |  16 +-
 9 files changed, 288 insertions(+), 77 deletions(-)

diff --git a/NpgsqlRestClient/App.cs b/NpgsqlRestClient/App.cs
index ba97954b..8978f83b 100644
--- a/NpgsqlRestClient/App.cs
+++ b/NpgsqlRestClient/App.cs
@@ -621,7 +621,7 @@ public List<IEndpointCreateHandler> CreateCodeGenHandlers(string connectionStrin
         return handlers;
     }
 
-    public List<IEndpointSource> CreateEndpointSources()
+    public List<IEndpointSource> CreateEndpointSources(bool relaxSqlFileErrors = false)
     {
         var sources = new List<IEndpointSource>(2);
 
@@ -684,6 +684,14 @@ public List<IEndpointSource> CreateEndpointSources()
                 {
                     opts.ErrorMode = _config.GetConfigEnum<ParseErrorMode>("ErrorMode", sqlFileSourceCfg);
                 }
+                if (relaxSqlFileErrors && opts.ErrorMode == ParseErrorMode.Exit)
+                {
+                    // Watch mode rebuilds endpoints on the fly; ErrorMode=Exit would kill the whole watch
+                    // session (Environment.Exit) on a broken SQL file — Skip drops the file instead, and
+                    // the runner reports the endpoint delta after each rebuild.
+                    opts.ErrorMode = ParseErrorMode.Skip;
+                    _builder.TestLogger?.LogDebug("watch mode: SqlFileSource ErrorMode forced from Exit to Skip");
+                }
                 var resultPrefix = _config.GetConfigStr("ResultPrefix", sqlFileSourceCfg);
                 if (resultPrefix is not null)
                 {
diff --git a/NpgsqlRestClient/ConfigSchemaGenerator.cs b/NpgsqlRestClient/ConfigSchemaGenerator.cs
index 895d01e5..512469ab 100644
--- a/NpgsqlRestClient/ConfigSchemaGenerator.cs
+++ b/NpgsqlRestClient/ConfigSchemaGenerator.cs
@@ -259,7 +259,7 @@ public static partial class ConfigSchemaGenerator
         ["TestRunner:Keep"] = "Skip Teardown so a failed run's state can be inspected.",
         ["TestRunner:DetailedReport"] = "Detailed console REPORT: list passed assertions, print the full failing SQL statement, and show captured `raise notice` output for passing tests too.\nThis shapes the report only — for diagnostic logging of every executed query/HTTP call, raise the log channel instead (Log:MinimalLevels + LoggerName).",
         ["TestRunner:AllowEmpty"] = "Treat \"no tests discovered\" as success (exit 0) instead of exit 4.",
-        ["TestRunner:Watch"] = "Watch mode (interactive/dev-only; CLI flag: --watch): run everything once, then re-run on file changes until Ctrl+C.\nA changed test file re-runs alone; any other changed .sql under the watched tree (e.g. an included fixture) re-runs everything. Endpoint sources are not watched — restart to rebuild endpoints. Teardown runs once, on exit; a graceful stop exits 0 (not for CI gating).",
+        ["TestRunner:Watch"] = "Watch mode (interactive/dev-only; CLI flag: --watch): run everything once, then re-run on file changes until Ctrl+C.\nA changed test file re-runs alone; a changed ENDPOINT file (SqlFileSource FilePattern) rebuilds the endpoints in-process (delta reported; ErrorMode forced Exit->Skip so a broken file cannot kill the session) and re-runs everything; any other changed .sql under the test tree (e.g. an included fixture) re-runs everything. Teardown runs once, on exit; a graceful stop exits 0 (not for CI gating).",
         ["TestRunner:LoggerName"] = "SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels (defaults to Information).\nDiscovery/parsing log at Debug, each query and HTTP invocation at Verbose, `raise notice` by severity. The console PASS/FAIL report is separate.",
         ["TestRunner:ResponseTempTable:Name"] = "Temp table name used when a test file has exactly ONE HTTP block.\nEach HTTP block gets its own fresh temp table (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified. Per-block override: `# @response <name>`.",
         ["TestRunner:ResponseTempTable:MultiNamePattern"] = "Temp table name pattern used when a test file has 2+ HTTP blocks.\n{n} is the 1-based block ordinal, e.g. \"_response_{n}\" => _response_1, _response_2, …",
diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index 7382ddcc..523c6848 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -1503,9 +1503,11 @@ public static partial class ConfigSchemaGenerator
         "AllowEmpty": false,
         //
         // Watch mode (interactive/dev-only; CLI flag: --watch): run everything once, then re-run on file
-        // changes until Ctrl+C. A changed test file re-runs alone; any other changed .sql under the watched
-        // tree (e.g. an included fixture) re-runs everything. Endpoint sources are not watched — restart to
-        // rebuild endpoints. Teardown runs once, on exit; a graceful stop exits 0 (not for CI gating).
+        // changes until Ctrl+C. A changed test file re-runs alone; a changed ENDPOINT file (SqlFileSource
+        // FilePattern) rebuilds the endpoints in-process (delta reported; ErrorMode forced Exit->Skip so a
+        // broken file cannot kill the session) and re-runs everything; any other changed .sql under the test
+        // tree (e.g. an included fixture) re-runs everything. Teardown runs once, on exit; a graceful stop
+        // exits 0 (not for CI gating).
         //
         "Watch": false,
         //
diff --git a/NpgsqlRestClient/Out.cs b/NpgsqlRestClient/Out.cs
index f1c9c05a..c690db96 100644
--- a/NpgsqlRestClient/Out.cs
+++ b/NpgsqlRestClient/Out.cs
@@ -47,7 +47,7 @@ public void Write(string line, ConsoleColor? color = null)
     }
 
     /// <summary>
-    /// Write a line wrapped in a raw ANSI SGR sequence (e.g. "\x1b[38;5;196m" for a 256-color foreground),
+    /// Write a line wrapped in a raw ANSI SGR sequence (e.g. "\x1b[38;5;197m" for a 256-color foreground),
     /// used when a specific color is needed that the 16-color <see cref="ConsoleColor"/> API can't express.
     /// Emits plain text (no escapes) when output is redirected, so piped/CI logs stay clean.
     /// </summary>
@@ -63,6 +63,29 @@ public void LineAnsi(string line, string ansiSgr)
         Console.WriteLine("\x1b[0m");
     }
 
+    /// <summary>
+    /// Write a line starting with a colored "chip" (the label rendered in its own SGR — e.g. white text on
+    /// a red background, like Serilog's ERR level chip) followed by the rest of the line, optionally in
+    /// another SGR. Emits plain text when output is redirected.
+    /// </summary>
+    public void LineChip(string chip, string chipSgr, string rest, string? restSgr = null)
+    {
+        if (Console.IsOutputRedirected)
+        {
+            Console.WriteLine(string.Concat(chip, rest));
+            return;
+        }
+        Console.Write(chipSgr);
+        Console.Write(chip);
+        Console.Write("\x1b[0m");
+        if (restSgr is not null)
+        {
+            Console.Write(restSgr);
+        }
+        Console.Write(rest);
+        Console.WriteLine("\x1b[0m");
+    }
+
     public void JsonHighlight(string json)
     {
         if (Console.IsOutputRedirected)
diff --git a/NpgsqlRestClient/Program.cs b/NpgsqlRestClient/Program.cs
index c17764f9..ea0f29c1 100644
--- a/NpgsqlRestClient/Program.cs
+++ b/NpgsqlRestClient/Program.cs
@@ -271,6 +271,10 @@
 
 bool endpointsMode = args.Any(a => string.Equals(a, "--endpoints", StringComparison.OrdinalIgnoreCase));
 bool testMode = args.Any(a => string.Equals(a, "--test", StringComparison.OrdinalIgnoreCase));
+// Watch mode (interactive re-run loop). Needed this early because it relaxes SqlFileSource error handling
+// (a broken endpoint file must not kill the watch session — see CreateEndpointSources).
+bool watchMode = testMode && (args.Any(a => string.Equals(a, "--watch", StringComparison.OrdinalIgnoreCase))
+    || config.GetConfigBool("Watch", config.Cfg.GetSection("TestRunner")));
 
 builder.BuildInstance();
 builder.Instance.Services.AddRouting();
@@ -474,7 +478,7 @@
     SseResponseHeaders = builder.GetSseResponseHeaders(),
     WarnUnboundSseNotices = config.GetConfigBool("WarnUnboundServerSentEventsNotices", config.NpgsqlRestCfg, true),
 
-    EndpointSources = appInstance.CreateEndpointSources(),
+    EndpointSources = appInstance.CreateEndpointSources(relaxSqlFileErrors: watchMode),
     UploadOptions = appInstance.CreateUploadOptions(),
     
     CacheOptions = builder.BuildCacheOptions(app, cacheType),
@@ -510,7 +514,7 @@
     catch (Exception ex)
     {
         // Configuration error (e.g. a Setup/Teardown entry referencing an unknown named step).
-        new Out().Line($"Test runner configuration error: {ex.Message}", ConsoleColor.Red);
+        new Out().LineAnsi($"Test runner configuration error: {ex.Message}", NpgsqlRestClient.Testing.TestRunner.AnsiFail);
         builder.TestLogger?.LogError(ex, "Test runner configuration error");
         Environment.ExitCode = NpgsqlRestClient.Testing.TestRunner.ExitConfig;
         return;
@@ -538,12 +542,31 @@
 if (testMode)
 {
     // Endpoints are now built; run the test files (then Teardown), and exit. `--watch` (or
-    // TestRunner:Watch) keeps the process alive and re-runs on file changes until Ctrl+C.
-    bool watchMode = args.Any(a => string.Equals(a, "--watch", StringComparison.OrdinalIgnoreCase))
-        || testRunnerOptions!.Watch;
-    Environment.ExitCode = watchMode
-        ? await testRunner!.RunWatchAsync(EndpointCapture.Endpoints)
-        : await testRunner!.RunAsync(EndpointCapture.Endpoints);
+    // TestRunner:Watch) keeps the process alive and re-runs on file changes until Ctrl+C. When the SQL
+    // file source is enabled, watch mode also watches its tree: a changed endpoint file triggers an
+    // in-process endpoint rebuild (UseNpgsqlRest re-reads + re-describes and atomically swaps the
+    // endpoint registry) followed by a full test rerun.
+    if (watchMode)
+    {
+        string? endpointPattern = null;
+        var sqlFileCfg = config.NpgsqlRestCfg.GetSection("SqlFileSource");
+        if (sqlFileCfg.Exists() && config.GetConfigBool("Enabled", sqlFileCfg, true))
+        {
+            endpointPattern = config.GetConfigStr("FilePattern", sqlFileCfg);
+        }
+        Environment.ExitCode = await testRunner!.RunWatchAsync(
+            EndpointCapture.Endpoints,
+            endpointPattern,
+            () =>
+            {
+                app.UseNpgsqlRest(options);
+                return EndpointCapture.Endpoints;
+            });
+    }
+    else
+    {
+        Environment.ExitCode = await testRunner!.RunAsync(EndpointCapture.Endpoints);
+    }
     return;
 }
 
diff --git a/NpgsqlRestClient/Testing/TestRunner.cs b/NpgsqlRestClient/Testing/TestRunner.cs
index 953f5a8e..35ccafbd 100644
--- a/NpgsqlRestClient/Testing/TestRunner.cs
+++ b/NpgsqlRestClient/Testing/TestRunner.cs
@@ -16,9 +16,16 @@ namespace NpgsqlRestClient.Testing;
 /// </summary>
 public sealed class TestRunner
 {
-    // Failure/error color: ANSI 256-color 196 — the same red Serilog's Code theme uses (truer than the
-    // 16-color ConsoleColor.Red, which renders orange in some themes). Emitted only to a real terminal.
-    private const string AnsiFail = "\x1b[38;5;196m";
+    // Report styling, matched to Serilog's Code theme: the FAIL/ERROR label renders as the byte-identical
+    // CHIP the Code theme uses for its ERR/FTL level — red-197 text on a dark-grey-238 background (NOT the
+    // white-on-red-196 chip, which is the Literate theme's). PASS uses the same chip grammar with green-47,
+    // the exact color-cube mirror of red-197 (#ff005f ↔ #00ff5f). ALL failure text uses the red-197
+    // foreground (never 16-color ConsoleColor.Red, which renders orange in some themes). Escapes are
+    // emitted only on a real terminal (see Out).
+    private const string AnsiFailChip = "\x1b[38;5;197m\x1b[48;5;238m";
+    private const string AnsiPassChip = "\x1b[38;5;47m\x1b[48;5;238m";
+    public const string AnsiFail = "\x1b[38;5;197m";
+    private const string AnsiOk = "\x1b[38;5;47m";
 
     public const int ExitPass = 0;
     public const int ExitFailures = 1;
@@ -41,6 +48,19 @@ public sealed class TestRunner
     // Endpoints actually invoked during the run (canonical "METHOD path" keys) — the coverage numerator.
     private readonly ConcurrentDictionary<string, byte> _invoked = new(StringComparer.OrdinalIgnoreCase);
 
+    // Lifetime cleanup: from Setup onward, SIGINT/SIGTERM and process exit all funnel into a run-once
+    // Teardown, executed SYNCHRONOUSLY in the signal handler — not after the run loop unwinds. A parent
+    // process (bun/npm run, a shell) that kills its children right after forwarding Ctrl+C would otherwise
+    // win the race and leak the test database. ProcessExit additionally covers hard exits such as
+    // SqlFileSource ErrorMode=Exit calling Environment.Exit(1). (A parent that SIGKILLs instantly is not
+    // survivable — this shrinks the window to the teardown itself.)
+    private readonly CancellationTokenSource _stop = new();
+    private readonly object _teardownLock = new();
+    private Task? _teardownTask;
+    private int _signalCount;
+    private System.Runtime.InteropServices.PosixSignalRegistration? _sigInt;
+    private System.Runtime.InteropServices.PosixSignalRegistration? _sigTerm;
+
     private enum Outcome { Pass, Fail, Error }
 
     // Result of executing one step. Emit=false marks an arrange/act step that is not a reported test (it
@@ -93,9 +113,48 @@ public TestRunner(NpgsqlRestOptions rest, TestRunnerOptions opt, string baseConn
         _rest.AmbientConnectionAccessor = () => Ambient.Value;
     }
 
+    // Registers the run-once cleanup triggers. First SIGINT/SIGTERM: cancel everything, then run Teardown
+    // right here on the signal thread (ctx.Cancel keeps the process alive for it); a second signal force-
+    // quits. ProcessExit is the safety net for Environment.Exit paths and no-ops after a normal teardown.
+    private void RegisterLifetimeCleanup()
+    {
+        void OnSignal(System.Runtime.InteropServices.PosixSignalContext ctx)
+        {
+            if (Interlocked.Increment(ref _signalCount) > 1)
+            {
+                return; // second signal: leave ctx.Cancel=false → default handling kills the process
+            }
+            ctx.Cancel = true;
+            _stop.Cancel();
+            try { TeardownOnceAsync().GetAwaiter().GetResult(); } catch { /* best-effort */ }
+        }
+        _sigInt = System.Runtime.InteropServices.PosixSignalRegistration.Create(
+            System.Runtime.InteropServices.PosixSignal.SIGINT, OnSignal);
+        _sigTerm = System.Runtime.InteropServices.PosixSignalRegistration.Create(
+            System.Runtime.InteropServices.PosixSignal.SIGTERM, OnSignal);
+        AppDomain.CurrentDomain.ProcessExit += (s, e) =>
+        {
+            try { TeardownOnceAsync().GetAwaiter().GetResult(); } catch { /* best-effort */ }
+        };
+    }
+
+    // All teardown paths (signal, process exit, RunAsync/RunWatchAsync finally, Setup failure) funnel here.
+    // The first caller starts it; every caller gets the SAME task — so a concurrent caller (e.g. the run
+    // loop's finally racing the signal thread) awaits the in-flight teardown instead of letting the process
+    // exit while databases are still being dropped.
+    private Task TeardownOnceAsync()
+    {
+        lock (_teardownLock)
+        {
+            _teardownTask ??= TeardownAsync(CancellationToken.None);
+            return _teardownTask;
+        }
+    }
+
     /// <summary>Runs before endpoint discovery: collision check + Setup steps. Returns false on failure (logged, teardown attempted).</summary>
     public async Task<bool> SetupAsync(CancellationToken ct = default)
     {
+        RegisterLifetimeCleanup();
         try
         {
             // Response-table names are validated and created per HTTP block (no pre-run permanent-table
@@ -114,9 +173,9 @@ public async Task<bool> SetupAsync(CancellationToken ct = default)
         }
         catch (Exception ex)
         {
-            _out.Line($"Test runner setup failed: {ex.Message}", ConsoleColor.Red);
+            _out.LineAnsi($"Test runner setup failed: {ex.Message}", AnsiFail);
             _log?.LogError(ex, "Test runner setup failed");
-            await TeardownAsync(ct);
+            await TeardownOnceAsync();
             return false;
         }
     }
@@ -154,13 +213,19 @@ private string ResolveStepConnection(TestSetupStep step)
     /// <summary>Runs after endpoint discovery: executes the test files and (always) Teardown. Returns the process exit code.</summary>
     public async Task<int> RunAsync(RoutineEndpoint[] endpoints, CancellationToken ct = default)
     {
+        using var linked = CancellationTokenSource.CreateLinkedTokenSource(_stop.Token, ct);
         try
         {
-            return await ExecuteDiscoveredFilesAsync(endpoints, BuildEndpointLookup(endpoints), only: null, ct);
+            return await ExecuteDiscoveredFilesAsync(endpoints, BuildEndpointLookup(endpoints), only: null, linked.Token);
+        }
+        catch (OperationCanceledException)
+        {
+            // Interrupted (Ctrl+C/SIGTERM) — the signal handler has already run Teardown synchronously.
+            return ExitErrors;
         }
         finally
         {
-            await TeardownAsync(ct);
+            await TeardownOnceAsync();
         }
     }
 
@@ -325,81 +390,123 @@ public static bool MatchesTags(IReadOnlyList<string> fileTags, IReadOnlySet<stri
 
     /// <summary>
     /// Watch mode (interactive/dev-only): runs everything once, then re-runs on file changes until
-    /// Ctrl+C. A changed TEST file re-runs just that file; any other changed .sql under the watched tree
-    /// (e.g. a \ir fixture — its dependents are unknown) re-runs everything. Endpoint sources are NOT
-    /// watched (endpoints are built once at startup — restart to rebuild). Teardown runs once, on exit;
-    /// the exit code is always 0 on a graceful stop (watch is not for CI gating).
+    /// Ctrl+C. A changed TEST file re-runs just that file; a changed ENDPOINT file (matching
+    /// <paramref name="endpointPattern"/>, when the SQL file source is enabled) triggers an in-process
+    /// endpoint REBUILD via <paramref name="rebuildEndpoints"/> followed by a full rerun; any other
+    /// changed .sql under the test tree (e.g. a \ir fixture — its dependents are unknown) re-runs
+    /// everything. Teardown runs once, on exit; the exit code is always 0 on a graceful stop (watch is
+    /// not for CI gating).
     /// </summary>
-    public async Task<int> RunWatchAsync(RoutineEndpoint[] endpoints, CancellationToken ct = default)
+    public async Task<int> RunWatchAsync(
+        RoutineEndpoint[] endpoints,
+        string? endpointPattern = null,
+        Func<RoutineEndpoint[]>? rebuildEndpoints = null,
+        CancellationToken ct = default)
     {
         var lookup = BuildEndpointLookup(endpoints);
-        using var stop = CancellationTokenSource.CreateLinkedTokenSource(ct);
-        // PosixSignalRegistration (not Console.CancelKeyPress, which is unreliable without a TTY):
-        // intercept both Ctrl+C (SIGINT) and e.g. `docker stop` (SIGTERM), cancel the default kill so the
-        // loop can end gracefully and Teardown can run.
-        void OnSignal(System.Runtime.InteropServices.PosixSignalContext ctx)
-        {
-            ctx.Cancel = true;
-            stop.Cancel();
-        }
-        using var sigInt = System.Runtime.InteropServices.PosixSignalRegistration.Create(
-            System.Runtime.InteropServices.PosixSignal.SIGINT, OnSignal);
-        using var sigTerm = System.Runtime.InteropServices.PosixSignalRegistration.Create(
-            System.Runtime.InteropServices.PosixSignal.SIGTERM, OnSignal);
+        // SIGINT/SIGTERM handling is registered runner-wide (see RegisterLifetimeCleanup): the FIRST signal
+        // cancels this token and runs Teardown synchronously on the signal thread — so cleanup wins even
+        // when a parent process (bun/npm run) kills its children right after forwarding Ctrl+C.
+        using var stop = CancellationTokenSource.CreateLinkedTokenSource(_stop.Token, ct);
 
         try
         {
             await ExecuteDiscoveredFilesAsync(endpoints, lookup, only: null, stop.Token);
 
-            var baseDir = GetWatchBaseDir(_opt.FilePattern);
-            if (baseDir is null)
+            var testBase = GetWatchBaseDir(_opt.FilePattern);
+            if (testBase is null)
             {
                 _out.Line("Test runner: cannot watch — FilePattern has no existing base directory.", ConsoleColor.Yellow);
                 return ExitConfig;
             }
+            var testBaseFull = Path.GetFullPath(testBase);
+            var endpointBaseFull = rebuildEndpoints is not null && !string.IsNullOrWhiteSpace(endpointPattern)
+                ? GetWatchBaseDir(endpointPattern!) is { } eb ? Path.GetFullPath(eb) : null
+                : null;
 
             var changes = System.Threading.Channels.Channel.CreateUnbounded<string>();
-            using var watcher = new FileSystemWatcher(Path.GetFullPath(baseDir), "*.sql")
-            {
-                IncludeSubdirectories = true,
-                NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.FileName | NotifyFilters.Size,
-            };
             void OnFsEvent(object s, FileSystemEventArgs e) => changes.Writer.TryWrite(e.FullPath);
-            watcher.Changed += OnFsEvent;
-            watcher.Created += OnFsEvent;
-            watcher.Renamed += (s, e) => changes.Writer.TryWrite(e.FullPath);
-            watcher.EnableRaisingEvents = true;
-
-            _out.Line($"\nwatching {Path.GetRelativePath(Environment.CurrentDirectory, baseDir)} for changes — Ctrl+C to stop", ConsoleColor.Cyan);
+            FileSystemWatcher NewWatcher(string dir)
+            {
+                var w = new FileSystemWatcher(dir, "*.sql")
+                {
+                    IncludeSubdirectories = true,
+                    NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.FileName | NotifyFilters.Size,
+                };
+                w.Changed += OnFsEvent;
+                w.Created += OnFsEvent;
+                w.Renamed += (s, e) => changes.Writer.TryWrite(e.FullPath);
+                w.EnableRaisingEvents = true;
+                return w;
+            }
+            using var watcher = NewWatcher(testBaseFull);
+            // Watch the endpoint source tree too (unless it is the same/contained directory — the
+            // co-located layout — where the first watcher already covers it).
+            bool separateEndpointTree = endpointBaseFull is not null
+                && !testBaseFull.StartsWith(endpointBaseFull, StringComparison.Ordinal)
+                && !endpointBaseFull.StartsWith(testBaseFull, StringComparison.Ordinal);
+            using var endpointWatcher = separateEndpointTree ? NewWatcher(endpointBaseFull!) : null;
+
+            var watching = Path.GetRelativePath(Environment.CurrentDirectory, testBaseFull)
+                + (endpointBaseFull is not null && endpointBaseFull != testBaseFull
+                    ? $" + {Path.GetRelativePath(Environment.CurrentDirectory, endpointBaseFull)} (endpoints)"
+                    : "");
+            _out.Line($"\nwatching {watching} for changes — Ctrl+C to stop", ConsoleColor.Cyan);
 
             while (!stop.IsCancellationRequested)
             {
-                var changed = await NextChangeBatchAsync(changes.Reader, stop.Token);
+                var changed = (await NextChangeBatchAsync(changes.Reader, stop.Token))?.Distinct().ToList();
                 if (changed is null) break; // cancelled
 
-                // Debounced batch: changed test files rerun individually; any other .sql (fixture/profile
-                // include) forces a full rerun since its dependents are unknown.
+                // Debounced batch, classified per file: test file → rerun it alone; endpoint source →
+                // rebuild endpoints + full rerun; anything else under the test tree (fixture/profile
+                // include — dependents unknown) → full rerun; anything else → ignore.
                 var testFiles = new List<string>();
                 bool runAll = false;
+                bool rebuild = false;
                 foreach (var path in changed)
                 {
-                    // Watcher paths are absolute; FilePattern is cwd-relative — compare in relative form.
                     var rel = Path.GetRelativePath(Environment.CurrentDirectory, path).Replace('\\', '/');
-                    var pattern = _opt.FilePattern.Replace('\\', '/');
-                    if (pattern.StartsWith("./")) pattern = pattern[2..];
-                    if (Parser.IsPatternMatch(rel, pattern))
+                    if (MatchesCwdRelativePattern(rel, _opt.FilePattern))
                     {
                         if (File.Exists(path)) testFiles.Add(Path.GetFullPath(path));
                     }
-                    else
+                    else if (endpointPattern is not null && rebuildEndpoints is not null
+                        && MatchesCwdRelativePattern(rel, endpointPattern))
+                    {
+                        rebuild = true;
+                    }
+                    else if (Path.GetFullPath(path).StartsWith(testBaseFull, StringComparison.Ordinal))
                     {
                         runAll = true;
                     }
                 }
-                if (!runAll && testFiles.Count == 0) continue; // e.g. only deletions of test files
+                if (!rebuild && !runAll && testFiles.Count == 0) continue; // e.g. only deletions
 
                 var trigger = Path.GetRelativePath(Environment.CurrentDirectory, changed[0]);
                 _out.Line($"\n— {DateTime.Now:HH:mm:ss} change detected ({trigger}{(changed.Count > 1 ? $" +{changed.Count - 1}" : "")}) —", ConsoleColor.Cyan);
+
+                if (rebuild)
+                {
+                    // In-process endpoint rebuild: UseNpgsqlRest re-reads the sources, re-describes against
+                    // the test database, and atomically swaps the endpoint registry. On failure the old
+                    // endpoints stay live. The delta report makes a dropped endpoint (= a broken SQL file,
+                    // skipped by ErrorMode=Skip) visible even when the NpgsqlRest log channel is muted.
+                    try
+                    {
+                        var fresh = rebuildEndpoints!();
+                        ReportEndpointDelta(endpoints, fresh);
+                        endpoints = fresh;
+                        lookup = BuildEndpointLookup(fresh);
+                    }
+                    catch (Exception ex)
+                    {
+                        _out.LineAnsi($"endpoint rebuild failed: {ex.Message} — keeping the previous endpoints", AnsiFail);
+                        _log?.LogError(ex, "endpoint rebuild failed");
+                    }
+                    runAll = true;
+                }
+
                 await ExecuteDiscoveredFilesAsync(endpoints, lookup, only: runAll ? null : testFiles.Distinct().ToList(), stop.Token);
                 _out.Line($"\nwatching — Ctrl+C to stop", ConsoleColor.Cyan);
             }
@@ -411,9 +518,42 @@ void OnSignal(System.Runtime.InteropServices.PosixSignalContext ctx)
         }
         finally
         {
-            // Teardown must survive the SIGINT/SIGTERM that ended the loop → uncancellable token.
-            await TeardownAsync(CancellationToken.None);
+            // Normally a no-op: the signal handler already ran Teardown; covers non-signal exits.
+            await TeardownOnceAsync();
+        }
+    }
+
+    // A cwd-relative path against a cwd-relative glob (leading "./" tolerated on the pattern).
+    private static bool MatchesCwdRelativePattern(string relativePath, string pattern)
+    {
+        pattern = pattern.Replace('\\', '/');
+        if (pattern.StartsWith("./")) pattern = pattern[2..];
+        return Parser.IsPatternMatch(relativePath, pattern);
+    }
+
+    // Rebuild delta: how many endpoints now, plus every added/removed "METHOD path" — a removed endpoint
+    // usually means its SQL file failed to parse/describe and was skipped.
+    private void ReportEndpointDelta(RoutineEndpoint[] before, RoutineEndpoint[] after)
+    {
+        static HashSet<string> Keys(RoutineEndpoint[] eps) =>
+            new(eps.Select(e => $"{e.Method} {e.Path}"), StringComparer.OrdinalIgnoreCase);
+        var beforeKeys = Keys(before);
+        var afterKeys = Keys(after);
+        var added = afterKeys.Except(beforeKeys).OrderBy(k => k, StringComparer.Ordinal).ToList();
+        var removed = beforeKeys.Except(afterKeys).OrderBy(k => k, StringComparer.Ordinal).ToList();
+
+        _out.Line($"endpoints rebuilt: {after.Length} (was {before.Length})",
+            removed.Count > 0 ? ConsoleColor.Yellow : ConsoleColor.Cyan);
+        foreach (var k in added)
+        {
+            _out.Line($"        + {k}", ConsoleColor.Green);
+        }
+        foreach (var k in removed)
+        {
+            _out.Line($"        - {k}  (endpoint dropped — check its SQL file for errors)", ConsoleColor.Yellow);
         }
+        _log?.LogDebug("endpoints rebuilt: {After} (was {Before}); +{Added} -{Removed}",
+            after.Length, before.Length, added.Count, removed.Count);
     }
 
     // First change (blocking), then a quiet period so editor write bursts coalesce into one rerun.
@@ -988,18 +1128,20 @@ private void ReportConsole(List<FileResult> results)
             if (fr.Assertions.Count == 0)
             {
                 // The file ran but contained no recognizable assertion — surface it rather than count a pass.
-                _out.Line($"PASS  {rel}  (no assertions, {fr.ElapsedMs}ms)", ConsoleColor.Yellow);
+                _out.LineChip("PASS", AnsiPassChip, $"  {rel}  (no assertions, {fr.ElapsedMs}ms)", "\x1b[38;5;229m");
             }
             else if (fr.Outcome == Outcome.Pass)
             {
-                _out.Line($"PASS  {rel}  ({aPass} assertion{(aPass == 1 ? "" : "s")}, {fr.ElapsedMs}ms)", ConsoleColor.Green);
+                _out.LineChip("PASS", AnsiPassChip, $"  {rel}  ({aPass} assertion{(aPass == 1 ? "" : "s")}, {fr.ElapsedMs}ms)");
                 if (_opt.DetailedReport)
                     foreach (var a in fr.Assertions) _out.Line($"        ✓ {a.Name}", ConsoleColor.DarkGray);
             }
             else
             {
-                var label = fr.Outcome == Outcome.Error ? "ERROR" : "FAIL ";
-                _out.LineAnsi($"{label} {rel}  ({fr.ElapsedMs}ms)", AnsiFail);
+                // The label renders as Serilog's error chip (white on red); the rest of the line stays in
+                // the terminal's normal text color — same visual grammar as a `[... ERR]` log line.
+                var label = fr.Outcome == Outcome.Error ? "ERROR" : "FAIL";
+                _out.LineChip(label, AnsiFailChip, $"{(fr.Outcome == Outcome.Error ? " " : "  ")}{rel}  ({fr.ElapsedMs}ms)");
                 foreach (var a in fr.Assertions)
                 {
                     if (a.Outcome == Outcome.Pass)
@@ -1020,7 +1162,7 @@ private void ReportConsole(List<FileResult> results)
         }
 
         var summary = $"\n{passed} passed, {failed} failed, {errored} error(s)  —  {totalAssertions} assertion{(totalAssertions == 1 ? "" : "s")} in {results.Count} file{(results.Count == 1 ? "" : "s")}";
-        if (failed + errored == 0) _out.Line(summary, ConsoleColor.Green);
+        if (failed + errored == 0) _out.LineAnsi(summary, AnsiOk);
         else _out.LineAnsi(summary, AnsiFail);
     }
 
diff --git a/NpgsqlRestClient/Testing/TestRunnerOptions.cs b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
index 935b527f..5b0ebb6a 100644
--- a/NpgsqlRestClient/Testing/TestRunnerOptions.cs
+++ b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
@@ -73,9 +73,10 @@ public class TestRunnerOptions
 
     /// <summary>
     /// Watch mode (interactive/dev-only; CLI: <c>--watch</c>): run everything once, then re-run on file
-    /// changes until Ctrl+C. A changed test file re-runs alone; any other changed .sql under the watched
-    /// tree re-runs everything (an included fixture's dependents are unknown). Endpoint sources are not
-    /// watched — restart to rebuild endpoints. Teardown runs once, on exit; graceful exit code is 0.
+    /// changes until Ctrl+C. A changed test file re-runs alone; a changed ENDPOINT file (SqlFileSource
+    /// FilePattern) rebuilds the endpoints in-process (delta reported) and re-runs everything; any other
+    /// changed .sql under the test tree re-runs everything (an included fixture's dependents are unknown).
+    /// Teardown runs once, on exit; graceful exit code is 0.
     /// </summary>
     public bool Watch { get; set; } = false;
 
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index 1b00ba09..822646c8 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -1494,9 +1494,11 @@
     "AllowEmpty": false,
     //
     // Watch mode (interactive/dev-only; CLI flag: --watch): run everything once, then re-run on file
-    // changes until Ctrl+C. A changed test file re-runs alone; any other changed .sql under the watched
-    // tree (e.g. an included fixture) re-runs everything. Endpoint sources are not watched — restart to
-    // rebuild endpoints. Teardown runs once, on exit; a graceful stop exits 0 (not for CI gating).
+    // changes until Ctrl+C. A changed test file re-runs alone; a changed ENDPOINT file (SqlFileSource
+    // FilePattern) rebuilds the endpoints in-process (delta reported; ErrorMode forced Exit->Skip so a
+    // broken file cannot kill the session) and re-runs everything; any other changed .sql under the test
+    // tree (e.g. an included fixture) re-runs everything. Teardown runs once, on exit; a graceful stop
+    // exits 0 (not for CI gating).
     //
     "Watch": false,
     //
diff --git a/changelog/v3.19.0.md b/changelog/v3.19.0.md
index 4a5be38d..c366b271 100644
--- a/changelog/v3.19.0.md
+++ b/changelog/v3.19.0.md
@@ -158,6 +158,8 @@ Run-once steps around the whole test session. **`Setup` runs before endpoint dis
 
 `Sql`/`SqlFile` steps run on the test connection by default, or on any named `ConnectionStrings` entry via a per-step `"ConnectionName"` — which enables maintenance operations like `create database` without the runner ever issuing DDL on its own.
 
+`Teardown` is guaranteed beyond the happy path: from Setup onward the runner intercepts **SIGINT (Ctrl+C) and SIGTERM** (e.g. `docker stop`) and runs Teardown **synchronously in the signal handler** — before the process can be torn down by an impatient parent (`bun run`/`npm run` forward Ctrl+C and may kill their children immediately; waiting for the run loop to unwind would lose that race). A second Ctrl+C force-quits. A **process-exit hook** additionally covers hard exits — e.g. a broken endpoint SQL file under `SqlFileSource.ErrorMode: Exit` calls `Environment.Exit(1)`, which previously leaked the just-created test database; the exit code is unchanged, but Teardown now runs first. All paths funnel into a run-once Teardown. (A parent that SIGKILLs instantly remains unsurvivable — that is what a leading `drop database if exists …` on a static name, or a periodic sweep, is for.)
+
 Steps can be defined once in the **`Steps` registry** (name → step, like `ConnectionStrings` or `CacheOptions.Profiles`) and referenced by name; `Setup`/`Teardown` arrays accept names and inline objects mixed. Referencing an unknown name is a configuration error (exit 3).
 
 ```jsonc
@@ -233,11 +235,13 @@ FAIL  tests/get_users.test.sql  (49ms)
 18 passed, 1 failed, 0 error(s)  —  19 assertions in 9 files
 ```
 
-Failures show the assertion name, `file:line`, and the failing statement. `DetailedReport: true` additionally lists passed assertions (`✓`), full failing SQL, and captured `raise notice` output for passing tests (notices always show under failing tests). This shapes the console report only — it is distinct from raising the `NpgsqlRestTest` *log* level, which controls diagnostics (see Logging below). A file with no recognizable assertions is flagged (yellow) rather than silently counted. Colors are disabled automatically when output is redirected.
+Failures show the assertion name, `file:line`, and the failing statement. `DetailedReport: true` additionally lists passed assertions (`✓`), full failing SQL, and captured `raise notice` output for passing tests (notices always show under failing tests). This shapes the console report only — it is distinct from raising the `NpgsqlRestTest` *log* level, which controls diagnostics (see Logging below). A file with no recognizable assertions is flagged rather than silently counted.
+
+The report's colors are **matched to Serilog's Code console theme**, so the test report and the log lines around it read as one output: the `FAIL`/`ERROR` labels render as the *byte-identical chip* the theme uses for its `ERR`/`FTL` level (red text on a dark-grey block), `PASS` uses the same chip grammar in the mirror green, the rest of each line stays in the terminal's normal text color, and all failure text uses the theme's error red — never the 16-color red that renders orange in some terminals. Colors are disabled automatically when output is redirected (piped/CI logs stay plain).
 
 **JUnit XML** (`JUnitOutput: "path.xml"`): one `<testcase>` per assertion (name = the assertion message, classname = the file), `<failure>`/`<error>` with message and `file:line`, captured notices in `<system-out>`, files without assertions marked `<skipped>` — works with any CI dashboard.
 
-**Exit codes:** `0` all passed · `1` at least one failure · `2` at least one error (SQL error, timeout, unsupported endpoint) · `3` setup/configuration error · `4` no test files found (`AllowEmpty: true` turns this into `0`).
+**Exit codes:** `0` all passed · `1` at least one failure · `2` at least one error (SQL error, timeout, unsupported endpoint, an interrupted run) · `3` setup/configuration error · `4` no test files found (`AllowEmpty: true` turns this into `0`).
 
 ### Logging
 
@@ -325,7 +329,13 @@ Endpoint kinds the runner rejects (SSE, upload, login/logout, outbound proxy) ar
 npgsqlrest ./config.json ./test-config.json --test --watch
 ```
 
-`Setup` runs once, then everything runs once, then the `FilePattern` base directory is watched recursively for `*.sql` changes (debounced): a changed **test file** re-runs alone (the `Filter` still applies); any **other** changed `.sql` — an included fixture or profile, whose dependents are unknown — re-runs everything. `Teardown` runs **once, on exit**: Ctrl+C (SIGINT) and SIGTERM (e.g. `docker stop`) are intercepted so the test database is still dropped cleanly. Interactive/dev-only: a graceful stop exits `0` regardless of test outcomes — watch is not for CI gating. Endpoint *sources* are not watched (endpoints are built once) — restart to rebuild them.
+`Setup` runs once, then everything runs once, then the test tree — **and, when the SQL file source is enabled, the endpoint source tree** — is watched recursively for `*.sql` changes (debounced). Changes are classified per file:
+
+- a changed **test file** re-runs alone (the `Filter` still applies);
+- a changed **endpoint file** (matching `SqlFileSource.FilePattern`) triggers an **in-process endpoint rebuild** — the sources are re-read and re-described against the test database, and the endpoint registry is swapped atomically — followed by a full rerun. After each rebuild the runner prints the **endpoint delta** (`+ POST /api/new`, `- GET /api/x  (endpoint dropped — check its SQL file for errors)`), so breaking an endpoint file mid-session is visible immediately: the endpoint drops out, its tests fail with 404 warnings, and fixing the file brings it right back — no restart. (To make this safe, watch mode forces `SqlFileSource.ErrorMode` from `Exit` to `Skip` — a broken file must not kill the watch session; non-watch `--test` keeps `Exit` for CI. A rebuild that fails entirely keeps the previous endpoints live.)
+- any **other** changed `.sql` under the test tree — an included fixture or profile, whose dependents are unknown — re-runs everything.
+
+`Teardown` runs **once, on exit** — synchronously inside the SIGINT/SIGTERM handler (see the Setup and Teardown section), so the test database is dropped even when the watch process is stopped through a wrapper like `bun run`; a second Ctrl+C force-quits. Interactive/dev-only: a graceful stop exits `0` regardless of test outcomes — watch is not for CI gating. Database-routine sources have no files to watch — restart to pick up catalog changes.
 
 ### Project layout
 

From 94667a9275a06eda04416caa9107ea382948baf6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Thu, 2 Jul 2026 20:19:24 +0200
Subject: [PATCH 17/25] fix(test-runner): one red style, one green style in the
 console report
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AnsiFail is now the full Serilog Code ERR chip style (red-197 on grey-238)
and is the ONLY red in the report — FAIL/ERROR labels and every failure line
(assertion details, messages, failing summary, coverage gate, setup/config
errors) share the exact same escape sequence, so they can never render
differently. AnsiOk is the mirror (green-47 on grey-238) for the PASS label
and the all-green summary. Indentation and blank lines are written outside
the styled block so the grey strip starts at the text.
---
 NpgsqlRestClient/Testing/TestRunner.cs | 41 +++++++++++++-------------
 1 file changed, 21 insertions(+), 20 deletions(-)

diff --git a/NpgsqlRestClient/Testing/TestRunner.cs b/NpgsqlRestClient/Testing/TestRunner.cs
index 35ccafbd..9388c0f8 100644
--- a/NpgsqlRestClient/Testing/TestRunner.cs
+++ b/NpgsqlRestClient/Testing/TestRunner.cs
@@ -16,16 +16,17 @@ namespace NpgsqlRestClient.Testing;
 /// </summary>
 public sealed class TestRunner
 {
-    // Report styling, matched to Serilog's Code theme: the FAIL/ERROR label renders as the byte-identical
-    // CHIP the Code theme uses for its ERR/FTL level — red-197 text on a dark-grey-238 background (NOT the
-    // white-on-red-196 chip, which is the Literate theme's). PASS uses the same chip grammar with green-47,
-    // the exact color-cube mirror of red-197 (#ff005f ↔ #00ff5f). ALL failure text uses the red-197
-    // foreground (never 16-color ConsoleColor.Red, which renders orange in some themes). Escapes are
-    // emitted only on a real terminal (see Out).
-    private const string AnsiFailChip = "\x1b[38;5;197m\x1b[48;5;238m";
-    private const string AnsiPassChip = "\x1b[38;5;47m\x1b[48;5;238m";
-    public const string AnsiFail = "\x1b[38;5;197m";
-    private const string AnsiOk = "\x1b[38;5;47m";
+    // Report styling, matched to Serilog's Code theme. There is exactly ONE red style and ONE green style:
+    // AnsiFail is byte-identical to the chip the Code theme uses for its ERR/FTL level — red-197 text on a
+    // dark-grey-238 background (NOT white-on-red-196, which is the Literate theme's chip) — and it is used
+    // for the FAIL/ERROR labels AND all failure text, so they can never look different. AnsiOk is the same
+    // grammar with green-47, the exact color-cube mirror of red-197 (#ff005f ↔ #00ff5f), used for the PASS
+    // label and the all-green summary. Never 16-color ConsoleColor.Red (renders orange in some themes).
+    // Indentation is written OUTSIDE the style so the grey block starts at the text. Escapes are emitted
+    // only on a real terminal (see Out).
+    public const string AnsiFail = "\x1b[38;5;197m\x1b[48;5;238m";
+    private const string AnsiOk = "\x1b[38;5;47m\x1b[48;5;238m";
+    private const string AnsiPlain = "\x1b[0m";
 
     public const int ExitPass = 0;
     public const int ExitFailures = 1;
@@ -349,7 +350,7 @@ private int ReportCoverage(RoutineEndpoint[] endpoints, int exit)
 
         var line = $"\nendpoint coverage: {covered}/{testable.Count} ({pct}%)"
             + (untestable > 0 ? $"  —  {untestable} endpoint(s) excluded (not testable in test mode)" : "");
-        if (gateFailed) _out.LineAnsi(line, AnsiFail);
+        if (gateFailed) { _out.NL(); _out.LineAnsi(line.TrimStart('\n'), AnsiFail); }
         else _out.Line(line, untested.Count == 0 ? ConsoleColor.Green : ConsoleColor.Yellow);
 
         foreach (var ep in untested)
@@ -360,7 +361,7 @@ private int ReportCoverage(RoutineEndpoint[] endpoints, int exit)
 
         if (gateFailed)
         {
-            _out.LineAnsi($"        coverage {pct}% is below the CoverageThreshold ({_opt.CoverageThreshold}%)", AnsiFail);
+            _out.LineChip("        ", AnsiPlain, $"coverage {pct}% is below the CoverageThreshold ({_opt.CoverageThreshold}%)", AnsiFail);
             if (exit == ExitPass) exit = ExitErrors;
         }
         return exit;
@@ -1128,11 +1129,11 @@ private void ReportConsole(List<FileResult> results)
             if (fr.Assertions.Count == 0)
             {
                 // The file ran but contained no recognizable assertion — surface it rather than count a pass.
-                _out.LineChip("PASS", AnsiPassChip, $"  {rel}  (no assertions, {fr.ElapsedMs}ms)", "\x1b[38;5;229m");
+                _out.LineChip("PASS", AnsiOk, $"  {rel}  (no assertions, {fr.ElapsedMs}ms)", "\x1b[38;5;229m");
             }
             else if (fr.Outcome == Outcome.Pass)
             {
-                _out.LineChip("PASS", AnsiPassChip, $"  {rel}  ({aPass} assertion{(aPass == 1 ? "" : "s")}, {fr.ElapsedMs}ms)");
+                _out.LineChip("PASS", AnsiOk, $"  {rel}  ({aPass} assertion{(aPass == 1 ? "" : "s")}, {fr.ElapsedMs}ms)");
                 if (_opt.DetailedReport)
                     foreach (var a in fr.Assertions) _out.Line($"        ✓ {a.Name}", ConsoleColor.DarkGray);
             }
@@ -1141,7 +1142,7 @@ private void ReportConsole(List<FileResult> results)
                 // The label renders as Serilog's error chip (white on red); the rest of the line stays in
                 // the terminal's normal text color — same visual grammar as a `[... ERR]` log line.
                 var label = fr.Outcome == Outcome.Error ? "ERROR" : "FAIL";
-                _out.LineChip(label, AnsiFailChip, $"{(fr.Outcome == Outcome.Error ? " " : "  ")}{rel}  ({fr.ElapsedMs}ms)");
+                _out.LineChip(label, AnsiFail, $"{(fr.Outcome == Outcome.Error ? " " : "  ")}{rel}  ({fr.ElapsedMs}ms)");
                 foreach (var a in fr.Assertions)
                 {
                     if (a.Outcome == Outcome.Pass)
@@ -1151,8 +1152,8 @@ private void ReportConsole(List<FileResult> results)
                     }
                     var locFile = a.SourceFile is null ? rel : Path.GetRelativePath(Environment.CurrentDirectory, a.SourceFile);
                     var loc = a.Line is null ? "" : $"  [{locFile}:{a.Line}]";
-                    _out.LineAnsi($"        ✗ {a.Name}{loc}", AnsiFail);
-                    if (!string.IsNullOrWhiteSpace(a.Message) && a.Message != a.Name) _out.LineAnsi($"          {a.Message}", AnsiFail);
+                    _out.LineChip("        ", AnsiPlain, $"✗ {a.Name}{loc}", AnsiFail);
+                    if (!string.IsNullOrWhiteSpace(a.Message) && a.Message != a.Name) _out.LineChip("          ", AnsiPlain, a.Message, AnsiFail);
                     WriteFailingSql(a.Sql);
                 }
             }
@@ -1161,9 +1162,9 @@ private void ReportConsole(List<FileResult> results)
                 foreach (var n in fr.Notices) _out.Line($"        notice: {n}", ConsoleColor.DarkGray);
         }
 
-        var summary = $"\n{passed} passed, {failed} failed, {errored} error(s)  —  {totalAssertions} assertion{(totalAssertions == 1 ? "" : "s")} in {results.Count} file{(results.Count == 1 ? "" : "s")}";
-        if (failed + errored == 0) _out.LineAnsi(summary, AnsiOk);
-        else _out.LineAnsi(summary, AnsiFail);
+        var summary = $"{passed} passed, {failed} failed, {errored} error(s)  —  {totalAssertions} assertion{(totalAssertions == 1 ? "" : "s")} in {results.Count} file{(results.Count == 1 ? "" : "s")}";
+        _out.NL();
+        _out.LineAnsi(summary, failed + errored == 0 ? AnsiOk : AnsiFail);
     }
 
     private static void WriteJUnit(List<FileResult> results, string path)

From 19ecbaed873740a1fb26814539748945561fba3d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Thu, 2 Jul 2026 20:39:21 +0200
Subject: [PATCH 18/25] feat(test-runner): endpoint coverage on by default for
 full runs (tri-state)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

TestRunner.Coverage is now tri-state:
- null (the new default): report the endpoint-coverage summary after FULL
  runs — it costs one line and surfaces untested endpoints passively — but
  stay quiet when the run is narrowed by Filter/Tag (a deliberately partial
  run would just nag about endpoints its subset never touches);
- true: always report, including narrowed runs;
- false: never report.
CoverageThreshold always reports and gates when set, regardless of Coverage
or narrowing — it is an explicit ask for enforcement.

Config synced (appsettings.json, ConfigTemplate.cs, ConfigDefaults.cs,
ConfigSchemaGenerator.cs — incl. previously missing schema descriptions for
Coverage/CoverageThreshold). Changelog updated. Full suite green (2364);
all five behaviors verified live (default-on full run, narrowed suppression,
forced on, forced off, threshold reporting).
---
 NpgsqlRestClient/Builder.cs                   |  6 +++++-
 NpgsqlRestClient/ConfigDefaults.cs            |  2 +-
 NpgsqlRestClient/ConfigSchemaGenerator.cs     |  2 ++
 NpgsqlRestClient/ConfigTemplate.cs            |  8 +++++---
 NpgsqlRestClient/Testing/TestRunner.cs        |  9 ++++++++-
 NpgsqlRestClient/Testing/TestRunnerOptions.cs | 11 +++++++----
 NpgsqlRestClient/appsettings.json             |  8 +++++---
 changelog/v3.19.0.md                          |  8 ++++----
 8 files changed, 37 insertions(+), 17 deletions(-)

diff --git a/NpgsqlRestClient/Builder.cs b/NpgsqlRestClient/Builder.cs
index 74b4c395..a2590046 100644
--- a/NpgsqlRestClient/Builder.cs
+++ b/NpgsqlRestClient/Builder.cs
@@ -3081,7 +3081,11 @@ public TestRunnerOptions BuildTestRunnerOptions()
         opt.AllowEmpty = _config.GetConfigBool("AllowEmpty", section, false);
         opt.Watch = _config.GetConfigBool("Watch", section, false);
         opt.CoverageThreshold = _config.GetConfigInt("CoverageThreshold", section);
-        opt.Coverage = _config.GetConfigBool("Coverage", section, false) || opt.CoverageThreshold is not null;
+        // Tri-state: absent/empty => null (report after full runs only); explicit true/false honored.
+        if (string.IsNullOrEmpty(section.GetSection("Coverage").Value) is false)
+        {
+            opt.Coverage = _config.GetConfigBool("Coverage", section, false);
+        }
 
         var rt = section.GetSection("ResponseTempTable");
         if (rt.Exists())
diff --git a/NpgsqlRestClient/ConfigDefaults.cs b/NpgsqlRestClient/ConfigDefaults.cs
index 57439532..8ccc6117 100644
--- a/NpgsqlRestClient/ConfigDefaults.cs
+++ b/NpgsqlRestClient/ConfigDefaults.cs
@@ -1113,7 +1113,7 @@ private static JsonObject GetTestRunnerDefaults()
             ["DetailedReport"] = false,
             ["AllowEmpty"] = false,
             ["Watch"] = false,
-            ["Coverage"] = false,
+            ["Coverage"] = null,
             ["CoverageThreshold"] = null,
             ["LoggerName"] = "NpgsqlRestTest",
             ["ResponseTempTable"] = new JsonObject
diff --git a/NpgsqlRestClient/ConfigSchemaGenerator.cs b/NpgsqlRestClient/ConfigSchemaGenerator.cs
index 512469ab..163cccdb 100644
--- a/NpgsqlRestClient/ConfigSchemaGenerator.cs
+++ b/NpgsqlRestClient/ConfigSchemaGenerator.cs
@@ -260,6 +260,8 @@ public static partial class ConfigSchemaGenerator
         ["TestRunner:DetailedReport"] = "Detailed console REPORT: list passed assertions, print the full failing SQL statement, and show captured `raise notice` output for passing tests too.\nThis shapes the report only — for diagnostic logging of every executed query/HTTP call, raise the log channel instead (Log:MinimalLevels + LoggerName).",
         ["TestRunner:AllowEmpty"] = "Treat \"no tests discovered\" as success (exit 0) instead of exit 4.",
         ["TestRunner:Watch"] = "Watch mode (interactive/dev-only; CLI flag: --watch): run everything once, then re-run on file changes until Ctrl+C.\nA changed test file re-runs alone; a changed ENDPOINT file (SqlFileSource FilePattern) rebuilds the endpoints in-process (delta reported; ErrorMode forced Exit->Skip so a broken file cannot kill the session) and re-runs everything; any other changed .sql under the test tree (e.g. an included fixture) re-runs everything. Teardown runs once, on exit; a graceful stop exits 0 (not for CI gating).",
+        ["TestRunner:Coverage"] = "Endpoint-coverage summary after the run: exercised N of M testable endpoints + the list of untested ones (endpoint kinds the runner rejects — SSE, upload, login/logout, outbound proxy — are excluded from the ratio and counted separately).\nTri-state: null (default) reports after FULL runs but stays quiet when the run is narrowed by Filter/Tag; true always reports; false never.",
+        ["TestRunner:CoverageThreshold"] = "Fail an otherwise-passing run with exit 2 when endpoint coverage is below this percentage (0-100) — CI gating for \"every endpoint has a test\". Always reports coverage when set, regardless of the Coverage setting or run narrowing. Null = no gate.",
         ["TestRunner:LoggerName"] = "SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels (defaults to Information).\nDiscovery/parsing log at Debug, each query and HTTP invocation at Verbose, `raise notice` by severity. The console PASS/FAIL report is separate.",
         ["TestRunner:ResponseTempTable:Name"] = "Temp table name used when a test file has exactly ONE HTTP block.\nEach HTTP block gets its own fresh temp table (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified. Per-block override: `# @response <name>`.",
         ["TestRunner:ResponseTempTable:MultiNamePattern"] = "Temp table name pattern used when a test file has 2+ HTTP blocks.\n{n} is the 1-based block ordinal, e.g. \"_response_{n}\" => _response_1, _response_2, …",
diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index 523c6848..4ec7f671 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -1513,10 +1513,12 @@ public static partial class ConfigSchemaGenerator
         //
         // Endpoint-coverage summary after the run: exercised N of M testable endpoints + the list of untested
         // ones (endpoint kinds the runner rejects — SSE, upload, login/logout, outbound proxy — are excluded
-        // from the ratio and counted separately). CoverageThreshold (0-100, implies Coverage) fails an
-        // otherwise-passing run with exit 2 when coverage is below it — CI gating for "every endpoint has a test".
+        // from the ratio and counted separately). Tri-state: null (default) reports after FULL runs but stays
+        // quiet when the run is narrowed by Filter/Tag (a deliberately partial run would just nag); true always
+        // reports; false never. CoverageThreshold (0-100) always reports and fails an otherwise-passing run
+        // with exit 2 when coverage is below it — CI gating for "every endpoint has a test".
         //
-        "Coverage": false,
+        "Coverage": null,
         "CoverageThreshold": null,
         //
         // SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels.
diff --git a/NpgsqlRestClient/Testing/TestRunner.cs b/NpgsqlRestClient/Testing/TestRunner.cs
index 9388c0f8..0c56c075 100644
--- a/NpgsqlRestClient/Testing/TestRunner.cs
+++ b/NpgsqlRestClient/Testing/TestRunner.cs
@@ -318,7 +318,14 @@ await Parallel.ForEachAsync(
         int exit = ordered.Any(r => r.Outcome == Outcome.Error) ? ExitErrors
             : ordered.Any(r => r.Outcome == Outcome.Fail) ? ExitFailures
             : ExitPass;
-        if (_opt.Coverage && only is null)
+        // Coverage reports on complete runs (never on watch partial reruns). Default (Coverage=null):
+        // report unless the run was narrowed by Filter/Tag — a deliberately partial run would just nag
+        // about endpoints its subset never touches. Coverage=true always reports, false never; a set
+        // CoverageThreshold always reports (and gates) — that's an explicit ask for enforcement.
+        bool narrowed = !string.IsNullOrWhiteSpace(_opt.Filter) || _opt.Tags.Count > 0 || _opt.ExcludeTags.Count > 0;
+        bool showCoverage = only is null
+            && (_opt.CoverageThreshold is not null || _opt.Coverage == true || (_opt.Coverage is null && !narrowed));
+        if (showCoverage)
         {
             exit = ReportCoverage(endpoints, exit);
         }
diff --git a/NpgsqlRestClient/Testing/TestRunnerOptions.cs b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
index 5b0ebb6a..014dbd3f 100644
--- a/NpgsqlRestClient/Testing/TestRunnerOptions.cs
+++ b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
@@ -24,11 +24,14 @@ public class TestRunnerOptions
     public List<string> ExcludeTags { get; set; } = [];
 
     /// <summary>
-    /// Emit an endpoint-coverage summary after the run: exercised N of M testable endpoints plus the list
-    /// of untested ones. Endpoint kinds the runner rejects (SSE, upload, login/logout, outbound proxy) are
-    /// excluded from the ratio and reported separately.
+    /// Endpoint-coverage summary after the run: exercised N of M testable endpoints plus the list of
+    /// untested ones. Endpoint kinds the runner rejects (SSE, upload, login/logout, outbound proxy) are
+    /// excluded from the ratio and reported separately. Tri-state: null (default) = report after FULL runs
+    /// but stay quiet when the run is narrowed by <see cref="Filter"/>/<see cref="Tags"/> (a deliberately
+    /// partial run would just nag); true = always report; false = never. A set
+    /// <see cref="CoverageThreshold"/> always reports and gates.
     /// </summary>
-    public bool Coverage { get; set; } = false;
+    public bool? Coverage { get; set; } = null;
 
     /// <summary>
     /// Fail an otherwise-passing run (exit 2) when endpoint coverage is below this percentage (0-100), for
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index 822646c8..5a8cccba 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -1504,10 +1504,12 @@
     //
     // Endpoint-coverage summary after the run: exercised N of M testable endpoints + the list of untested
     // ones (endpoint kinds the runner rejects — SSE, upload, login/logout, outbound proxy — are excluded
-    // from the ratio and counted separately). CoverageThreshold (0-100, implies Coverage) fails an
-    // otherwise-passing run with exit 2 when coverage is below it — CI gating for "every endpoint has a test".
+    // from the ratio and counted separately). Tri-state: null (default) reports after FULL runs but stays
+    // quiet when the run is narrowed by Filter/Tag (a deliberately partial run would just nag); true always
+    // reports; false never. CoverageThreshold (0-100) always reports and fails an otherwise-passing run
+    // with exit 2 when coverage is below it — CI gating for "every endpoint has a test".
     //
-    "Coverage": false,
+    "Coverage": null,
     "CoverageThreshold": null,
     //
     // SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels.
diff --git a/changelog/v3.19.0.md b/changelog/v3.19.0.md
index c366b271..2d703fc1 100644
--- a/changelog/v3.19.0.md
+++ b/changelog/v3.19.0.md
@@ -273,8 +273,8 @@ The runner logs through its own channel — **`NpgsqlRestTest`** (configurable v
   "DetailedReport": false,              // detailed console report: passed ✓ lines, full failing SQL, notices for passing tests
   "AllowEmpty": false,                  // exit 0 instead of 4 when no tests are found
   "Watch": false,                       // watch mode (CLI: --watch): re-run on file changes until Ctrl+C; teardown on exit
-  "Coverage": false,                    // endpoint-coverage summary: exercised N/M testable + the untested list
-  "CoverageThreshold": null,            // 0-100 (implies Coverage): fail an otherwise-passing run (exit 2) below it
+  "Coverage": null,                     // coverage summary: null (default) = on for full runs, quiet when narrowed; true/false = always/never
+  "CoverageThreshold": null,            // 0-100: always report + fail an otherwise-passing run (exit 2) below it
   "LoggerName": "NpgsqlRestTest",       // the runner's log channel (leveled via Log:MinimalLevels)
   "ResponseTempTable": {
     "Name": "_response",                // table name when a file has ONE HTTP block
@@ -312,7 +312,7 @@ npgsqlrest ... --test --testrunner:tag=smoke --testrunner:excludetag=slow
 
 Since includes behave as if pasted, tags travel through a **shared profile** too: a profile file carrying `-- @tag isolation, slow` next to its `-- @setup`/`-- @connection` annotations tags *every test that attaches it* — e.g. all clone-isolated tests are automatically `slow`, so the everyday dev loop is just `--testrunner:excludetag=slow`, with zero per-file bookkeeping.
 
-**Endpoint coverage** (`Coverage: true`, or just set a threshold) is something only an integrated runner can offer: the runner knows the **entire API surface** it built *and* records every endpoint the tests actually invoked, so after the run it reports the API-level analogue of code coverage — including the exact endpoints no test touches:
+**Endpoint coverage** is something only an integrated runner can offer: the runner knows the **entire API surface** it built *and* records every endpoint the tests actually invoked, so after the run it reports the API-level analogue of code coverage — including the exact endpoints no test touches. It is **on by default for full runs** (it costs one line); a run narrowed by `Filter`/`Tag` stays quiet — a deliberately partial run would just nag — unless `Coverage: true` forces it, and `Coverage: false` silences it entirely:
 
 ```
 19 passed, 0 failed, 0 error(s)  —  19 assertions in 9 files
@@ -321,7 +321,7 @@ endpoint coverage: 1/2 (50%)
         untested: GET /api/get-users
 ```
 
-Endpoint kinds the runner rejects (SSE, upload, login/logout, outbound proxy) are excluded from the ratio and counted separately, so the number is honest. **`CoverageThreshold`** (0–100, implies `Coverage`) turns it into a CI gate: an otherwise-passing run below the threshold exits `2` — set it to `100` and forgetting to write a test for a new endpoint fails the build, naming the endpoint. "Covered" means *invoked at least once by a test* — execution, not assertion depth (the same semantics as code coverage).
+Endpoint kinds the runner rejects (SSE, upload, login/logout, outbound proxy) are excluded from the ratio and counted separately, so the number is honest. **`CoverageThreshold`** (0–100) turns it into a CI gate — it always reports, regardless of the `Coverage` setting or run narrowing: an otherwise-passing run below the threshold exits `2` — set it to `100` and forgetting to write a test for a new endpoint fails the build, naming the endpoint. "Covered" means *invoked at least once by a test* — execution, not assertion depth (the same semantics as code coverage).
 
 **Watch mode** (`--watch`, or `TestRunner:Watch`) keeps the process alive and re-runs on change — and because the endpoint middleware is built once at startup, re-runs are near-instant:
 

From 6cd715090508a4b2dca923ad8970b3d042b8e18b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Thu, 2 Jul 2026 22:06:52 +0200
Subject: [PATCH 19/25] feat(sql-file-source): named parameters (:name) in SQL
 files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SQL file endpoints can use named placeholders instead of positional $1..$N:

    select * from users where email = :email and age > :age;

The placeholder IS the parameter: :email becomes API parameter "email"
through the same NameConverter routine parameters use (:user_id -> userId),
so @param annotations that existed only to NAME positional parameters become
unnecessary. Claim mappings (ParameterNameClaimsMapping, @user_parameters)
hook up by the placeholder's own name with zero annotations.

Mechanics: statements are rewritten to native $N right after parsing —
PostgreSQL never sees :name, so Describe, type inference, and runtime
behavior are identical to positional files. The same name (case-insensitive,
first spelling wins) maps to ONE parameter file-wide, including across
statements in multi-command files. Token-aware rewriter: strings ('', ""),
comments (nested /* */), and dollar-quoted bodies untouched; :: casts, :=
calls, and numeric slice bounds (a[1:3]) never match (variable slice bounds
need a space: a[1 : n]). Mixing $N and :name in one file is rejected
(ErrorMode semantics).

Annotations match named parameters by name: `@param email default null`
works as-is; `@param :email citext` is a Describe type hint; the new
`@param email type is citext` form retypes WITHOUT rename (core
ParameterHandler, delegates to the rename path as rename-to-same-name;
also tolerates a leading ':' on the parameter reference). Typed-annotation
detection for HTTP-client/composite types accepts the named form.

`?` (JDBC style) considered and rejected: ?, ?|, ?& and @? are PostgreSQL's
own jsonb/geometric operators — no rewriter can safely claim `?`; same
reason the PG JDBC driver requires ?? escapes. Documented in the changelog.

Tests: 22 rewriter unit tests + 7 end-to-end endpoint tests (auto-naming,
repeated placeholder from one value, required-param matching, name-matched
defaults, `type is` retype producing an unquoted JSON int, claim mapping by
placeholder name, mixed-style rejection, multi-command cross-statement
sharing). Full suite green (2393). Example 20's login.sql converted to
:email/:password live (docs repo, committed separately). Changelog section
+ plugin README updated.
---
 .../CommentParsers/ParameterHandler.cs        |  22 ++
 .../NamedParamEndpointTests.cs                | 127 +++++++++
 .../ParserTests/NamedParamRewriteTests.cs     | 192 +++++++++++++
 changelog/v3.19.0.md                          |  34 ++-
 plugins/NpgsqlRest.SqlFileSource/README.md    |  12 +-
 .../NpgsqlRest.SqlFileSource/SqlFileParser.cs | 268 ++++++++++++++++--
 .../NpgsqlRest.SqlFileSource/SqlFileSource.cs |  83 ++++--
 7 files changed, 696 insertions(+), 42 deletions(-)
 create mode 100644 NpgsqlRestTests/SqlFileSourceTests/AdvancedFeatureTests/NamedParamEndpointTests.cs
 create mode 100644 NpgsqlRestTests/SqlFileSourceTests/ParserTests/NamedParamRewriteTests.cs

diff --git a/NpgsqlRest/Defaults/CommentParsers/ParameterHandler.cs b/NpgsqlRest/Defaults/CommentParsers/ParameterHandler.cs
index 9a35b28b..8cfc299d 100644
--- a/NpgsqlRest/Defaults/CommentParsers/ParameterHandler.cs
+++ b/NpgsqlRest/Defaults/CommentParsers/ParameterHandler.cs
@@ -36,6 +36,14 @@ private static void HandleParameter(
         int len,
         string description)
     {
+        // Tolerate the :name placeholder spelling from named-parameter SQL files: "@param :email ..."
+        // targets the parameter whose ActualName is "email".
+        if (len >= 2 && words[1].Length > 1 && words[1][0] == ':')
+        {
+            words[1] = words[1][1..];
+            wordsLower[1] = wordsLower[1][1..];
+        }
+
         // param param_name1 is hash of param_name2
         if (len >= 6 && StrEquals(wordsLower[2], "is") && StrEquals(wordsLower[3], "hash") && StrEquals(wordsLower[4], "of"))
         {
@@ -128,6 +136,20 @@ private static void HandleParameter(
             return;
         }
 
+        // param [name] type is [type] [default ...] — retype (and optionally default) WITHOUT rename.
+        // Useful for named-placeholder (:name) SQL file parameters, where the name comes from the
+        // placeholder and only the type needs overriding. Delegated to the rename path as a
+        // rename-to-same-name: [param, X, type, is, Y, ...] → [param, X, is, X, Y, ...].
+        if (len >= 5 && StrEquals(wordsLower[2], "type") && StrEquals(wordsLower[3], "is"))
+        {
+            var w = (string[])words.Clone();
+            var wl = (string[])wordsLower.Clone();
+            w[2] = "is"; wl[2] = "is";
+            w[3] = words[1]; wl[3] = wordsLower[1];
+            HandleParameterRename(routine, wl, w, len, description);
+            return;
+        }
+
         // Rename / retype forms:
         // param [original] is [new_name]                     — len >= 4, wordsLower[2] == "is"
         // param [original] is [new_name] [type]              — len >= 5, wordsLower[2] == "is"
diff --git a/NpgsqlRestTests/SqlFileSourceTests/AdvancedFeatureTests/NamedParamEndpointTests.cs b/NpgsqlRestTests/SqlFileSourceTests/AdvancedFeatureTests/NamedParamEndpointTests.cs
new file mode 100644
index 00000000..839ba325
--- /dev/null
+++ b/NpgsqlRestTests/SqlFileSourceTests/AdvancedFeatureTests/NamedParamEndpointTests.cs
@@ -0,0 +1,127 @@
+namespace NpgsqlRestTests.SqlFileSourceTests;
+
+public static partial class SqlFiles
+{
+    public static void NamedParamEndpointTests()
+    {
+        // Named placeholders: API names come from the placeholders (through the camelCase NameConverter),
+        // no @param annotations needed; a repeated name maps to the SAME parameter.
+        File.WriteAllText(Path.Combine(Dir, "named_echo.sql"), """
+            /*
+            HTTP GET
+            */
+            select :first_name || ' ' || :last_name || ' (' || :first_name || ')' as greeting;
+            """);
+
+        // Optional named parameter via the existing name-matching default annotation.
+        File.WriteAllText(Path.Combine(Dir, "named_default.sql"), """
+            -- @param label default null
+            select coalesce(:label, 'none') as v;
+            """);
+
+        // Retype WITHOUT rename via the new `type is` form (both the Describe hint and endpoint retype).
+        File.WriteAllText(Path.Combine(Dir, "named_type_is.sql"), """
+            -- @param val type is int
+            select :val as v;
+            """);
+
+        // Claim-mapped user parameter — the placeholder name itself (_user_id) matches
+        // ParameterNameClaimsMapping, so the claim hookup needs no annotation at all.
+        File.WriteAllText(Path.Combine(Dir, "named_user_param.sql"), """
+            -- @authorize
+            -- @user_parameters
+            select :_user_id as user_id;
+            """);
+
+        // Mixing positional and named placeholders is rejected (ErrorMode=Skip → no endpoint).
+        File.WriteAllText(Path.Combine(Dir, "named_mixed_invalid.sql"), """
+            select $1 as a, :b as b;
+            """);
+
+        // Multi-command file: :id is shared ACROSS statements (one API parameter), :offset appears
+        // only in the second statement — still no annotations needed.
+        File.WriteAllText(Path.Combine(Dir, "named_multi.sql"), """
+            -- HTTP POST
+            -- @result first
+            select :id::int as v;
+            -- @result second
+            select :id::int + :offset::int as v;
+            """);
+    }
+}
+
+[Collection("SqlFileSourceFixture")]
+public class NamedParamEndpointTests(SqlFileSourceTestFixture test)
+{
+    [Fact]
+    public async Task NamedParams_AutoNamed_CamelCased_And_RepeatedNameShared()
+    {
+        using var response = await test.Client.GetAsync("/api/named-echo?firstName=Ada&lastName=Lovelace");
+        var content = await response.Content.ReadAsStringAsync();
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+        content.Should().Be("[\"Ada Lovelace (Ada)\"]");
+    }
+
+    [Fact]
+    public async Task NamedParams_MissingRequiredParam_NotFound()
+    {
+        // lastName missing → endpoint parameter set doesn't match → 404
+        using var response = await test.Client.GetAsync("/api/named-echo?firstName=Ada");
+        response.StatusCode.Should().Be(HttpStatusCode.NotFound);
+    }
+
+    [Fact]
+    public async Task NamedParams_DefaultAnnotation_MatchesByPlaceholderName()
+    {
+        using var response = await test.Client.GetAsync("/api/named-default");
+        var content = await response.Content.ReadAsStringAsync();
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+        content.Should().Be("[\"none\"]");
+
+        using var response2 = await test.Client.GetAsync("/api/named-default?label=tagged");
+        var content2 = await response2.Content.ReadAsStringAsync();
+        response2.StatusCode.Should().Be(HttpStatusCode.OK);
+        content2.Should().Be("[\"tagged\"]");
+    }
+
+    [Fact]
+    public async Task NamedParams_TypeIsForm_RetypesWithoutRename()
+    {
+        using var response = await test.Client.GetAsync("/api/named-type-is?val=7");
+        var content = await response.Content.ReadAsStringAsync();
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+        // int type → rendered unquoted in JSON
+        content.Should().Be("[7]");
+    }
+
+    [Fact]
+    public async Task NamedParams_ClaimMappedByPlaceholderName_NoAnnotationNeeded()
+    {
+        using var client = test.CreateClient();
+        await client.GetAsync("/login");
+
+        using var response = await client.GetAsync("/api/named-user-param");
+        var content = await response.Content.ReadAsStringAsync();
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+        // name_identifier claim = "user123"
+        content.Should().Be("[\"user123\"]");
+    }
+
+    [Fact]
+    public async Task MixedPositionalAndNamed_FileSkipped_NoEndpoint()
+    {
+        using var response = await test.Client.GetAsync("/api/named-mixed-invalid?a=1&b=2");
+        response.StatusCode.Should().Be(HttpStatusCode.NotFound);
+    }
+
+    [Fact]
+    public async Task NamedParams_SharedAcrossStatements_OneApiParameter()
+    {
+        using var body = new StringContent("{\"id\": 10, \"offset\": 5}", Encoding.UTF8, "application/json");
+        using var response = await test.Client.PostAsync("/api/named-multi", body);
+        var content = await response.Content.ReadAsStringAsync();
+        response.StatusCode.Should().Be(HttpStatusCode.OK, $"Response: {content}");
+        // one `id` value feeds both statements; `offset` only the second
+        content.Should().Be("""{"first":[10],"second":[15]}""");
+    }
+}
diff --git a/NpgsqlRestTests/SqlFileSourceTests/ParserTests/NamedParamRewriteTests.cs b/NpgsqlRestTests/SqlFileSourceTests/ParserTests/NamedParamRewriteTests.cs
new file mode 100644
index 00000000..4a6eeaa1
--- /dev/null
+++ b/NpgsqlRestTests/SqlFileSourceTests/ParserTests/NamedParamRewriteTests.cs
@@ -0,0 +1,192 @@
+using NpgsqlRest.SqlFileSource;
+
+namespace NpgsqlRestTests.SqlFileSourceTests;
+
+public class NamedParamRewriteTests
+{
+    private static (List<string> Statements, NamedParamRewriteResult Result) Rewrite(string sql)
+    {
+        var parsed = SqlFileParser.Parse(sql);
+        var result = SqlFileParser.RewriteNamedParameters(parsed.Statements);
+        return (parsed.Statements, result);
+    }
+
+    [Fact]
+    public void SingleNamedParam_RewrittenToPositional()
+    {
+        var (statements, result) = Rewrite("select * from users where id = :id");
+        statements[0].Should().Be("select * from users where id = $1");
+        result.Names.Should().Equal("id");
+        result.HasNamed.Should().BeTrue();
+        result.HasPositional.Should().BeFalse();
+    }
+
+    [Fact]
+    public void MultipleNamedParams_OrdinalsInFirstAppearanceOrder()
+    {
+        var (statements, result) = Rewrite("select :b, :a, :c");
+        statements[0].Should().Be("select $1, $2, $3");
+        result.Names.Should().Equal("b", "a", "c");
+    }
+
+    [Fact]
+    public void RepeatedName_MapsToSameOrdinal()
+    {
+        var (statements, result) = Rewrite("select :id where :id > 0 and :other < :id");
+        statements[0].Should().Be("select $1 where $1 > 0 and $2 < $1");
+        result.Names.Should().Equal("id", "other");
+    }
+
+    [Fact]
+    public void RepeatedName_CaseInsensitive_KeepsFirstSpelling()
+    {
+        var (statements, result) = Rewrite("select :UserId, :userid");
+        statements[0].Should().Be("select $1, $1");
+        result.Names.Should().Equal("UserId");
+    }
+
+    [Fact]
+    public void SameName_AcrossStatements_SharesParameter()
+    {
+        var (statements, result) = Rewrite("select :id;\nupdate t set x = :val where id = :id;");
+        statements[0].Should().Be("select $1");
+        statements[1].Should().Contain("set x = $2 where id = $1");
+        result.Names.Should().Equal("id", "val");
+    }
+
+    [Fact]
+    public void DoubleColonCast_NotAParameter()
+    {
+        var (statements, result) = Rewrite("select '1'::int, :id::text");
+        statements[0].Should().Be("select '1'::int, $1::text");
+        result.Names.Should().Equal("id");
+    }
+
+    [Fact]
+    public void CastOnly_NoNamedParams()
+    {
+        var (statements, result) = Rewrite("select a::int, b::text from t");
+        statements[0].Should().Be("select a::int, b::text from t");
+        result.HasNamed.Should().BeFalse();
+    }
+
+    [Fact]
+    public void ColonEquals_NotAParameter()
+    {
+        var (statements, result) = Rewrite("select f(a := 1)");
+        statements[0].Should().Be("select f(a := 1)");
+        result.HasNamed.Should().BeFalse();
+    }
+
+    [Fact]
+    public void NumericSliceBound_NotAParameter()
+    {
+        var (statements, result) = Rewrite("select arr[1:3] from t");
+        statements[0].Should().Be("select arr[1:3] from t");
+        result.HasNamed.Should().BeFalse();
+    }
+
+    [Fact]
+    public void InsideSingleQuotedString_Untouched()
+    {
+        var (statements, result) = Rewrite("select ':notaparam', :real");
+        statements[0].Should().Be("select ':notaparam', $1");
+        result.Names.Should().Equal("real");
+    }
+
+    [Fact]
+    public void InsideEscapedQuotes_Untouched()
+    {
+        var (statements, result) = Rewrite("select 'it''s :x here', :y");
+        statements[0].Should().Be("select 'it''s :x here', $1");
+        result.Names.Should().Equal("y");
+    }
+
+    [Fact]
+    public void InsideDoubleQuotedIdentifier_Untouched()
+    {
+        var (statements, result) = Rewrite("select \"a:b\" from t where c = :c");
+        statements[0].Should().Be("select \"a:b\" from t where c = $1");
+        result.Names.Should().Equal("c");
+    }
+
+    [Fact]
+    public void InsideDollarQuote_Untouched()
+    {
+        var (statements, result) = Rewrite("do $$ begin perform :x; end $$;");
+        statements[0].Should().Contain("perform :x;");
+        result.HasNamed.Should().BeFalse();
+    }
+
+    [Fact]
+    public void InsideTaggedDollarQuote_Untouched()
+    {
+        var (statements, result) = Rewrite("select $tag$ :x $tag$, :y");
+        statements[0].Should().Be("select $tag$ :x $tag$, $1");
+        result.Names.Should().Equal("y");
+    }
+
+    [Fact]
+    public void PositionalParams_Detected_NotRewritten()
+    {
+        var (statements, result) = Rewrite("select * from t where a = $1 and b = $2");
+        statements[0].Should().Be("select * from t where a = $1 and b = $2");
+        result.HasPositional.Should().BeTrue();
+        result.HasNamed.Should().BeFalse();
+    }
+
+    [Fact]
+    public void MixedStyles_BothFlagsSet()
+    {
+        var (_, result) = Rewrite("select $1, :id");
+        result.HasPositional.Should().BeTrue();
+        result.HasNamed.Should().BeTrue();
+    }
+
+    [Fact]
+    public void UnderscoreName_Recognized()
+    {
+        var (statements, result) = Rewrite("select :_user_id");
+        statements[0].Should().Be("select $1");
+        result.Names.Should().Equal("_user_id");
+    }
+
+    [Fact]
+    public void JsonbPathOperators_ColonInsideString_Untouched()
+    {
+        var (statements, result) = Rewrite("select data @? '$.a ? (@ > :x)' from t where id = :id");
+        statements[0].Should().Be("select data @? '$.a ? (@ > :x)' from t where id = $1");
+        result.Names.Should().Equal("id");
+    }
+
+    [Fact]
+    public void TypeHints_NamedColonForm_ResolvedByName()
+    {
+        var hints = SqlFileParser.ExtractParamTypeHints("param :user_id integer", ["email", "user_id"]);
+        hints.Should().NotBeNull();
+        hints![1].Should().Be("integer");
+    }
+
+    [Fact]
+    public void TypeHints_TypeIsForm_ResolvedByName()
+    {
+        var hints = SqlFileParser.ExtractParamTypeHints("param user_id type is integer", ["user_id"]);
+        hints.Should().NotBeNull();
+        hints![0].Should().Be("integer");
+    }
+
+    [Fact]
+    public void TypeHints_UnknownName_Ignored()
+    {
+        var hints = SqlFileParser.ExtractParamTypeHints("param :nope integer", ["user_id"]);
+        hints.Should().BeNull();
+    }
+
+    [Fact]
+    public void TypeHints_PositionalForm_StillWorks()
+    {
+        var hints = SqlFileParser.ExtractParamTypeHints("param $1 name integer");
+        hints.Should().NotBeNull();
+        hints![0].Should().Be("integer");
+    }
+}
diff --git a/changelog/v3.19.0.md b/changelog/v3.19.0.md
index 2d703fc1..0e4a24d1 100644
--- a/changelog/v3.19.0.md
+++ b/changelog/v3.19.0.md
@@ -354,7 +354,37 @@ This is what makes the co-located test layout safe: without it, a test file's `/
 
 > **Behavior change:** the default is `"*.test.sql"`, so files matching that suffix are **no longer exposed** as endpoints out of the box. If you previously relied on serving `*.test.sql` files, set `SkipPattern` to `""` to restore the old behavior.
 
-## 3. Mute an individual logger with `"Off"` in `Log:MinimalLevels`
+## 3. Named parameters in SQL files: `:name`
+
+SQL file endpoints can now use **named placeholders** instead of the positional `$1, $2, …`:
+
+```sql
+/*
+HTTP POST
+@allow_anonymous
+@single
+*/
+select u.id, u.email, u.full_name as name, r.name as role
+from users u
+join roles r on r.id = u.role_id
+where u.email = :email
+  and u.password_hash = crypt(:password, u.password_hash);
+```
+
+The placeholder **is** the parameter name: `:email` becomes the API parameter `email` (through the same `NameConverter` routine parameters use, so `:user_id` → `userId` with the default camelCase converter). The `@param $1 email text`-style annotations that existed only to *name* positional parameters are simply unnecessary — the file above needs none. Under the hood the SQL is rewritten to native `$N` before it is described and executed; PostgreSQL never sees the `:name` form, so type inference, `Describe`, and runtime behavior are identical to positional files.
+
+What you get:
+
+- **Repetition collapses**: the same name used multiple times — including **across statements** in a multi-command file — is **one** parameter (`where :user_id = author_id or :user_id = editor_id` takes a single `userId` value).
+- **Claim mappings hook up by placeholder name**: `select :_user_id` under `@authorize` + `@user_parameters` binds the mapped claim with **zero** `@param` annotations.
+- **Annotations match by name** where you still need them: `@param email default null` (defaults), `@param :email citext` (a Describe type hint), and the new **retype-without-rename** form `@param email type is citext` — renaming a parameter whose name came from its own placeholder would be nonsense, so `type is` changes only the type. All positional `@param $N …` forms keep working unchanged.
+- **The tokenizer knows SQL**: strings (`'…'`, `"…"`, dollar-quoted bodies) and comments are untouched; `::int` casts, `:=` named-argument calls, and numeric slice bounds (`a[1:3]`) never match. A placeholder requires an identifier character immediately after the colon — the one caveat is an array slice with a *variable* bound, which must be written with a space (`a[1 : n]`).
+
+**One style per file**: mixing `$N` and `:name` in the same file makes the ordinal assignment ambiguous and is rejected (logged; the file is skipped under `ErrorMode: Skip`, or exits under `Exit`).
+
+**Why not `?` (JDBC style)?** Considered and rejected: `?`, `?|`, `?&`, and `@?` are PostgreSQL's own jsonb/geometric operators — `where data ? 'admin'` is legal, common SQL that no rewriter can reliably tell apart from a parameter. This is the same reason the PostgreSQL JDBC driver requires `??` escapes. Anonymous-positional already exists as `$N`.
+
+## 4. Mute an individual logger with `"Off"` in `Log:MinimalLevels`
 
 Each entry under **`Log:MinimalLevels`** now accepts **`"Off"`** (aliases **`"None"`** and **`"Silent"`**, case-insensitive) to **fully silence** that logger. Previously the only accepted values were the Serilog levels `Verbose…Fatal`, and there was no way to turn a logger off completely.
 
@@ -382,4 +412,4 @@ Each named logger is controlled independently — e.g. mute the application logg
 
 ## Tests
 
-Full test suite green (2364), including 63 unit tests for the test-file, HTTP-block, header-annotation, and include parsers plus the filter and tag matchers (`NpgsqlRestTests/TestRunnerTests/ParserTests/`). All three documentation examples verified end-to-end against live PostgreSQL — including example 21's template-clone workflow (template migrated once; the shared run database and **two parallel per-test isolated databases** cloned from it concurrently; deterministic sequence ids asserted independently in both clones; everything dropped on teardown), watch mode (single-file rerun on a test change, full rerun on a fixture change, teardown on SIGINT/SIGTERM), path and tag filtering (including tags carried through a profile include), and the coverage report with a failing threshold gate. The new configuration keys are covered by the configuration round-trip tests (the `--config` template output matches `appsettings.json`).
+Full test suite green (2393), including 63 unit tests for the test-file, HTTP-block, header-annotation, and include parsers plus the filter and tag matchers (`NpgsqlRestTests/TestRunnerTests/ParserTests/`), and 29 for named SQL-file parameters — 22 rewriter unit tests (casts, `:=`, slices, strings, dollar-quotes, jsonb-path strings, case-insensitive repetition, cross-statement sharing, mixing detection, named type hints) plus 7 end-to-end endpoint tests (auto-naming through the camelCase converter, a repeated placeholder bound from one value, required-parameter matching, name-matched defaults, `type is` retype, claim mapping by placeholder name, mixed-style rejection, and a multi-command file sharing `:id` across statements as one API parameter). All three documentation examples verified end-to-end against live PostgreSQL — including example 21's template-clone workflow (template migrated once; the shared run database and **two parallel per-test isolated databases** cloned from it concurrently; deterministic sequence ids asserted independently in both clones; everything dropped on teardown), watch mode (single-file rerun on a test change, full rerun on a fixture change, teardown on SIGINT/SIGTERM), path and tag filtering (including tags carried through a profile include), and the coverage report with a failing threshold gate. The new configuration keys are covered by the configuration round-trip tests (the `--config` template output matches `appsettings.json`).
diff --git a/plugins/NpgsqlRest.SqlFileSource/README.md b/plugins/NpgsqlRest.SqlFileSource/README.md
index 3777e2ea..2a1704b7 100644
--- a/plugins/NpgsqlRest.SqlFileSource/README.md
+++ b/plugins/NpgsqlRest.SqlFileSource/README.md
@@ -124,7 +124,17 @@ SELECT id, status FROM orders WHERE id = $1;
 
 ## Parameters
 
-SQL files use PostgreSQL positional parameters (`$1`, `$2`, ...). Parameters are passed via query string (GET) or JSON body (POST/PUT/DELETE):
+SQL files use PostgreSQL positional parameters (`$1`, `$2`, ...) or **named parameters** (`:name`) — one style per file (mixing is rejected).
+
+**Named parameters** carry their API name in the placeholder itself (converted with the configured `NameConverter`, camelCase by default), so no `@param` naming annotations are needed:
+
+```sql
+SELECT * FROM users WHERE name = :user_name AND age > :age;
+```
+
+Gives: `GET /api/my-query?userName=hello&age=42`. The same name used repeatedly — including across statements in a multi-command file — is ONE parameter. The SQL is rewritten to native `$N` before describe/execution, so type inference and runtime behavior are identical to positional files. Strings, comments, and dollar-quoted bodies are untouched; `::` casts, `:=` calls, and numeric slice bounds (`a[1:3]`) never match (write a variable slice bound with a space: `a[1 : n]`). Annotations match named parameters by name: `@param user_name default null`, `@param :user_name citext` (type hint), or `@param user_name type is citext` (retype without rename).
+
+**Positional parameters** are passed via query string (GET) or JSON body (POST/PUT/DELETE):
 
 ```
 GET /api/my-query?$1=hello&$2=42
diff --git a/plugins/NpgsqlRest.SqlFileSource/SqlFileParser.cs b/plugins/NpgsqlRest.SqlFileSource/SqlFileParser.cs
index 718658b5..02de1e58 100644
--- a/plugins/NpgsqlRest.SqlFileSource/SqlFileParser.cs
+++ b/plugins/NpgsqlRest.SqlFileSource/SqlFileParser.cs
@@ -1,3 +1,4 @@
+using System.Text;
 using NpgsqlRest.Common;
 
 namespace NpgsqlRest.SqlFileSource;
@@ -84,6 +85,24 @@ public Method AutoHttpMethod
     }
 }
 
+/// <summary>
+/// Result of the named-parameter (:name) rewrite pass (<see cref="SqlFileParser.RewriteNamedParameters"/>).
+/// </summary>
+public sealed class NamedParamRewriteResult
+{
+    /// <summary>
+    /// Placeholder names in first-appearance order; index i corresponds to $(i+1) in the rewritten SQL.
+    /// The same name (case-insensitive) always maps to the same ordinal, file-wide.
+    /// </summary>
+    public List<string> Names { get; } = [];
+
+    /// <summary>The file uses :name placeholders.</summary>
+    public bool HasNamed => Names.Count > 0;
+
+    /// <summary>A native positional ($N) placeholder was found outside strings/comments/dollar-quotes.</summary>
+    public bool HasPositional { get; set; }
+}
+
 /// <summary>
 /// Single-pass SQL file parser. Extracts comments and splits statements simultaneously.
 /// Handles: line comments (--), block comments (/* */), single-quoted strings (''),
@@ -552,11 +571,12 @@ private static void ExtractVirtualParams(SqlFileParseResult result)
 
     /// <summary>
     /// Extract parameter type hints from @param annotations.
-    /// Looks for patterns like: @param $1 name type, @param $1 is name type
-    /// Only extracts when a positional $N and an explicit type are present.
-    /// Returns null if no type hints found.
+    /// Positional patterns: @param $1 name type, @param $1 is name type.
+    /// Named patterns (when <paramref name="namedParams"/> is supplied — the file uses :name placeholders):
+    /// @param :name type, @param name type is type.
+    /// Only extracts when an explicit type is present. Returns null if no type hints found.
     /// </summary>
-    public static Dictionary<int, string>? ExtractParamTypeHints(string? comment)
+    public static Dictionary<int, string>? ExtractParamTypeHints(string? comment, IReadOnlyList<string>? namedParams = null)
     {
         if (string.IsNullOrEmpty(comment)) return null;
 
@@ -576,37 +596,68 @@ private static void ExtractVirtualParams(SqlFileParseResult result)
 
             var parts = s.Split([' ', '\t'], StringSplitOptions.RemoveEmptyEntries);
 
-            if (parts.Length < 2 || parts[1][0] != '$')
-            {
-                continue;
-            }
-
-            if (!int.TryParse(parts[1].AsSpan(1), out int paramIndex) || paramIndex < 1)
+            if (parts.Length < 2)
             {
                 continue;
             }
 
-            // @param $1 name type ... → parts[3] is type candidate
-            // @param $1 is name type ... → parts[4] is type candidate
+            int paramIndex;
             string? typeName = null;
-            if (parts.Length >= 4 && parts[2].Equals("is", StringComparison.OrdinalIgnoreCase))
+
+            if (parts[1][0] == '$')
             {
-                if (parts.Length >= 5)
+                if (!int.TryParse(parts[1].AsSpan(1), out paramIndex) || paramIndex < 1)
                 {
-                    var candidate = parts[4].TrimEnd(';').ToLowerInvariant();
-                    if (candidate != "default" && candidate != "=")
+                    continue;
+                }
+
+                // @param $1 name type ... → parts[3] is type candidate
+                // @param $1 is name type ... → parts[4] is type candidate
+                if (parts.Length >= 4 && parts[2].Equals("is", StringComparison.OrdinalIgnoreCase))
+                {
+                    if (parts.Length >= 5)
                     {
-                        typeName = candidate;
+                        typeName = TypeCandidate(parts[4]);
                     }
                 }
+                else if (parts.Length >= 4)
+                {
+                    typeName = TypeCandidate(parts[3]);
+                }
             }
-            else if (parts.Length >= 4)
+            else if (namedParams is not null)
             {
-                var candidate = parts[3].TrimEnd(';').ToLowerInvariant();
-                if (candidate != "default" && candidate != "=")
+                // @param :name type ...           → parts[2] is type candidate
+                // @param name type is type ...    → parts[4] is type candidate
+                string name;
+                int typeIdx;
+                if (parts[1][0] == ':' && parts[1].Length > 1)
+                {
+                    name = parts[1][1..];
+                    typeIdx = 2;
+                }
+                else if (parts.Length >= 5 &&
+                    parts[2].Equals("type", StringComparison.OrdinalIgnoreCase) &&
+                    parts[3].Equals("is", StringComparison.OrdinalIgnoreCase))
                 {
-                    typeName = candidate;
+                    name = parts[1];
+                    typeIdx = 4;
                 }
+                else
+                {
+                    continue;
+                }
+
+                paramIndex = IndexOfName(namedParams, name) + 1;
+                if (paramIndex < 1 || parts.Length <= typeIdx)
+                {
+                    continue;
+                }
+                typeName = TypeCandidate(parts[typeIdx]);
+            }
+            else
+            {
+                continue;
             }
 
             if (typeName is not null)
@@ -621,6 +672,181 @@ private static void ExtractVirtualParams(SqlFileParseResult result)
         }
 
         return hints;
+
+        static string? TypeCandidate(string part)
+        {
+            var candidate = part.TrimEnd(';').ToLowerInvariant();
+            return candidate is "default" or "=" ? null : candidate;
+        }
+    }
+
+    /// <summary>0-based index of a named parameter (case-insensitive), or -1.</summary>
+    public static int IndexOfName(IReadOnlyList<string> namedParams, string name)
+    {
+        for (int i = 0; i < namedParams.Count; i++)
+        {
+            if (string.Equals(namedParams[i], name, StringComparison.OrdinalIgnoreCase))
+            {
+                return i;
+            }
+        }
+        return -1;
+    }
+
+    /// <summary>
+    /// Rewrite named (:name) placeholders in the parsed statements to native positional ($N) placeholders.
+    /// Names are assigned ordinals in first-appearance order across the whole file (case-insensitive), so
+    /// the same name used repeatedly — including across statements — maps to the SAME parameter. The
+    /// rewritten SQL is what gets described and executed; PostgreSQL never sees the :name form.
+    ///
+    /// Token-aware: strings ('', ""), comments (-- and nested /* */), and dollar-quoted bodies are left
+    /// untouched. `::` casts, `:=` assignments, and numeric slice bounds (a[1:3]) never match because a
+    /// placeholder requires an identifier-start character immediately after the colon (a slice with a
+    /// variable bound, a[1:n], must be written with a space: a[1 : n]).
+    ///
+    /// Also detects native $N placeholders so the caller can reject files mixing both styles.
+    /// </summary>
+    public static NamedParamRewriteResult RewriteNamedParameters(List<string> statements)
+    {
+        var result = new NamedParamRewriteResult();
+
+        for (int s = 0; s < statements.Count; s++)
+        {
+            var sql = statements[s];
+            StringBuilder? sb = null; // created lazily on the first replacement
+            var state = State.Normal;
+            int blockDepth = 0;
+            string dollarTag = "";
+            char quote = '\0';
+
+            for (int i = 0; i < sql.Length; i++)
+            {
+                char c = sql[i];
+                char next = i + 1 < sql.Length ? sql[i + 1] : '\0';
+
+                switch (state)
+                {
+                    case State.Normal:
+                        if (c == '-' && next == '-')
+                        {
+                            state = State.LineComment;
+                        }
+                        else if (c == '/' && next == '*')
+                        {
+                            state = State.BlockComment;
+                            blockDepth = 1;
+                            sb?.Append(c); sb?.Append(next); i++;
+                            continue;
+                        }
+                        else if (c == '\'' || c == '"')
+                        {
+                            state = State.SingleQuote;
+                            quote = c;
+                        }
+                        else if (c == '$')
+                        {
+                            // Dollar-quote open ($$ / $tag$) vs positional param ($1). A dollar-quote tag
+                            // must start with a letter/underscore, so $ followed by a digit is always $N.
+                            if (next == '$' || char.IsAsciiLetter(next) || next == '_')
+                            {
+                                int t = i + 1;
+                                while (t < sql.Length && (char.IsAsciiLetterOrDigit(sql[t]) || sql[t] == '_')) t++;
+                                if (t < sql.Length && sql[t] == '$')
+                                {
+                                    dollarTag = sql[i..(t + 1)];
+                                    state = State.DollarQuote;
+                                    sb?.Append(dollarTag);
+                                    i = t;
+                                    continue;
+                                }
+                            }
+                            else if (char.IsAsciiDigit(next))
+                            {
+                                result.HasPositional = true;
+                            }
+                        }
+                        else if (c == ':')
+                        {
+                            if (next == ':')
+                            {
+                                // `::` cast — copy both, never a placeholder
+                                sb?.Append("::");
+                                i++;
+                                continue;
+                            }
+                            if (char.IsAsciiLetter(next) || next == '_')
+                            {
+                                int e = i + 1;
+                                while (e < sql.Length && (char.IsAsciiLetterOrDigit(sql[e]) || sql[e] == '_')) e++;
+                                var name = sql[(i + 1)..e];
+                                int idx = IndexOfName(result.Names, name);
+                                if (idx < 0)
+                                {
+                                    result.Names.Add(name);
+                                    idx = result.Names.Count - 1;
+                                }
+                                sb ??= new StringBuilder(sql[..i], sql.Length);
+                                sb.Append('$').Append(idx + 1);
+                                i = e - 1;
+                                continue;
+                            }
+                        }
+                        break;
+
+                    case State.LineComment:
+                        if (c == '\n') state = State.Normal;
+                        break;
+
+                    case State.BlockComment:
+                        if (c == '*' && next == '/')
+                        {
+                            if (--blockDepth == 0) state = State.Normal;
+                            sb?.Append(c); sb?.Append(next); i++;
+                            continue;
+                        }
+                        if (c == '/' && next == '*')
+                        {
+                            blockDepth++;
+                            sb?.Append(c); sb?.Append(next); i++;
+                            continue;
+                        }
+                        break;
+
+                    case State.SingleQuote:
+                        if (c == quote)
+                        {
+                            if (next == quote)
+                            {
+                                // '' / "" escape — stay in the string
+                                sb?.Append(c); sb?.Append(next); i++;
+                                continue;
+                            }
+                            state = State.Normal;
+                        }
+                        break;
+
+                    case State.DollarQuote:
+                        if (c == '$' && i + dollarTag.Length <= sql.Length
+                            && sql.AsSpan(i, dollarTag.Length).SequenceEqual(dollarTag))
+                        {
+                            sb?.Append(dollarTag);
+                            i += dollarTag.Length - 1;
+                            state = State.Normal;
+                            continue;
+                        }
+                        break;
+                }
+
+                sb?.Append(c);
+            }
+
+            if (sb is not null)
+            {
+                statements[s] = sb.ToString();
+            }
+        }
+
+        return result;
     }
 
     private static void DetectMutation(ReadOnlySpan<char> word, SqlFileParseResult result)
diff --git a/plugins/NpgsqlRest.SqlFileSource/SqlFileSource.cs b/plugins/NpgsqlRest.SqlFileSource/SqlFileSource.cs
index 7edf6c19..8c869bed 100644
--- a/plugins/NpgsqlRest.SqlFileSource/SqlFileSource.cs
+++ b/plugins/NpgsqlRest.SqlFileSource/SqlFileSource.cs
@@ -127,23 +127,42 @@ private static (Routine, IRoutineSourceParameterFormatter)? ProcessFile(
             return null;
         }
 
+        // Named-parameter (:name) rewrite: placeholders become native $N before Describe/execution
+        // (PostgreSQL never sees the :name form); the names flow into parameter ActualName, so the API
+        // name — and claim mappings — come from the placeholder itself. Same name = same parameter,
+        // file-wide. Mixing $N and :name in one file is ambiguous and rejected.
+        var namedParams = SqlFileParser.RewriteNamedParameters(parseResult.Statements);
+        if (namedParams.HasNamed && namedParams.HasPositional)
+        {
+            NpgsqlRestOptions.Logger?.LogError(
+                "SqlFileSource: {FilePath}: mixing positional ($N) and named (:name) parameters in the same file is not supported — use one style.",
+                filePath);
+            if (options.ErrorMode == ParseErrorMode.Exit)
+            {
+                NpgsqlRestOptions.Logger?.LogCritical("SqlFileSource: Exiting due to SQL file error. Set ErrorMode to Skip to continue past errors.");
+                Environment.Exit(1);
+            }
+            return null;
+        }
+        IReadOnlyList<string>? namedList = namedParams.HasNamed ? namedParams.Names : null;
+
         bool isMultiCommand = parseResult.Statements.Count > 1;
 
         // Check @param annotations for HTTP client type parameters (single composite, no SQL rewriting)
         Dictionary<int, (string TypeName, string ParamName, string[] FieldNames, string[] FieldTypes)>? httpTypeParams = null;
         if (NpgsqlRestOptions.Options.HttpClientOptions.Enabled && HttpClientTypes.Definitions.Count > 0)
         {
-            httpTypeParams = DetectHttpTypeParams(parseResult.Comment, connection);
+            httpTypeParams = DetectHttpTypeParams(parseResult.Comment, connection, namedList);
         }
 
         // Check @param annotations for non-HTTP composite type parameters (single composite, no SQL rewriting)
-        var compositeTypeParams = DetectCompositeTypeParams(parseResult.Comment, connection, httpTypeParams);
+        var compositeTypeParams = DetectCompositeTypeParams(parseResult.Comment, connection, httpTypeParams, namedList);
 
         // Describe each statement individually and merge parameters
         int mergedMaxParam = 0;
         var paramTypesByIndex = new Dictionary<int, string>(); // $N index → type name
         var commandDescribes = new List<DescribeResult>();
-        var paramTypeHints = SqlFileParser.ExtractParamTypeHints(parseResult.Comment);
+        var paramTypeHints = SqlFileParser.ExtractParamTypeHints(parseResult.Comment, namedList);
 
         for (int stmtIndex = 0; stmtIndex < parseResult.Statements.Count; stmtIndex++)
         {
@@ -249,6 +268,8 @@ private static (Routine, IRoutineSourceParameterFormatter)? ProcessFile(
         for (int i = 0; i < mergedMaxParam; i++)
         {
             var typeName = paramTypesByIndex.GetValueOrDefault(i, "unknown");
+            // Named (:name) placeholder for this ordinal, when the file uses them.
+            string? placeholderName = namedList is not null && i < namedList.Count ? namedList[i] : null;
 
             string? customType = null;
             string? customTypeName = null;
@@ -273,7 +294,11 @@ private static (Routine, IRoutineSourceParameterFormatter)? ProcessFile(
             }
             else
             {
-                convertedName = $"${i + 1}";
+                // Named placeholders get their API name from the placeholder itself, through the same
+                // NameConverter routine parameters use (:user_id → userId); positional stay "$N".
+                convertedName = placeholderName is not null
+                    ? nameConverter(placeholderName) ?? placeholderName
+                    : $"${i + 1}";
             }
 
             var typeDescriptor = new TypeDescriptor(
@@ -283,7 +308,7 @@ private static (Routine, IRoutineSourceParameterFormatter)? ProcessFile(
                 customTypePosition: customTypePosition,
                 originalParameterName: originalParameterName,
                 customTypeName: customTypeName);
-            var positionalName = $"${i + 1}";
+            var positionalName = placeholderName ?? $"${i + 1}";
 
             var param = new NpgsqlRestParameter(
                 ordinal: i,
@@ -488,22 +513,47 @@ private static void ResolveCompositeType(TypeDescriptor descriptor)
         CompositeTypeCache.ResolveTypeDescriptor(descriptor);
     }
 
+    /// <summary>
+    /// Collect typed @param annotations as (0-based index, API param name, type name) tuples.
+    /// Positional form: @param $N name type. Named form (only for files using :name placeholders):
+    /// @param :name type — the API name comes from the placeholder itself, through the NameConverter.
+    /// </summary>
+    private static List<(int ParamIndex, string ParamName, string TypeName)> CollectTypedParamAnnotations(
+        string comment, IReadOnlyList<string>? namedParams)
+    {
+        List<(int, string, string)> annotations = [];
+        foreach (Match match in Regex.Matches(comment, @"@param\s+\$(\d+)\s+(\w+)\s+(\S+)", RegexOptions.IgnoreCase))
+        {
+            annotations.Add((int.Parse(match.Groups[1].Value) - 1, match.Groups[2].Value, match.Groups[3].Value));
+        }
+        if (namedParams is not null)
+        {
+            foreach (Match match in Regex.Matches(comment, @"@param\s+:(\w+)\s+(\S+)", RegexOptions.IgnoreCase))
+            {
+                var name = match.Groups[1].Value;
+                var paramIndex = SqlFileParser.IndexOfName(namedParams, name);
+                if (paramIndex < 0)
+                {
+                    continue;
+                }
+                var paramName = NpgsqlRestOptions.Options.NameConverter(name) ?? name;
+                annotations.Add((paramIndex, paramName, match.Groups[2].Value));
+            }
+        }
+        return annotations;
+    }
+
     /// <summary>
     /// Scan @param annotations in the comment for HTTP client type parameters.
     /// Returns null if no HTTP types found, otherwise a dictionary keyed by 0-based param index.
     /// </summary>
     private static Dictionary<int, (string TypeName, string ParamName, string[] FieldNames, string[] FieldTypes)>?
-        DetectHttpTypeParams(string comment, NpgsqlConnection connection)
+        DetectHttpTypeParams(string comment, NpgsqlConnection connection, IReadOnlyList<string>? namedParams)
     {
         Dictionary<int, (string TypeName, string ParamName, string[] FieldNames, string[] FieldTypes)>? result = null;
 
-        // Match @param $N name type patterns
-        foreach (Match match in Regex.Matches(comment, @"@param\s+\$(\d+)\s+(\w+)\s+(\S+)", RegexOptions.IgnoreCase))
+        foreach (var (paramIndex, paramName, typeName) in CollectTypedParamAnnotations(comment, namedParams))
         {
-            var paramIndex = int.Parse(match.Groups[1].Value) - 1; // 0-based
-            var paramName = match.Groups[2].Value;
-            var typeName = match.Groups[3].Value;
-
             // Check if this type is an HTTP client type (try with and without public. prefix)
             string? resolvedTypeName = null;
             if (HttpClientTypes.Definitions.ContainsKey(typeName))
@@ -579,16 +629,13 @@ and a.attnum > 0 and not a.attisdropped
         DetectCompositeTypeParams(
             string comment,
             NpgsqlConnection connection,
-            Dictionary<int, (string TypeName, string ParamName, string[] FieldNames, string[] FieldTypes)>? httpTypeParams)
+            Dictionary<int, (string TypeName, string ParamName, string[] FieldNames, string[] FieldTypes)>? httpTypeParams,
+            IReadOnlyList<string>? namedParams)
     {
         Dictionary<int, (string TypeName, string ParamName, string[] FieldNames, string[] FieldTypes)>? result = null;
 
-        foreach (Match match in Regex.Matches(comment, @"@param\s+\$(\d+)\s+(\w+)\s+(\S+)", RegexOptions.IgnoreCase))
+        foreach (var (paramIndex, paramName, typeName) in CollectTypedParamAnnotations(comment, namedParams))
         {
-            var paramIndex = int.Parse(match.Groups[1].Value) - 1; // 0-based
-            var paramName = match.Groups[2].Value;
-            var typeName = match.Groups[3].Value;
-
             // Skip if already detected as HTTP type
             if (httpTypeParams is not null && httpTypeParams.ContainsKey(paramIndex))
             {

From f859a4f051b6d3a2645d1eb44d2519c948eab62e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Fri, 3 Jul 2026 18:30:34 +0200
Subject: [PATCH 20/25] =?UTF-8?q?feat(watch):=20server=20watch=20mode=20?=
 =?UTF-8?q?=E2=80=94=20--watch=20restarts=20the=20server=20on=20SQL/config?=
 =?UTF-8?q?=20changes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

--watch is now a two-mode flag: with --test it is the test runner's in-process
watch (unchanged); WITHOUT --test it runs the SERVER under a watch supervisor.

Supervisor/child design (same model as dotnet watch): the process spawns
itself as a child server (marked via NPGSQLREST_WATCH_CHILD; value = the
supervisor PID) and watches the SqlFileSource tree plus the configuration
files. On a debounced change it stops the child gracefully and starts a fresh
one — the child runs the completely normal server pipeline (discovery,
describe, code generation, Kestrel), so dev is production behavior. The one
relaxation: SqlFileSource ErrorMode is forced Exit->Skip in the watch child so
a broken SQL file logs its error and drops only its own endpoint.

Details:
- Edits to files matching SqlFileSource.SkipPattern (test files) do NOT
  restart the server.
- Child crash: the supervisor prints "server exited (code N) — waiting for
  file changes" and revives on the next relevant save (no crash-looping).
- Graceful stop: SIGTERM via libc DllImport on Unix (Process.Kill is SIGKILL);
  hard process-tree kill on Windows (a dev server has no teardown needs).
- Parent watchdog in the child: if the supervisor dies without stopping it
  (SIGKILL, wrapper runners like bun run), the child exits by itself — no
  orphan holding the port.
- Spawn works from the AOT binary (Environment.ProcessPath) and under
  `dotnet NpgsqlRestClient.dll` (dotnet host re-invoked with the dll).
- DOTNET_USE_POLLING_FILE_WATCHER=1 switches to a 1s polling scan for
  environments where file events don't cross the filesystem boundary
  (Docker Desktop bind mounts).
- --watch without --test and without an enabled SqlFileSource exits with a
  clear error (nothing to watch).
- WatchUtils extracts the shared watch primitives (base dir, debounce,
  pattern match); the test runner delegates to it, behavior identical.

Plan B (in-process endpoint hot-swap via a dynamic EndpointDataSource,
target 3.20) is designed in scrap/WATCH_HOT_SWAP_PLAN.md.

Verified live across 12 scenarios: initial serve, add/break/fix endpoint
file (broken file 404s while the rest keeps serving), test-file edit ignored,
config-edit restart, child crash recovery, supervisor SIGKILL -> child
self-exit (no orphans), SIGTERM graceful stop with port freed, polling mode,
nothing-to-watch error, and test mode unaffected. Full suite green (2393).
Changelog: watch documented as a single two-mode feature.
---
 NpgsqlRestClient/App.cs                |   2 +-
 NpgsqlRestClient/Program.cs            |  19 +-
 NpgsqlRestClient/Testing/TestRunner.cs |  51 +----
 NpgsqlRestClient/WatchSupervisor.cs    | 300 +++++++++++++++++++++++++
 NpgsqlRestClient/WatchUtils.cs         | 141 ++++++++++++
 changelog/v3.19.0.md                   | 164 +++++++++-----
 6 files changed, 573 insertions(+), 104 deletions(-)
 create mode 100644 NpgsqlRestClient/WatchSupervisor.cs
 create mode 100644 NpgsqlRestClient/WatchUtils.cs

diff --git a/NpgsqlRestClient/App.cs b/NpgsqlRestClient/App.cs
index 8978f83b..fe1fcd90 100644
--- a/NpgsqlRestClient/App.cs
+++ b/NpgsqlRestClient/App.cs
@@ -690,7 +690,7 @@ public List<IEndpointSource> CreateEndpointSources(bool relaxSqlFileErrors = fal
                     // session (Environment.Exit) on a broken SQL file — Skip drops the file instead, and
                     // the runner reports the endpoint delta after each rebuild.
                     opts.ErrorMode = ParseErrorMode.Skip;
-                    _builder.TestLogger?.LogDebug("watch mode: SqlFileSource ErrorMode forced from Exit to Skip");
+                    (_builder.TestLogger ?? _builder.ClientLogger)?.LogDebug("watch mode: SqlFileSource ErrorMode forced from Exit to Skip");
                 }
                 var resultPrefix = _config.GetConfigStr("ResultPrefix", sqlFileSourceCfg);
                 if (resultPrefix is not null)
diff --git a/NpgsqlRestClient/Program.cs b/NpgsqlRestClient/Program.cs
index ea0f29c1..641524ab 100644
--- a/NpgsqlRestClient/Program.cs
+++ b/NpgsqlRestClient/Program.cs
@@ -40,6 +40,7 @@
         ("npgsqlrest [files...] --endpoints", "Connect to database, discover endpoints, output as JSON, then exit. Syntax highlighted in terminal, plain JSON when piped."),
         ("npgsqlrest [files...] --test", "Run SQL test files (TestRunner config), then exit. Exit codes: 0 pass, 1 failures, 2 errors, 3 config error, 4 no tests."),
         ("npgsqlrest [files...] --test --watch", "Watch mode: run the tests, then re-run on file changes until Ctrl+C (interactive/dev-only; teardown runs on exit)."),
+        ("npgsqlrest [files...] --watch", "Server watch mode (dev): run the server and restart it on SQL file source or configuration file changes until Ctrl+C. Requires an enabled SqlFileSource."),
         (" ", " "),
         ("npgsqlrest --hash [value]", "Hash value with default hasher and print to console."),
         ("npgsqlrest --basic_auth [username] [password]", "Print out basic basic auth header value in format 'Authorization: Basic base64(username:password)'."),
@@ -276,6 +277,20 @@
 bool watchMode = testMode && (args.Any(a => string.Equals(a, "--watch", StringComparison.OrdinalIgnoreCase))
     || config.GetConfigBool("Watch", config.Cfg.GetSection("TestRunner")));
 
+// Server watch mode (--watch WITHOUT --test): this process becomes a supervisor that spawns itself as
+// a child server and restarts it on SQL/config file changes; the child (marked by an env variable)
+// falls through and runs the normal server pipeline. See WatchSupervisor.
+if (testMode is false && args.Any(a => string.Equals(a, "--watch", StringComparison.OrdinalIgnoreCase)))
+{
+    if (WatchSupervisor.IsChild is false)
+    {
+        Environment.ExitCode = await WatchSupervisor.RunAsync(config, args);
+        return;
+    }
+    // The child exits by itself if the supervisor dies without stopping it (no orphan on the port).
+    WatchSupervisor.StartParentWatchdog();
+}
+
 builder.BuildInstance();
 builder.Instance.Services.AddRouting();
 if (!endpointsMode)
@@ -478,7 +493,9 @@
     SseResponseHeaders = builder.GetSseResponseHeaders(),
     WarnUnboundSseNotices = config.GetConfigBool("WarnUnboundServerSentEventsNotices", config.NpgsqlRestCfg, true),
 
-    EndpointSources = appInstance.CreateEndpointSources(relaxSqlFileErrors: watchMode),
+    // Both watch flavors must survive a broken SQL file: the test runner's in-process watch and the
+    // server watch child (supervisor restarts it on the next save either way).
+    EndpointSources = appInstance.CreateEndpointSources(relaxSqlFileErrors: watchMode || WatchSupervisor.IsChild),
     UploadOptions = appInstance.CreateUploadOptions(),
     
     CacheOptions = builder.BuildCacheOptions(app, cacheType),
diff --git a/NpgsqlRestClient/Testing/TestRunner.cs b/NpgsqlRestClient/Testing/TestRunner.cs
index 0c56c075..23c1c237 100644
--- a/NpgsqlRestClient/Testing/TestRunner.cs
+++ b/NpgsqlRestClient/Testing/TestRunner.cs
@@ -531,13 +531,9 @@ FileSystemWatcher NewWatcher(string dir)
         }
     }
 
-    // A cwd-relative path against a cwd-relative glob (leading "./" tolerated on the pattern).
+    // A cwd-relative path against a cwd-relative glob (shared with the server watch supervisor).
     private static bool MatchesCwdRelativePattern(string relativePath, string pattern)
-    {
-        pattern = pattern.Replace('\\', '/');
-        if (pattern.StartsWith("./")) pattern = pattern[2..];
-        return Parser.IsPatternMatch(relativePath, pattern);
-    }
+        => WatchUtils.MatchesCwdRelativePattern(relativePath, pattern);
 
     // Rebuild delta: how many endpoints now, plus every added/removed "METHOD path" — a removed endpoint
     // usually means its SQL file failed to parse/describe and was skipped.
@@ -564,46 +560,13 @@ static HashSet<string> Keys(RoutineEndpoint[] eps) =>
             after.Length, before.Length, added.Count, removed.Count);
     }
 
-    // First change (blocking), then a quiet period so editor write bursts coalesce into one rerun.
-    private static async Task<List<string>?> NextChangeBatchAsync(System.Threading.Channels.ChannelReader<string> reader, CancellationToken ct)
-    {
-        string first;
-        try
-        {
-            first = await reader.ReadAsync(ct);
-        }
-        catch (OperationCanceledException)
-        {
-            return null;
-        }
-        var batch = new List<string> { first };
-        while (true)
-        {
-            try { await Task.Delay(300, ct); } catch (OperationCanceledException) { return null; }
-            bool any = false;
-            while (reader.TryRead(out var more))
-            {
-                batch.Add(more);
-                any = true;
-            }
-            if (!any) return batch;
-        }
-    }
+    // First change (blocking) + quiet-period coalescing (shared with the server watch supervisor).
+    private static Task<List<string>?> NextChangeBatchAsync(System.Threading.Channels.ChannelReader<string> reader, CancellationToken ct)
+        => WatchUtils.NextChangeBatchAsync(reader, ct);
 
-    // The deepest fixed (wildcard-free) directory of the FilePattern — same logic DiscoverFiles uses.
+    // The deepest fixed (wildcard-free) directory of the FilePattern (shared with the supervisor).
     private static string? GetWatchBaseDir(string pattern)
-    {
-        if (string.IsNullOrWhiteSpace(pattern)) return null;
-        int firstWildcard = pattern.IndexOfAny(['*', '?']);
-        if (firstWildcard < 0)
-        {
-            var dir = Path.GetDirectoryName(pattern);
-            return string.IsNullOrEmpty(dir) ? "." : dir;
-        }
-        int lastSlash = pattern.LastIndexOf('/', firstWildcard);
-        var baseDir = lastSlash >= 0 ? pattern[..lastSlash] : ".";
-        return Directory.Exists(baseDir) ? baseDir : null;
-    }
+        => WatchUtils.GetWatchBaseDir(pattern);
 
     private async Task<FileResult> RunFileAsync(string file, IReadOnlyDictionary<string, RoutineEndpoint> lookup, CancellationToken runCt)
     {
diff --git a/NpgsqlRestClient/WatchSupervisor.cs b/NpgsqlRestClient/WatchSupervisor.cs
new file mode 100644
index 00000000..829caa9b
--- /dev/null
+++ b/NpgsqlRestClient/WatchSupervisor.cs
@@ -0,0 +1,300 @@
+using System.Diagnostics;
+using System.Runtime.InteropServices;
+using System.Threading.Channels;
+
+namespace NpgsqlRestClient;
+
+/// <summary>
+/// Server watch mode (`--watch` without `--test`): this process becomes a tiny SUPERVISOR that never
+/// builds the server itself — it spawns this same executable as a CHILD (marked via an environment
+/// variable), watches the SqlFileSource tree and the configuration files, and restarts the child on
+/// every debounced change. The child runs the completely normal server pipeline (production parity),
+/// with one relaxation: SqlFileSource ErrorMode is forced from Exit to Skip so a broken SQL file logs
+/// its error and drops that endpoint instead of killing the server (see App.CreateEndpointSources).
+///
+/// Design notes:
+/// - A child process (vs. in-process rebuild) guarantees clean state: Kestrel's port binding and
+///   ASP.NET's route table cannot be torn down in-process (routes can be added, never removed), and
+///   static caches would accumulate. This is the same conclusion `dotnet watch` and nodemon reached.
+///   The in-process hot-swap upgrade is designed in scrap/WATCH_HOT_SWAP_PLAN.md (target 3.20).
+/// - Graceful stop: SIGTERM via libc on Unix (Process.Kill would be SIGKILL), hard kill fallback after
+///   a timeout; on Windows there is no SIGTERM for console children — hard process-tree kill, which is
+///   acceptable here because a dev server holds nothing that needs teardown.
+/// - The child runs a parent WATCHDOG: if the supervisor dies without stopping it (SIGKILL, a wrapper
+///   runner like `bun run` murdering the process group), the child exits by itself — no orphan holding
+///   the port.
+/// </summary>
+public static class WatchSupervisor
+{
+    /// <summary>Set on the child process; the value is the supervisor's PID (for the parent watchdog).</summary>
+    public const string ChildEnv = "NPGSQLREST_WATCH_CHILD";
+
+    public static bool IsChild { get; } = string.IsNullOrEmpty(Environment.GetEnvironmentVariable(ChildEnv)) is false;
+
+    // Blittable signature — plain DllImport is AOT-safe here and avoids AllowUnsafeBlocks.
+    [DllImport("libc", SetLastError = true, EntryPoint = "kill")]
+    private static extern int kill(int pid, int sig);
+    private const int SIGTERM = 15;
+
+    /// <summary>
+    /// Called in the CHILD: exit when the supervisor process disappears without stopping us first,
+    /// so a SIGKILLed supervisor never leaves an orphaned server holding the port.
+    /// </summary>
+    public static void StartParentWatchdog()
+    {
+        if (int.TryParse(Environment.GetEnvironmentVariable(ChildEnv), out var parentPid) is false)
+        {
+            return;
+        }
+        var thread = new Thread(() =>
+        {
+            try
+            {
+                Process.GetProcessById(parentPid).WaitForExit();
+            }
+            catch
+            {
+                // already gone
+            }
+            Environment.Exit(143);
+        })
+        {
+            IsBackground = true,
+            Name = "watch-parent-watchdog",
+        };
+        thread.Start();
+    }
+
+    /// <summary>Supervisor main loop. Returns the process exit code.</summary>
+    public static async Task<int> RunAsync(Config config, string[] args)
+    {
+        var output = new Out();
+
+        // Something to watch? Server watch requires an enabled SqlFileSource (database routines have no
+        // files to watch — a change in the database needs a manual restart either way).
+        var sqlFileCfg = config.NpgsqlRestCfg.GetSection("SqlFileSource");
+        string? filePattern = null;
+        if (sqlFileCfg.Exists() && config.GetConfigBool("Enabled", sqlFileCfg, true))
+        {
+            filePattern = config.GetConfigStr("FilePattern", sqlFileCfg);
+        }
+        if (string.IsNullOrWhiteSpace(filePattern))
+        {
+            output.LineAnsi(
+                "watch: nothing to watch — --watch without --test requires an enabled SqlFileSource with a FilePattern. For test watch mode use --test --watch.",
+                Testing.TestRunner.AnsiFail);
+            return 1;
+        }
+        var baseDir = WatchUtils.GetWatchBaseDir(filePattern);
+        if (baseDir is null)
+        {
+            output.LineAnsi(
+                $"watch: cannot watch — SqlFileSource FilePattern \"{filePattern}\" has no existing base directory.",
+                Testing.TestRunner.AnsiFail);
+            return 1;
+        }
+        var baseDirFull = Path.GetFullPath(baseDir);
+        var skipPattern = (config.GetConfigStr("SkipPattern", sqlFileCfg) ?? "*.test.sql").Replace('\\', '/');
+
+        // Config files restart the server too: the .json/.jsonc files passed on the command line, plus
+        // the implicit default when present.
+        var configFiles = args
+            .Where(a => a.StartsWith('-') is false
+                && (a.EndsWith(".json", StringComparison.OrdinalIgnoreCase) || a.EndsWith(".jsonc", StringComparison.OrdinalIgnoreCase))
+                && File.Exists(a))
+            .Select(Path.GetFullPath)
+            .ToList();
+        if (File.Exists("appsettings.json"))
+        {
+            configFiles.Add(Path.GetFullPath("appsettings.json"));
+        }
+        configFiles = [.. configFiles.Distinct(StringComparer.Ordinal)];
+        var configFileSet = new HashSet<string>(configFiles, StringComparer.Ordinal);
+
+        using var stop = new CancellationTokenSource();
+        bool stopping = false;
+        void OnSignal(PosixSignalContext ctx)
+        {
+            // The child receives Ctrl+C from the terminal group by itself; for SIGTERM (docker stop,
+            // where only PID 1 is signalled) the shutdown path below forwards the stop to the child.
+            ctx.Cancel = true;
+            stopping = true;
+            stop.Cancel();
+        }
+        using var sigInt = PosixSignalRegistration.Create(PosixSignal.SIGINT, OnSignal);
+        using var sigTerm = PosixSignalRegistration.Create(PosixSignal.SIGTERM, OnSignal);
+
+        // Watchers (or the polling fallback for bind-mount environments) feed one debounced channel.
+        var changes = Channel.CreateUnbounded<string>();
+        var watchers = new List<FileSystemWatcher>();
+        bool polling = WatchUtils.UsePollingWatcher;
+        if (polling)
+        {
+            WatchUtils.StartPollingWatcher(baseDirFull, configFiles, changes.Writer, stop.Token);
+        }
+        else
+        {
+            watchers.Add(WatchUtils.NewSqlWatcher(baseDirFull, changes.Writer));
+            foreach (var dir in configFiles.Select(Path.GetDirectoryName).Where(d => d is not null).Distinct(StringComparer.Ordinal))
+            {
+                var w = new FileSystemWatcher(dir!)
+                {
+                    NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.FileName | NotifyFilters.Size,
+                };
+                void OnFsEvent(object s, FileSystemEventArgs e)
+                {
+                    if (configFileSet.Contains(e.FullPath))
+                    {
+                        changes.Writer.TryWrite(e.FullPath);
+                    }
+                }
+                w.Changed += OnFsEvent;
+                w.Created += OnFsEvent;
+                w.Renamed += (s, e) => { if (configFileSet.Contains(e.FullPath)) changes.Writer.TryWrite(e.FullPath); };
+                w.EnableRaisingEvents = true;
+                watchers.Add(w);
+            }
+        }
+
+        var watchingWhat = $"{Path.GetRelativePath(Environment.CurrentDirectory, baseDirFull)} (*.sql)"
+            + (configFiles.Count > 0 ? " + config files" : "")
+            + (polling ? " [polling]" : "");
+        output.Line($"watch mode: supervising the server process, watching {watchingWhat} — Ctrl+C to stop", ConsoleColor.Cyan);
+
+        Process child = Spawn(args);
+        Task exitTask = child.WaitForExitAsync(CancellationToken.None);
+
+        try
+        {
+            while (stopping is false)
+            {
+                var batchTask = WatchUtils.NextChangeBatchAsync(changes.Reader, stop.Token);
+                var completed = await Task.WhenAny(exitTask, batchTask);
+
+                if (stopping)
+                {
+                    break;
+                }
+
+                if (completed == exitTask && batchTask.IsCompleted is false)
+                {
+                    // The child died on its own (crash, config error, port conflict). Don't respawn in a
+                    // loop — hold until the next file change, then try again.
+                    output.Line($"\nserver exited (code {child.ExitCode}) — waiting for file changes", ConsoleColor.Yellow);
+                    var wakeBatch = await batchTask;
+                    if (wakeBatch is null || stopping)
+                    {
+                        break;
+                    }
+                    if (Relevant(wakeBatch, baseDirFull, skipPattern, configFileSet) is not { } wakeTrigger)
+                    {
+                        // Irrelevant change (e.g. a *.test.sql edit) — keep holding.
+                        continue;
+                    }
+                    output.Line($"— {DateTime.Now:HH:mm:ss} change detected ({wakeTrigger}) — restarting —", ConsoleColor.Cyan);
+                    child = Spawn(args);
+                    exitTask = child.WaitForExitAsync(CancellationToken.None);
+                    continue;
+                }
+
+                var batch = await batchTask;
+                if (batch is null)
+                {
+                    break;
+                }
+                if (Relevant(batch, baseDirFull, skipPattern, configFileSet) is not { } trigger)
+                {
+                    continue;
+                }
+                output.Line($"\n— {DateTime.Now:HH:mm:ss} change detected ({trigger}) — restarting —", ConsoleColor.Cyan);
+                StopChild(child);
+                child = Spawn(args);
+                exitTask = child.WaitForExitAsync(CancellationToken.None);
+            }
+            return 0;
+        }
+        finally
+        {
+            foreach (var w in watchers)
+            {
+                w.Dispose();
+            }
+            StopChild(child);
+        }
+    }
+
+    /// <summary>
+    /// First relevant path in the batch (cwd-relative, for display), or null when the whole batch is
+    /// noise. Relevant: a config file, or a *.sql file under the watched tree that matches the
+    /// SqlFileSource FilePattern and does NOT match SkipPattern (a test-file edit must not bounce the
+    /// server).
+    /// </summary>
+    private static string? Relevant(List<string> batch, string baseDirFull, string skipPattern, HashSet<string> configFileSet)
+    {
+        foreach (var path in batch.Distinct(StringComparer.Ordinal))
+        {
+            var full = Path.GetFullPath(path);
+            var rel = Path.GetRelativePath(Environment.CurrentDirectory, full).Replace('\\', '/');
+            if (configFileSet.Contains(full))
+            {
+                return rel;
+            }
+            if (full.StartsWith(baseDirFull, StringComparison.Ordinal)
+                && rel.EndsWith(".sql", StringComparison.OrdinalIgnoreCase)
+                && WatchUtils.MatchesCwdRelativePattern(rel, skipPattern) is false)
+            {
+                return rel;
+            }
+        }
+        return null;
+    }
+
+    private static Process Spawn(string[] args)
+    {
+        var exe = Environment.ProcessPath ?? "dotnet";
+        var psi = new ProcessStartInfo(exe)
+        {
+            UseShellExecute = false, // stdout/stderr inherited — the child's logs are the console output
+        };
+        // Under `dotnet NpgsqlRestClient.dll ...` ProcessPath is the dotnet host; argv[0] is the dll path.
+        if (string.Equals(Path.GetFileNameWithoutExtension(exe), "dotnet", StringComparison.OrdinalIgnoreCase))
+        {
+            psi.ArgumentList.Add(Environment.GetCommandLineArgs()[0]);
+        }
+        foreach (var a in args)
+        {
+            psi.ArgumentList.Add(a);
+        }
+        psi.Environment[ChildEnv] = Environment.ProcessId.ToString();
+        return Process.Start(psi)!;
+    }
+
+    private static void StopChild(Process child)
+    {
+        try
+        {
+            if (child.HasExited)
+            {
+                return;
+            }
+            if (OperatingSystem.IsWindows())
+            {
+                // No SIGTERM for console children on Windows; a dev server has nothing needing teardown.
+                child.Kill(entireProcessTree: true);
+            }
+            else
+            {
+                kill(child.Id, SIGTERM); // graceful: Kestrel drains and stops
+                if (child.WaitForExit(5000) is false)
+                {
+                    child.Kill(entireProcessTree: true);
+                }
+            }
+            child.WaitForExit();
+        }
+        catch
+        {
+            // already gone
+        }
+    }
+}
diff --git a/NpgsqlRestClient/WatchUtils.cs b/NpgsqlRestClient/WatchUtils.cs
new file mode 100644
index 00000000..43548d71
--- /dev/null
+++ b/NpgsqlRestClient/WatchUtils.cs
@@ -0,0 +1,141 @@
+using System.Threading.Channels;
+using NpgsqlRest;
+
+namespace NpgsqlRestClient;
+
+/// <summary>
+/// Shared file-watching primitives used by both watch modes: the test runner's in-process watch
+/// (<see cref="Testing.TestRunner"/>) and the server watch supervisor (<see cref="WatchSupervisor"/>).
+/// </summary>
+public static class WatchUtils
+{
+    /// <summary>A cwd-relative path against a cwd-relative glob (leading "./" tolerated on the pattern).</summary>
+    public static bool MatchesCwdRelativePattern(string relativePath, string pattern)
+    {
+        pattern = pattern.Replace('\\', '/');
+        if (pattern.StartsWith("./"))
+        {
+            pattern = pattern[2..];
+        }
+        return Parser.IsPatternMatch(relativePath, pattern);
+    }
+
+    /// <summary>
+    /// The deepest fixed (wildcard-free) directory of a glob pattern — same logic file discovery uses.
+    /// Null when the directory does not exist.
+    /// </summary>
+    public static string? GetWatchBaseDir(string pattern)
+    {
+        if (string.IsNullOrWhiteSpace(pattern))
+        {
+            return null;
+        }
+        int firstWildcard = pattern.IndexOfAny(['*', '?']);
+        if (firstWildcard < 0)
+        {
+            var dir = Path.GetDirectoryName(pattern);
+            return string.IsNullOrEmpty(dir) ? "." : dir;
+        }
+        int lastSlash = pattern.LastIndexOf('/', firstWildcard);
+        var baseDir = lastSlash >= 0 ? pattern[..lastSlash] : ".";
+        return Directory.Exists(baseDir) ? baseDir : null;
+    }
+
+    /// <summary>
+    /// First change (blocking), then a quiet period so editor write bursts coalesce into one batch.
+    /// Returns null when cancelled.
+    /// </summary>
+    public static async Task<List<string>?> NextChangeBatchAsync(ChannelReader<string> reader, CancellationToken ct)
+    {
+        string first;
+        try
+        {
+            first = await reader.ReadAsync(ct);
+        }
+        catch (OperationCanceledException)
+        {
+            return null;
+        }
+        var batch = new List<string> { first };
+        while (true)
+        {
+            try { await Task.Delay(300, ct); } catch (OperationCanceledException) { return null; }
+            bool any = false;
+            while (reader.TryRead(out var more))
+            {
+                batch.Add(more);
+                any = true;
+            }
+            if (!any) return batch;
+        }
+    }
+
+    /// <summary>
+    /// A recursive *.sql FileSystemWatcher over a directory, feeding full paths into the channel.
+    /// </summary>
+    public static FileSystemWatcher NewSqlWatcher(string fullDir, ChannelWriter<string> writer)
+    {
+        var w = new FileSystemWatcher(fullDir, "*.sql")
+        {
+            IncludeSubdirectories = true,
+            NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.FileName | NotifyFilters.Size,
+        };
+        void OnFsEvent(object s, FileSystemEventArgs e) => writer.TryWrite(e.FullPath);
+        w.Changed += OnFsEvent;
+        w.Created += OnFsEvent;
+        w.Renamed += (s, e) => writer.TryWrite(e.FullPath);
+        w.EnableRaisingEvents = true;
+        return w;
+    }
+
+    /// <summary>
+    /// True when the ecosystem-standard DOTNET_USE_POLLING_FILE_WATCHER is set — the escape hatch for
+    /// environments where inotify events don't cross the filesystem boundary (Docker Desktop bind mounts,
+    /// some network shares).
+    /// </summary>
+    public static bool UsePollingWatcher =>
+        Environment.GetEnvironmentVariable("DOTNET_USE_POLLING_FILE_WATCHER") is { } v
+        && (v == "1" || string.Equals(v, "true", StringComparison.OrdinalIgnoreCase));
+
+    /// <summary>
+    /// Polling fallback: scans *.sql under <paramref name="fullDir"/> plus the extra files every second
+    /// and writes changed/new paths into the channel. Runs until the token is cancelled.
+    /// </summary>
+    public static void StartPollingWatcher(string fullDir, IReadOnlyList<string> extraFiles, ChannelWriter<string> writer, CancellationToken ct)
+    {
+        _ = Task.Run(async () =>
+        {
+            var known = new Dictionary<string, DateTime>(StringComparer.Ordinal);
+            void Scan(bool emit)
+            {
+                IEnumerable<string> files = Directory.Exists(fullDir)
+                    ? Directory.EnumerateFiles(fullDir, "*.sql", SearchOption.AllDirectories)
+                    : [];
+                foreach (var f in files.Concat(extraFiles))
+                {
+                    DateTime mtime;
+                    try { mtime = File.GetLastWriteTimeUtc(f); } catch { continue; }
+                    if (known.TryGetValue(f, out var prev))
+                    {
+                        if (prev != mtime)
+                        {
+                            known[f] = mtime;
+                            if (emit) writer.TryWrite(f);
+                        }
+                    }
+                    else
+                    {
+                        known[f] = mtime;
+                        if (emit) writer.TryWrite(f);
+                    }
+                }
+            }
+            Scan(emit: false);
+            while (ct.IsCancellationRequested is false)
+            {
+                try { await Task.Delay(1000, ct); } catch (OperationCanceledException) { break; }
+                Scan(emit: true);
+            }
+        }, CancellationToken.None);
+    }
+}
diff --git a/changelog/v3.19.0.md b/changelog/v3.19.0.md
index 0e4a24d1..93cf8561 100644
--- a/changelog/v3.19.0.md
+++ b/changelog/v3.19.0.md
@@ -1,10 +1,10 @@
 # Changelog v3.19.0
 
-## Version [3.19.0](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.19.0) (2026-07-02)
+## Version [3.19.0](https://github.com/NpgsqlRest/NpgsqlRest/tree/3.19.0) (2026-07-03)
 
 [Full Changelog](https://github.com/NpgsqlRest/NpgsqlRest/compare/3.18.2...3.19.0)
 
-This release introduces the **SQL test runner** (`npgsqlrest --test`) — write tests for your endpoints as plain `.sql` files, invoke endpoints in-process from inside a test, and assert on both the HTTP response and the database state, all within the test's own transaction. Also included: a **skip glob for the SQL file source** and the ability to **mute an individual logger**.
+This release introduces the **SQL test runner** (`npgsqlrest --test`) — write tests for your endpoints as plain `.sql` files, invoke endpoints in-process from inside a test, and assert on both the HTTP response and the database state, all within the test's own transaction. Also included: **watch mode** (`--watch` — re-run tests or restart the server on SQL and configuration changes), **named parameters in SQL files** (`:name`), a **skip glob for the SQL file source**, and the ability to **mute an individual logger**.
 
 ---
 
@@ -163,13 +163,17 @@ Run-once steps around the whole test session. **`Setup` runs before endpoint dis
 Steps can be defined once in the **`Steps` registry** (name → step, like `ConnectionStrings` or `CacheOptions.Profiles`) and referenced by name; `Setup`/`Teardown` arrays accept names and inline objects mixed. Referencing an unknown name is a configuration error (exit 3).
 
 ```jsonc
-"Steps": {
-  "CreateDatabase":  { "Sql": "create database app_test_{rnd5}", "ConnectionName": "Admin" },
-  "ApplyMigrations": { "SqlFile": "./migrations/schema.sql" },
-  "DropDatabase":    { "Sql": "drop database if exists app_test_{rnd5} with (force)", "ConnectionName": "Admin" }
-},
-"Setup":    ["CreateDatabase", "ApplyMigrations"],
-"Teardown": ["DropDatabase"]
+{
+  "TestRunner": {
+    "Steps": {
+      "CreateDatabase":  { "Sql": "create database app_test_{rnd5}", "ConnectionName": "Admin" },
+      "ApplyMigrations": { "SqlFile": "./migrations/schema.sql" },
+      "DropDatabase":    { "Sql": "drop database if exists app_test_{rnd5} with (force)", "ConnectionName": "Admin" }
+    },
+    "Setup":    ["CreateDatabase", "ApplyMigrations"],
+    "Teardown": ["DropDatabase"]
+  }
+}
 ```
 
 ### Per-file setup, teardown, and connection (header annotations)
@@ -200,21 +204,23 @@ Together these give **per-test database isolation**: a file's setup clones a mig
 `TestRunner.ConnectionName` points the whole test session — endpoint type-checking (SQL-file Describe), endpoint execution, and the tests — at a named `ConnectionStrings` entry instead of the app's main connection. That database **need not exist at startup**: it is never opened before Setup, so the first Setup step can create it.
 
 ```jsonc
-"ConnectionStrings": {
-  "Default": "Host={PGHOST};Database=appdb;...",                     // the real app DB — untouched by tests
-  "Admin":   "Host={PGHOST};Database=postgres;...",                  // maintenance (needs CREATEDB)
-  "Test":    "Host={PGHOST};Database=app_test_{rnd6};..."            // the throwaway test DB
-},
-"TestRunner": {
-  "ConnectionName": "Test",
-  "FilePattern": "./tests/**/*.test.sql",
-  "Steps": {
-    "CreateDatabase":  { "Sql": "create database app_test_{rnd6}", "ConnectionName": "Admin" },
-    "ApplyMigrations": { "SqlFile": "./migrations/schema.sql" },     // runs on "Test"
-    "DropDatabase":    { "Sql": "drop database if exists app_test_{rnd6} with (force)", "ConnectionName": "Admin" }
+{
+  "ConnectionStrings": {
+    "Default": "Host={PGHOST};Database=appdb;...",                     // the real app DB — untouched by tests
+    "Admin":   "Host={PGHOST};Database=postgres;...",                  // maintenance (needs CREATEDB)
+    "Test":    "Host={PGHOST};Database=app_test_{rnd6};..."            // the throwaway test DB
   },
-  "Setup":    ["CreateDatabase", "ApplyMigrations"],
-  "Teardown": ["DropDatabase"]
+  "TestRunner": {
+    "ConnectionName": "Test",
+    "FilePattern": "./tests/**/*.test.sql",
+    "Steps": {
+      "CreateDatabase":  { "Sql": "create database app_test_{rnd6}", "ConnectionName": "Admin" },
+      "ApplyMigrations": { "SqlFile": "./migrations/schema.sql" },     // runs on "Test"
+      "DropDatabase":    { "Sql": "drop database if exists app_test_{rnd6} with (force)", "ConnectionName": "Admin" }
+    },
+    "Setup":    ["CreateDatabase", "ApplyMigrations"],
+    "Teardown": ["DropDatabase"]
+  }
 }
 ```
 
@@ -253,40 +259,44 @@ The runner logs through its own channel — **`NpgsqlRestTest`** (configurable v
 - `raise notice`/`warning` from the database — logged **by their severity**, tagged with the test file that emitted them.
 
 ```jsonc
-"Log": { "MinimalLevels": { "NpgsqlRest": "Off", "NpgsqlRestClient": "Off", "NpgsqlRestTest": "Verbose" } }
+{
+  "Log": { "MinimalLevels": { "NpgsqlRest": "Off", "NpgsqlRestClient": "Off", "NpgsqlRestTest": "Verbose" } }
+}
 ```
 
 ### Configuration reference (`TestRunner` section)
 
 ```jsonc
-"TestRunner": {
-  "FilePattern": "",                    // glob selecting test files (same engine as SqlFileSource); empty disables
-  "Filter": "",                         // narrow the discovered set: substring, or glob when it contains wildcards
-  "Tag": "",                            // run only files carrying at least one of these tags (-- @tag name ...)
-  "ExcludeTag": "",                     // skip files carrying any of these tags (wins over Tag)
-  "ConnectionName": "",                 // ConnectionStrings entry to test against; empty = the main connection
-  "MaxParallelism": 0,                  // concurrent test files; 0 = processor count
-  "FailFast": false,                    // stop scheduling new files after the first failure (in-flight finish)
-  "PerTestTimeout": "30s",              // per-file timeout: "30s", "5m", "1h", plain seconds, "hh:mm:ss"; 0 disables
-  "JUnitOutput": null,                  // optional path for a JUnit XML report
-  "Keep": false,                        // skip Teardown (inspect state after a failed run)
-  "DetailedReport": false,              // detailed console report: passed ✓ lines, full failing SQL, notices for passing tests
-  "AllowEmpty": false,                  // exit 0 instead of 4 when no tests are found
-  "Watch": false,                       // watch mode (CLI: --watch): re-run on file changes until Ctrl+C; teardown on exit
-  "Coverage": null,                     // coverage summary: null (default) = on for full runs, quiet when narrowed; true/false = always/never
-  "CoverageThreshold": null,            // 0-100: always report + fail an otherwise-passing run (exit 2) below it
-  "LoggerName": "NpgsqlRestTest",       // the runner's log channel (leveled via Log:MinimalLevels)
-  "ResponseTempTable": {
-    "Name": "_response",                // table name when a file has ONE HTTP block
-    "MultiNamePattern": "_response_{n}",// name pattern for 2+ blocks; {n} = 1-based block position
-    "Columns": {                        // response → column mapping; null/empty omits the column
-      "Status": "status", "Body": "body", "ContentType": "content_type",
-      "Headers": "headers", "IsSuccess": "is_success"
-    }
-  },
-  "Steps": {},                          // named, reusable steps (name → step) for Setup/Teardown and -- @setup/-- @teardown
-  "Setup": [],                          // run-once, BEFORE endpoint discovery, in written order (step names or inline objects)
-  "Teardown": []                        // run-once, ALWAYS, in written order (Keep skips; same entries as Setup)
+{
+  "TestRunner": {
+    "FilePattern": "",                    // glob selecting test files (same engine as SqlFileSource); empty disables
+    "Filter": "",                         // narrow the discovered set: substring, or glob when it contains wildcards
+    "Tag": "",                            // run only files carrying at least one of these tags (-- @tag name ...)
+    "ExcludeTag": "",                     // skip files carrying any of these tags (wins over Tag)
+    "ConnectionName": "",                 // ConnectionStrings entry to test against; empty = the main connection
+    "MaxParallelism": 0,                  // concurrent test files; 0 = processor count
+    "FailFast": false,                    // stop scheduling new files after the first failure (in-flight finish)
+    "PerTestTimeout": "30s",              // per-file timeout: "30s", "5m", "1h", plain seconds, "hh:mm:ss"; 0 disables
+    "JUnitOutput": null,                  // optional path for a JUnit XML report
+    "Keep": false,                        // skip Teardown (inspect state after a failed run)
+    "DetailedReport": false,              // detailed console report: passed ✓ lines, full failing SQL, notices for passing tests
+    "AllowEmpty": false,                  // exit 0 instead of 4 when no tests are found
+    "Watch": false,                       // watch mode (CLI: --watch): re-run on file changes until Ctrl+C; teardown on exit
+    "Coverage": null,                     // coverage summary: null (default) = on for full runs, quiet when narrowed; true/false = always/never
+    "CoverageThreshold": null,            // 0-100: always report + fail an otherwise-passing run (exit 2) below it
+    "LoggerName": "NpgsqlRestTest",       // the runner's log channel (leveled via Log:MinimalLevels)
+    "ResponseTempTable": {
+      "Name": "_response",                // table name when a file has ONE HTTP block
+      "MultiNamePattern": "_response_{n}",// name pattern for 2+ blocks; {n} = 1-based block position
+      "Columns": {                        // response → column mapping; null/empty omits the column
+        "Status": "status", "Body": "body", "ContentType": "content_type",
+        "Headers": "headers", "IsSuccess": "is_success"
+      }
+    },
+    "Steps": {},                          // named, reusable steps (name → step) for Setup/Teardown and -- @setup/-- @teardown
+    "Setup": [],                          // run-once, BEFORE endpoint discovery, in written order (step names or inline objects)
+    "Teardown": []                        // run-once, ALWAYS, in written order (Keep skips; same entries as Setup)
+  }
 }
 ```
 
@@ -384,7 +394,43 @@ What you get:
 
 **Why not `?` (JDBC style)?** Considered and rejected: `?`, `?|`, `?&`, and `@?` are PostgreSQL's own jsonb/geometric operators — `where data ? 'admin'` is legal, common SQL that no rewriter can reliably tell apart from a parameter. This is the same reason the PostgreSQL JDBC driver requires `??` escapes. Anonymous-positional already exists as `$N`.
 
-## 4. Mute an individual logger with `"Off"` in `Log:MinimalLevels`
+## 4. Watch mode: `--watch`
+
+The `--watch` flag runs in one of **two modes**, depending on whether `--test` is present:
+
+| Command | Mode | Watches | On change |
+|---|---|---|---|
+| `npgsqlrest ... --test --watch` | **Test watch** | test files, included fixtures/profiles, and — when the SQL file source is enabled — the endpoint SQL files | changed test re-runs alone; endpoint change rebuilds endpoints in-process and re-runs everything |
+| `npgsqlrest ... --watch` | **Server watch** | the SQL file source tree and the configuration files | the server restarts (~1s) |
+
+Test watch works with or without a SQL file source (database-routine endpoints are testable too — they are just not watchable) and is described in the test runner section above. Server watch requires an **enabled SQL file source** — `--watch` without it (and without `--test`) has nothing to watch and exits with an error.
+
+### Server watch
+
+```sh
+npgsqlrest ./config.json --watch
+```
+
+Run the **server** under a watcher: edit a SQL file and the running API restarts with the change applied (~1s) — add an endpoint and it's immediately callable, break one and the error is on screen while the rest of the API keeps serving, and any configured code generation (TypeScript client, HTTP files, OpenAPI) regenerates on every restart, so the frontend's types follow your SQL as you type.
+
+**How it works.** The process becomes a small **supervisor** that spawns itself as a child server (marked by an environment variable) and watches the `SqlFileSource` tree plus the **configuration files themselves**. On a debounced change it stops the child gracefully and starts a fresh one — the child runs the completely normal server pipeline, so dev is byte-for-byte production behavior (the same model as `dotnet watch`). One relaxation: in the watch child, `SqlFileSource.ErrorMode` is forced from `Exit` to `Skip`, so a broken file logs its error and drops only its own endpoint instead of taking the server down.
+
+Behavior:
+
+| Event | Result |
+|---|---|
+| `.sql` change under the source tree | restart (files matching `SkipPattern` — test files — are ignored) |
+| configuration file change | restart with the new configuration |
+| broken SQL file | restart; the error is logged, that endpoint drops, everything else serves |
+| child crashes/exits on its own | supervisor prints `server exited (code N) — waiting for file changes` and revives on the next save (no crash-looping) |
+| Ctrl+C / SIGTERM (`docker stop`) | child stopped gracefully, both processes exit, port freed |
+| supervisor killed hard (SIGKILL) | the child detects the vanished parent and exits by itself — no orphan holding the port |
+
+Graceful child stop uses SIGTERM on Linux/macOS; on Windows the child is hard-killed (nothing needs teardown in a dev server). For environments where file events don't cross the filesystem boundary — Docker Desktop bind mounts, network shares — set the ecosystem-standard `DOTNET_USE_POLLING_FILE_WATCHER=1` to switch to a 1-second polling scan (applies to both watch modes).
+
+Works in every distribution: the AOT executables (the supervisor respawns `Environment.ProcessPath`), framework-dependent `dotnet NpgsqlRestClient.dll` (the dotnet host is re-invoked with the dll), and both Docker image flavors (the supervisor handles PID-1 signal and child-reaping duties).
+
+## 5. Mute an individual logger with `"Off"` in `Log:MinimalLevels`
 
 Each entry under **`Log:MinimalLevels`** now accepts **`"Off"`** (aliases **`"None"`** and **`"Silent"`**, case-insensitive) to **fully silence** that logger. Previously the only accepted values were the Serilog levels `Verbose…Fatal`, and there was no way to turn a logger off completely.
 
@@ -394,11 +440,13 @@ Each entry under **`Log:MinimalLevels`** now accepts **`"Off"`** (aliases **`"No
 Each named logger is controlled independently — e.g. mute the application loggers entirely while watching the test runner:
 
 ```json
-"Log": {
-  "MinimalLevels": {
-    "NpgsqlRest": "Off",
-    "NpgsqlRestClient": "Off",
-    "NpgsqlRestTest": "Verbose"
+{
+  "Log": {
+    "MinimalLevels": {
+      "NpgsqlRest": "Off",
+      "NpgsqlRestClient": "Off",
+      "NpgsqlRestTest": "Verbose"
+    }
   }
 }
 ```

From ba18c7493b339b800e8174ac1d317009e3aa924f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Fri, 3 Jul 2026 19:40:52 +0200
Subject: [PATCH 21/25] feat(watch): database routine polling + one Watch
 config section for both flavors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Watch mode now watches ALL endpoint sources in BOTH flavors. Routine-source
endpoints (functions/procedures) have no files to watch, so watch mode polls
the DATABASE — with perfect fidelity: RoutineSource.CreateFingerprintCommand
runs the SAME discovery query the endpoint source uses (same Query property,
same ten configured filter parameters — refactored into a shared command
builder used by Read() too), wrapped in an order-independent server-side hash
(select sum(hashtextextended(q::text,0)) from (<query>) q). If the hash
changes, the discovered endpoints changed — by definition: create/replace/
drop/alter of functions and procedures (function bodies are in the result via
pg_get_functiondef), GRANT/REVOKE, COMMENT ON (annotations), and changes to
the composite types and tables used as parameter/return types. Anything the
discovery query does not read — unrelated tables, temp objects, data — can
never cause a spurious trigger.

- WatchDbPoller (client): polls on a dedicated non-pooled connection, takes
  the actual configured RoutineSource instances from EndpointSources; skips
  cleanly when there are none. Rebaseline() prevents self-triggering.
- Server watch: the child polls and exits with code 64 -> the supervisor
  respawns immediately ("database change detected — restarting"). Supervisor
  loop reworked so the pending change batch survives respawn iterations (no
  competing channel readers). Routines-only projects are now watchable:
  --watch is valid without a SQL file source when polling is active.
- Test watch: the poller feeds a sentinel into the existing change channel ->
  endpoint rebuild + full rerun ("change detected (database)"); the runner
  re-baselines after every rerun so committed fixtures never re-trigger.

Config consolidated into ONE top-level Watch section (TestRunner.Watch
REMOVED — it was the same word with a different type and role):

    "Watch": { "Enabled": false, "DatabasePollingInterval": "2s" }

--watch is the CLI shorthand for Watch:Enabled (--watch:enabled=true also
works); the flavor is picked by --test. Polling accepts "2s"/"500ms"/"1m"/
seconds/hh:mm:ss, 0 disables, and deactivates automatically when
RoutineOptions.Enabled is false. Config synced x4 + schema descriptions.

Tests: WatchDbFingerprintTests proves the hash tracks the discovery result
exactly (create/replace/comment/drop and used-type changes fire; temp objects
and unrelated tables never do; nameSimilarTo filter wiring verified). Full
suite green (2394). Live-verified: function created in psql serving ~2s
later on a routines-only watch; replace -> new body; drop -> 404; alter table
add column reshaping a `returns setof` endpoint ([{"id":1}] ->
[{"id":1,"name":"ada"}]); unrelated table create/drop -> zero restarts;
test-watch database rerun without loops; all four activation paths
(server/test x flag/config). Changelog: watch section finalized.
---
 NpgsqlRest/RoutineSource.cs                   |  61 ++++++----
 NpgsqlRestClient/Builder.cs                   |   5 +-
 NpgsqlRestClient/ConfigDefaults.cs            |   6 +-
 NpgsqlRestClient/ConfigSchemaGenerator.cs     |   3 +-
 NpgsqlRestClient/ConfigTemplate.cs            |  34 ++++--
 NpgsqlRestClient/Program.cs                   |  36 ++++--
 NpgsqlRestClient/Testing/TestRunner.cs        |  31 ++++-
 NpgsqlRestClient/Testing/TestRunnerOptions.cs |  10 +-
 NpgsqlRestClient/WatchDbPoller.cs             | 106 ++++++++++++++++++
 NpgsqlRestClient/WatchSupervisor.cs           |  96 ++++++++++++----
 NpgsqlRestClient/appsettings.json             |  34 ++++--
 NpgsqlRestTests/WatchDbFingerprintTests.cs    |  75 +++++++++++++
 changelog/v3.19.0.md                          |  33 ++++--
 13 files changed, 440 insertions(+), 90 deletions(-)
 create mode 100644 NpgsqlRestClient/WatchDbPoller.cs
 create mode 100644 NpgsqlRestTests/WatchDbFingerprintTests.cs

diff --git a/NpgsqlRest/RoutineSource.cs b/NpgsqlRest/RoutineSource.cs
index 09d8b1e8..20c2e649 100644
--- a/NpgsqlRest/RoutineSource.cs
+++ b/NpgsqlRest/RoutineSource.cs
@@ -45,6 +45,44 @@ public class RoutineSource(
     /// </summary>
     public bool ResolveNestedCompositeTypes { get; set; } = resolveNestedCompositeTypes;
 
+    /// <summary>
+    /// The discovery command (query text + the ten filter parameters, each resolved against this source
+    /// or the global options) — shared by <see cref="Read"/> and <see cref="CreateFingerprintCommand"/>.
+    /// With <paramref name="fingerprint"/> the SAME query is wrapped in an order-independent server-side
+    /// hash of its result rows: if the hash changes, the discovered endpoints changed — by definition.
+    /// </summary>
+    private NpgsqlCommand CreateSourceCommand(NpgsqlConnection connection, bool fingerprint)
+    {
+        var command = connection.CreateCommand();
+        Query ??= RoutineSourceQuery.Query;
+        var text = Query.Contains(Consts.Space) is false
+            ? string.Concat("select * from ", Query, "($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)")
+            : Query;
+        command.CommandText = fingerprint
+            ? string.Concat("select coalesce(sum(hashtextextended(q::text, 0)), 0)::text from (", text, ") q")
+            : text;
+
+        command.AddParameter(SchemaSimilarTo ?? Options.SchemaSimilarTo); // $1
+        command.AddParameter(SchemaNotSimilarTo ?? Options.SchemaNotSimilarTo); // $2
+        command.AddParameter(IncludeSchemas ?? Options.IncludeSchemas, true); // $3
+        command.AddParameter(ExcludeSchemas ?? Options.ExcludeSchemas, true); // $4
+        command.AddParameter(NameSimilarTo ?? Options.NameSimilarTo); // $5
+        command.AddParameter(NameNotSimilarTo ?? Options.NameNotSimilarTo); // $6
+        command.AddParameter(IncludeNames ?? Options.IncludeNames, true); // $7
+        command.AddParameter(ExcludeNames ?? Options.ExcludeNames, true); // $8
+        command.AddParameter(IncludeLanguages, true); // $9
+        command.AddParameter(ExcludeLanguages is null ? ["c", "internal"] : ExcludeLanguages, true); // $10
+        return command;
+    }
+
+    /// <summary>
+    /// A command returning one text value: a hash of this source's ENTIRE discovery result (same query,
+    /// same configured filters). Watch mode polls it to detect any change to the discovered endpoints —
+    /// routines, their comments/annotations, and the composite/table types their signatures use.
+    /// </summary>
+    public NpgsqlCommand CreateFingerprintCommand(NpgsqlConnection connection)
+        => CreateSourceCommand(connection, fingerprint: true);
+
     public IEnumerable<(Routine, IRoutineSourceParameterFormatter)> Read(IServiceProvider? serviceProvider, RetryStrategy? retryStrategy)
     {
         bool shouldDispose = true;
@@ -64,28 +102,7 @@ public class RoutineSource(
                 CompositeTypeCache.Initialize(connection, Options.NameConverter);
             }
 
-            using var command = connection.CreateCommand();
-            Query ??= RoutineSourceQuery.Query;
-            if (Query.Contains(Consts.Space) is false)
-            {
-                command.CommandText = string.Concat("select * from ", Query, "($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)");
-            }
-            else
-            {
-                command.CommandText = Query;
-            }
-
-            command.AddParameter(SchemaSimilarTo ?? Options.SchemaSimilarTo); // $1
-            command.AddParameter(SchemaNotSimilarTo ?? Options.SchemaNotSimilarTo); // $2
-            command.AddParameter(IncludeSchemas ?? Options.IncludeSchemas, true); // $3
-            command.AddParameter(ExcludeSchemas ?? Options.ExcludeSchemas, true); // $4
-            command.AddParameter(NameSimilarTo ?? Options.NameSimilarTo); // $5
-            command.AddParameter(NameNotSimilarTo ?? Options.NameNotSimilarTo); // $6
-            command.AddParameter(IncludeNames ?? Options.IncludeNames, true); // $7
-            command.AddParameter(ExcludeNames ?? Options.ExcludeNames, true); // $8
-            command.AddParameter(IncludeLanguages, true); // $9
-            command.AddParameter(ExcludeLanguages is null ? ["c", "internal"] : ExcludeLanguages, true); // $10
-
+            using var command = CreateSourceCommand(connection, fingerprint: false);
             command.LogCommand(nameof(RoutineSource));
             using NpgsqlDataReader reader = command.ExecuteReaderWithRetry(retryStrategy);
             while (reader.Read())
diff --git a/NpgsqlRestClient/Builder.cs b/NpgsqlRestClient/Builder.cs
index a2590046..8f1c8dbd 100644
--- a/NpgsqlRestClient/Builder.cs
+++ b/NpgsqlRestClient/Builder.cs
@@ -3075,11 +3075,12 @@ public TestRunnerOptions BuildTestRunnerOptions()
         opt.MaxParallelism = _config.GetConfigInt("MaxParallelism", section) ?? 0;
         opt.FailFast = _config.GetConfigBool("FailFast", section, false);
         opt.PerTestTimeout = ParseTestTimeout(_config.GetConfigStr("PerTestTimeout", section), TimeSpan.FromSeconds(30));
+        opt.DatabasePollingInterval = ParseTestTimeout(
+            _config.GetConfigStr("DatabasePollingInterval", _config.Cfg.GetSection("Watch")), TimeSpan.FromSeconds(2));
         opt.JUnitOutput = _config.GetConfigStr("JUnitOutput", section);
         opt.Keep = _config.GetConfigBool("Keep", section, false);
         opt.DetailedReport = _config.GetConfigBool("DetailedReport", section, false);
         opt.AllowEmpty = _config.GetConfigBool("AllowEmpty", section, false);
-        opt.Watch = _config.GetConfigBool("Watch", section, false);
         opt.CoverageThreshold = _config.GetConfigInt("CoverageThreshold", section);
         // Tri-state: absent/empty => null (report after full runs only); explicit true/false honored.
         if (string.IsNullOrEmpty(section.GetSection("Coverage").Value) is false)
@@ -3179,7 +3180,7 @@ List<TestSetupStep> ReadTestSteps(IConfigurationSection stepsSection)
         }
     }
 
-    private static TimeSpan ParseTestTimeout(string? raw, TimeSpan def)
+    internal static TimeSpan ParseTestTimeout(string? raw, TimeSpan def)
     {
         if (string.IsNullOrWhiteSpace(raw)) return def;
         raw = raw.Trim();
diff --git a/NpgsqlRestClient/ConfigDefaults.cs b/NpgsqlRestClient/ConfigDefaults.cs
index 8ccc6117..537fb66e 100644
--- a/NpgsqlRestClient/ConfigDefaults.cs
+++ b/NpgsqlRestClient/ConfigDefaults.cs
@@ -174,6 +174,11 @@ public static JsonObject GetDefaults()
             ["HealthChecks"] = GetHealthChecksDefaults(),
             ["Stats"] = GetStatsDefaults(),
             ["TestRunner"] = GetTestRunnerDefaults(),
+            ["Watch"] = new JsonObject
+            {
+                ["Enabled"] = false,
+                ["DatabasePollingInterval"] = "2s",
+            },
             ["CommandRetryOptions"] = GetCommandRetryOptionsDefaults(),
             ["CacheOptions"] = GetCacheOptionsDefaults(),
             ["ValidationOptions"] = GetValidationOptionsDefaults(),
@@ -1112,7 +1117,6 @@ private static JsonObject GetTestRunnerDefaults()
             ["Keep"] = false,
             ["DetailedReport"] = false,
             ["AllowEmpty"] = false,
-            ["Watch"] = false,
             ["Coverage"] = null,
             ["CoverageThreshold"] = null,
             ["LoggerName"] = "NpgsqlRestTest",
diff --git a/NpgsqlRestClient/ConfigSchemaGenerator.cs b/NpgsqlRestClient/ConfigSchemaGenerator.cs
index 163cccdb..4636a6f3 100644
--- a/NpgsqlRestClient/ConfigSchemaGenerator.cs
+++ b/NpgsqlRestClient/ConfigSchemaGenerator.cs
@@ -259,9 +259,10 @@ public static partial class ConfigSchemaGenerator
         ["TestRunner:Keep"] = "Skip Teardown so a failed run's state can be inspected.",
         ["TestRunner:DetailedReport"] = "Detailed console REPORT: list passed assertions, print the full failing SQL statement, and show captured `raise notice` output for passing tests too.\nThis shapes the report only — for diagnostic logging of every executed query/HTTP call, raise the log channel instead (Log:MinimalLevels + LoggerName).",
         ["TestRunner:AllowEmpty"] = "Treat \"no tests discovered\" as success (exit 0) instead of exit 4.",
-        ["TestRunner:Watch"] = "Watch mode (interactive/dev-only; CLI flag: --watch): run everything once, then re-run on file changes until Ctrl+C.\nA changed test file re-runs alone; a changed ENDPOINT file (SqlFileSource FilePattern) rebuilds the endpoints in-process (delta reported; ErrorMode forced Exit->Skip so a broken file cannot kill the session) and re-runs everything; any other changed .sql under the test tree (e.g. an included fixture) re-runs everything. Teardown runs once, on exit; a graceful stop exits 0 (not for CI gating).",
         ["TestRunner:Coverage"] = "Endpoint-coverage summary after the run: exercised N of M testable endpoints + the list of untested ones (endpoint kinds the runner rejects — SSE, upload, login/logout, outbound proxy — are excluded from the ratio and counted separately).\nTri-state: null (default) reports after FULL runs but stays quiet when the run is narrowed by Filter/Tag; true always reports; false never.",
         ["TestRunner:CoverageThreshold"] = "Fail an otherwise-passing run with exit 2 when endpoint coverage is below this percentage (0-100) — CI gating for \"every endpoint has a test\". Always reports coverage when set, regardless of the Coverage setting or run narrowing. Null = no gate.",
+        ["Watch:Enabled"] = "Turn watch mode on (interactive/dev-only; the --watch command line flag is the shorthand for this setting).\nWith --test: re-run tests on changes (changed test file re-runs alone; changed endpoint file or database routine rebuilds endpoints in-process and re-runs everything; teardown once, on exit). Without --test: supervise the server and restart it on SQL file source, configuration, and database routine changes.",
+        ["Watch:DatabasePollingInterval"] = "Watch mode (both --watch flavors): poll the database for routine changes and restart the server (server watch) or rebuild endpoints and re-run tests (test watch).\nRuns the SAME routine discovery query the endpoint source uses (same configured filters), hashed server-side — detecting exactly what changes discovered endpoints: functions/procedures, grants, COMMENT ON annotations, and the composite/table types their signatures use. Accepts \"2s\", \"500ms\", \"1m\", plain seconds, or \"hh:mm:ss\"; 0 disables.",
         ["TestRunner:LoggerName"] = "SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels (defaults to Information).\nDiscovery/parsing log at Debug, each query and HTTP invocation at Verbose, `raise notice` by severity. The console PASS/FAIL report is separate.",
         ["TestRunner:ResponseTempTable:Name"] = "Temp table name used when a test file has exactly ONE HTTP block.\nEach HTTP block gets its own fresh temp table (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified. Per-block override: `# @response <name>`.",
         ["TestRunner:ResponseTempTable:MultiNamePattern"] = "Temp table name pattern used when a test file has 2+ HTTP blocks.\n{n} is the 1-based block ordinal, e.g. \"_response_{n}\" => _response_1, _response_2, …",
diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index 4ec7f671..18119364 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -1502,15 +1502,6 @@ public static partial class ConfigSchemaGenerator
         //
         "AllowEmpty": false,
         //
-        // Watch mode (interactive/dev-only; CLI flag: --watch): run everything once, then re-run on file
-        // changes until Ctrl+C. A changed test file re-runs alone; a changed ENDPOINT file (SqlFileSource
-        // FilePattern) rebuilds the endpoints in-process (delta reported; ErrorMode forced Exit->Skip so a
-        // broken file cannot kill the session) and re-runs everything; any other changed .sql under the test
-        // tree (e.g. an included fixture) re-runs everything. Teardown runs once, on exit; a graceful stop
-        // exits 0 (not for CI gating).
-        //
-        "Watch": false,
-        //
         // Endpoint-coverage summary after the run: exercised N of M testable endpoints + the list of untested
         // ones (endpoint kinds the runner rejects — SSE, upload, login/logout, outbound proxy — are excluded
         // from the ratio and counted separately). Tri-state: null (default) reports after FULL runs but stays
@@ -1569,6 +1560,31 @@ public static partial class ConfigSchemaGenerator
         "Teardown": []
       },
 
+      //
+      // Watch mode (interactive/dev-only) — one feature, two flavors: with --test it re-runs tests on
+      // changes (a changed test file re-runs alone; a changed endpoint file or database routine rebuilds
+      // endpoints in-process and re-runs everything; teardown runs once, on exit); without --test it
+      // supervises the SERVER and restarts it on SQL file source, configuration, and database routine
+      // changes. In both flavors a broken SQL file cannot kill the session (SqlFileSource ErrorMode is
+      // forced from Exit to Skip while watching).
+      //
+      "Watch": {
+        //
+        // Turn watch mode on. The --watch command line flag is the shorthand for this setting.
+        //
+        "Enabled": false,
+        //
+        // Poll the database for routine changes and restart the server (server watch) or rebuild endpoints and
+        // re-run the tests (test watch). The poll runs the SAME routine discovery query the endpoint source
+        // uses (same configured filters), hashed server-side into one value — so it detects exactly what
+        // changes discovered endpoints: functions/procedures (create/replace/drop/alter, grants), their
+        // COMMENT ON annotations, and the composite types and tables their signatures use; anything the
+        // discovery does not read can never trigger. Accepts "2s", "500ms", "1m", a plain number of seconds,
+        // or "hh:mm:ss"; 0 disables. One query per interval on a dedicated non-pooled connection.
+        //
+        "DatabasePollingInterval": "2s"
+      },
+
       //
       // Command retry strategies and options for client and middleware commands.
       //
diff --git a/NpgsqlRestClient/Program.cs b/NpgsqlRestClient/Program.cs
index 641524ab..a7b46c66 100644
--- a/NpgsqlRestClient/Program.cs
+++ b/NpgsqlRestClient/Program.cs
@@ -272,15 +272,17 @@
 
 bool endpointsMode = args.Any(a => string.Equals(a, "--endpoints", StringComparison.OrdinalIgnoreCase));
 bool testMode = args.Any(a => string.Equals(a, "--test", StringComparison.OrdinalIgnoreCase));
-// Watch mode (interactive re-run loop). Needed this early because it relaxes SqlFileSource error handling
-// (a broken endpoint file must not kill the watch session — see CreateEndpointSources).
-bool watchMode = testMode && (args.Any(a => string.Equals(a, "--watch", StringComparison.OrdinalIgnoreCase))
-    || config.GetConfigBool("Watch", config.Cfg.GetSection("TestRunner")));
-
-// Server watch mode (--watch WITHOUT --test): this process becomes a supervisor that spawns itself as
+// Watch mode — one feature, two flavors chosen by --test. The --watch flag is shorthand for
+// Watch:Enabled. Needed this early because it relaxes SqlFileSource error handling (a broken endpoint
+// file must not kill the watch session — see CreateEndpointSources).
+bool watchRequested = args.Any(a => string.Equals(a, "--watch", StringComparison.OrdinalIgnoreCase))
+    || config.GetConfigBool("Enabled", config.Cfg.GetSection("Watch"));
+bool watchMode = testMode && watchRequested;
+
+// Server watch (--watch WITHOUT --test): this process becomes a supervisor that spawns itself as
 // a child server and restarts it on SQL/config file changes; the child (marked by an env variable)
 // falls through and runs the normal server pipeline. See WatchSupervisor.
-if (testMode is false && args.Any(a => string.Equals(a, "--watch", StringComparison.OrdinalIgnoreCase)))
+if (testMode is false && watchRequested)
 {
     if (WatchSupervisor.IsChild is false)
     {
@@ -733,4 +735,24 @@
     }
 }
 
+// Server watch child: poll the routine discovery query (hashed server-side, same configured filters)
+// and request a restart (exit code 64 -> the supervisor respawns immediately) when its result changes —
+// routines, their comments (annotations), and the types their signatures use are invisible to a file watcher.
+if (WatchSupervisor.IsChild)
+{
+    var dbPollInterval = NpgsqlRestClient.Builder.ParseTestTimeout(
+        config.GetConfigStr("DatabasePollingInterval", config.Cfg.GetSection("Watch")), TimeSpan.FromSeconds(2));
+    var routineSources = options.EndpointSources.OfType<NpgsqlRest.RoutineSource>().ToArray();
+    if (dbPollInterval > TimeSpan.Zero && routineSources.Length > 0)
+    {
+        var dbPoller = new WatchDbPoller(connectionString!, dbPollInterval, onChange: () =>
+        {
+            builder.ClientLogger?.LogInformation("watch: database change detected — restarting");
+            Environment.ExitCode = WatchSupervisor.DbChangeExitCode;
+            app.Lifetime.StopApplication();
+        }, builder.ClientLogger, routineSources);
+        _ = dbPoller.RunAsync(app.Lifetime.ApplicationStopping);
+    }
+}
+
 app.Run();
diff --git a/NpgsqlRestClient/Testing/TestRunner.cs b/NpgsqlRestClient/Testing/TestRunner.cs
index 23c1c237..94729fa9 100644
--- a/NpgsqlRestClient/Testing/TestRunner.cs
+++ b/NpgsqlRestClient/Testing/TestRunner.cs
@@ -25,6 +25,9 @@ public sealed class TestRunner
     // Indentation is written OUTSIDE the style so the grey block starts at the text. Escapes are emitted
     // only on a real terminal (see Out).
     public const string AnsiFail = "\x1b[38;5;197m\x1b[48;5;238m";
+
+    // Channel sentinel written by the database poller (not a real path — NUL is invalid in paths).
+    private const string DbChangeSentinel = "\u0000database";
     private const string AnsiOk = "\x1b[38;5;47m\x1b[48;5;238m";
     private const string AnsiPlain = "\x1b[0m";
 
@@ -455,10 +458,23 @@ FileSystemWatcher NewWatcher(string dir)
                 && !endpointBaseFull.StartsWith(testBaseFull, StringComparison.Ordinal);
             using var endpointWatcher = separateEndpointTree ? NewWatcher(endpointBaseFull!) : null;
 
+            // Database polling: routine changes (create/replace/drop/comment, signature types) have no
+            // file to watch — a poller on the test connection runs the routine discovery query hashed
+            // server-side and feeds a sentinel into the same channel, triggering a rebuild + full rerun.
+            WatchDbPoller? dbPoller = null;
+            var routineSources = _rest.EndpointSources.OfType<RoutineSource>().ToArray();
+            if (_opt.DatabasePollingInterval > TimeSpan.Zero && routineSources.Length > 0)
+            {
+                dbPoller = new WatchDbPoller(_connString, _opt.DatabasePollingInterval,
+                    onChange: () => changes.Writer.TryWrite(DbChangeSentinel), _log, routineSources);
+                _ = dbPoller.RunAsync(stop.Token);
+            }
+
             var watching = Path.GetRelativePath(Environment.CurrentDirectory, testBaseFull)
                 + (endpointBaseFull is not null && endpointBaseFull != testBaseFull
                     ? $" + {Path.GetRelativePath(Environment.CurrentDirectory, endpointBaseFull)} (endpoints)"
-                    : "");
+                    : "")
+                + (dbPoller is not null ? $" + database (poll {_opt.DatabasePollingInterval.TotalSeconds:0.#}s)" : "");
             _out.Line($"\nwatching {watching} for changes — Ctrl+C to stop", ConsoleColor.Cyan);
 
             while (!stop.IsCancellationRequested)
@@ -474,6 +490,12 @@ FileSystemWatcher NewWatcher(string dir)
                 bool rebuild = false;
                 foreach (var path in changed)
                 {
+                    if (string.Equals(path, DbChangeSentinel, StringComparison.Ordinal))
+                    {
+                        // Routines changed in the database: re-describe (rebuild) and re-run everything.
+                        if (rebuildEndpoints is not null) rebuild = true; else runAll = true;
+                        continue;
+                    }
                     var rel = Path.GetRelativePath(Environment.CurrentDirectory, path).Replace('\\', '/');
                     if (MatchesCwdRelativePattern(rel, _opt.FilePattern))
                     {
@@ -491,7 +513,9 @@ FileSystemWatcher NewWatcher(string dir)
                 }
                 if (!rebuild && !runAll && testFiles.Count == 0) continue; // e.g. only deletions
 
-                var trigger = Path.GetRelativePath(Environment.CurrentDirectory, changed[0]);
+                var trigger = string.Equals(changed[0], DbChangeSentinel, StringComparison.Ordinal)
+                    ? "database"
+                    : Path.GetRelativePath(Environment.CurrentDirectory, changed[0]);
                 _out.Line($"\n— {DateTime.Now:HH:mm:ss} change detected ({trigger}{(changed.Count > 1 ? $" +{changed.Count - 1}" : "")}) —", ConsoleColor.Cyan);
 
                 if (rebuild)
@@ -516,6 +540,9 @@ FileSystemWatcher NewWatcher(string dir)
                 }
 
                 await ExecuteDiscoveredFilesAsync(endpoints, lookup, only: runAll ? null : testFiles.Distinct().ToList(), stop.Token);
+                // The rerun itself may have changed the database (committed fixtures, per-file steps) —
+                // re-baseline so self-inflicted changes never trigger another rerun.
+                dbPoller?.Rebaseline();
                 _out.Line($"\nwatching — Ctrl+C to stop", ConsoleColor.Cyan);
             }
             return ExitPass;
diff --git a/NpgsqlRestClient/Testing/TestRunnerOptions.cs b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
index 014dbd3f..e1ff374a 100644
--- a/NpgsqlRestClient/Testing/TestRunnerOptions.cs
+++ b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
@@ -75,13 +75,11 @@ public class TestRunnerOptions
     public bool AllowEmpty { get; set; } = false;
 
     /// <summary>
-    /// Watch mode (interactive/dev-only; CLI: <c>--watch</c>): run everything once, then re-run on file
-    /// changes until Ctrl+C. A changed test file re-runs alone; a changed ENDPOINT file (SqlFileSource
-    /// FilePattern) rebuilds the endpoints in-process (delta reported) and re-runs everything; any other
-    /// changed .sql under the test tree re-runs everything (an included fixture's dependents are unknown).
-    /// Teardown runs once, on exit; graceful exit code is 0.
+    /// Watch mode only: poll the test database's catalog for routine changes (create/replace/drop/alter
+    /// of functions/procedures, COMMENT ON) and rebuild endpoints + re-run everything when it changes.
+    /// Read from the shared top-level Watch:DatabasePollingInterval setting; zero disables.
     /// </summary>
-    public bool Watch { get; set; } = false;
+    public TimeSpan DatabasePollingInterval { get; set; } = TimeSpan.FromSeconds(2);
 
     /// <summary>
     /// SourceContext name for the runner's own log channel — discovery/parsing at Debug, each query and HTTP
diff --git a/NpgsqlRestClient/WatchDbPoller.cs b/NpgsqlRestClient/WatchDbPoller.cs
new file mode 100644
index 00000000..b36f6230
--- /dev/null
+++ b/NpgsqlRestClient/WatchDbPoller.cs
@@ -0,0 +1,106 @@
+using System.Text;
+using Microsoft.Extensions.Logging;
+using Npgsql;
+using NpgsqlRest;
+
+namespace NpgsqlRestClient;
+
+/// <summary>
+/// Database change detection for watch mode. There is no filesystem to watch for routine-source
+/// endpoints — instead, the poller runs the SAME discovery query the routine source uses (same
+/// configured filters — see <see cref="RoutineSource.CreateFingerprintCommand"/>), hashed server-side
+/// into one scalar, on a dedicated non-pooled connection. If the hash changes, the discovered
+/// endpoints changed — by definition: create/replace/drop/alter of functions and procedures, grants,
+/// COMMENT ON (annotations), schema renames, and changes to the composite/table types their signatures
+/// use. Anything the query does not read (an unrelated table, temp objects, data) can never trigger.
+/// </summary>
+public sealed class WatchDbPoller(
+    string connectionString,
+    TimeSpan interval,
+    Action onChange,
+    ILogger? logger,
+    IReadOnlyList<RoutineSource> sources)
+{
+    private readonly string _connString = new NpgsqlConnectionStringBuilder(connectionString) { Pooling = false }.ConnectionString;
+    private NpgsqlConnection? _conn;
+    private string? _baseline;
+    private volatile bool _rebaseline;
+
+    /// <summary>Fingerprint of one source's discovery result on an open connection (also used by tests).</summary>
+    public static string? GetFingerprint(NpgsqlConnection connection, RoutineSource source)
+    {
+        using var cmd = source.CreateFingerprintCommand(connection);
+        return cmd.ExecuteScalar() as string;
+    }
+
+    /// <summary>
+    /// Forget the baseline so the next tick captures a fresh one WITHOUT firing. Called after work
+    /// that legitimately changes the database (a test rerun with committed fixtures, a restart) so
+    /// self-inflicted changes never trigger.
+    /// </summary>
+    public void Rebaseline() => _rebaseline = true;
+
+    /// <summary>Poll loop; runs until cancelled. Connection failures skip the tick and retry.</summary>
+    public async Task RunAsync(CancellationToken ct)
+    {
+        if (sources.Count == 0)
+        {
+            return;
+        }
+        while (ct.IsCancellationRequested is false)
+        {
+            try
+            {
+                await Task.Delay(interval, ct);
+            }
+            catch (OperationCanceledException)
+            {
+                break;
+            }
+            try
+            {
+                if (_conn is null || _conn.State != System.Data.ConnectionState.Open)
+                {
+                    _conn?.Dispose();
+                    _conn = new NpgsqlConnection(_connString);
+                    await _conn.OpenAsync(ct);
+                }
+                var sb = new StringBuilder();
+                foreach (var source in sources)
+                {
+                    await using var cmd = source.CreateFingerprintCommand(_conn);
+                    sb.Append(await cmd.ExecuteScalarAsync(ct) as string).Append('|');
+                }
+                var current = sb.ToString();
+                if (_rebaseline)
+                {
+                    _rebaseline = false;
+                    _baseline = current;
+                    continue;
+                }
+                if (_baseline is null)
+                {
+                    _baseline = current;
+                    continue;
+                }
+                if (string.Equals(_baseline, current, StringComparison.Ordinal) is false)
+                {
+                    _baseline = current;
+                    onChange();
+                }
+            }
+            catch (OperationCanceledException)
+            {
+                break;
+            }
+            catch (Exception ex)
+            {
+                // DB down / restarting: skip this tick, reconnect on the next one.
+                logger?.LogDebug("watch: database poll failed ({Message}) — retrying", ex.Message);
+                try { _conn?.Dispose(); } catch { }
+                _conn = null;
+            }
+        }
+        try { _conn?.Dispose(); } catch { }
+    }
+}
diff --git a/NpgsqlRestClient/WatchSupervisor.cs b/NpgsqlRestClient/WatchSupervisor.cs
index 829caa9b..c93ebaf6 100644
--- a/NpgsqlRestClient/WatchSupervisor.cs
+++ b/NpgsqlRestClient/WatchSupervisor.cs
@@ -31,6 +31,9 @@ public static class WatchSupervisor
 
     public static bool IsChild { get; } = string.IsNullOrEmpty(Environment.GetEnvironmentVariable(ChildEnv)) is false;
 
+    /// <summary>Child exit code meaning "the database poller detected a change — respawn me immediately".</summary>
+    public const int DbChangeExitCode = 64;
+
     // Blittable signature — plain DllImport is AOT-safe here and avoids AllowUnsafeBlocks.
     [DllImport("libc", SetLastError = true, EntryPoint = "kill")]
     private static extern int kill(int pid, int sig);
@@ -70,31 +73,47 @@ public static async Task<int> RunAsync(Config config, string[] args)
     {
         var output = new Out();
 
-        // Something to watch? Server watch requires an enabled SqlFileSource (database routines have no
-        // files to watch — a change in the database needs a manual restart either way).
+        // Something to watch? A SqlFileSource tree, database catalog polling, or both.
         var sqlFileCfg = config.NpgsqlRestCfg.GetSection("SqlFileSource");
         string? filePattern = null;
         if (sqlFileCfg.Exists() && config.GetConfigBool("Enabled", sqlFileCfg, true))
         {
             filePattern = config.GetConfigStr("FilePattern", sqlFileCfg);
         }
-        if (string.IsNullOrWhiteSpace(filePattern))
+        // Database polling (the child does the actual polling by hashing the routine discovery query;
+        // the supervisor needs the value for validation and the banner). With polling active, --watch is
+        // valid even without a SQL file source — a routines-only project restarts on create/replace/drop/
+        // comment. Polling is only meaningful when the routine source itself is enabled.
+        var dbPollInterval = Builder.ParseTestTimeout(
+            config.GetConfigStr("DatabasePollingInterval", config.Cfg.GetSection("Watch")), TimeSpan.FromSeconds(2));
+        var routineOptionsCfg = config.NpgsqlRestCfg.GetSection("RoutineOptions");
+        if (routineOptionsCfg.Exists() && config.GetConfigBool("Enabled", routineOptionsCfg, true) is false)
         {
-            output.LineAnsi(
-                "watch: nothing to watch — --watch without --test requires an enabled SqlFileSource with a FilePattern. For test watch mode use --test --watch.",
-                Testing.TestRunner.AnsiFail);
-            return 1;
+            dbPollInterval = TimeSpan.Zero;
+        }
+
+        string? baseDirFull = null;
+        var skipPattern = "*.test.sql";
+        if (string.IsNullOrWhiteSpace(filePattern) is false)
+        {
+            var baseDir = WatchUtils.GetWatchBaseDir(filePattern);
+            if (baseDir is null)
+            {
+                output.LineAnsi(
+                    $"watch: cannot watch — SqlFileSource FilePattern \"{filePattern}\" has no existing base directory.",
+                    Testing.TestRunner.AnsiFail);
+                return 1;
+            }
+            baseDirFull = Path.GetFullPath(baseDir);
+            skipPattern = (config.GetConfigStr("SkipPattern", sqlFileCfg) ?? "*.test.sql").Replace('\\', '/');
         }
-        var baseDir = WatchUtils.GetWatchBaseDir(filePattern);
-        if (baseDir is null)
+        else if (dbPollInterval <= TimeSpan.Zero)
         {
             output.LineAnsi(
-                $"watch: cannot watch — SqlFileSource FilePattern \"{filePattern}\" has no existing base directory.",
+                "watch: nothing to watch — --watch without --test requires an enabled SqlFileSource with a FilePattern and/or database polling (Watch:DatabasePollingInterval). For test watch mode use --test --watch.",
                 Testing.TestRunner.AnsiFail);
             return 1;
         }
-        var baseDirFull = Path.GetFullPath(baseDir);
-        var skipPattern = (config.GetConfigStr("SkipPattern", sqlFileCfg) ?? "*.test.sql").Replace('\\', '/');
 
         // Config files restart the server too: the .json/.jsonc files passed on the command line, plus
         // the implicit default when present.
@@ -130,11 +149,14 @@ void OnSignal(PosixSignalContext ctx)
         bool polling = WatchUtils.UsePollingWatcher;
         if (polling)
         {
-            WatchUtils.StartPollingWatcher(baseDirFull, configFiles, changes.Writer, stop.Token);
+            WatchUtils.StartPollingWatcher(baseDirFull ?? "", configFiles, changes.Writer, stop.Token);
         }
         else
         {
-            watchers.Add(WatchUtils.NewSqlWatcher(baseDirFull, changes.Writer));
+            if (baseDirFull is not null)
+            {
+                watchers.Add(WatchUtils.NewSqlWatcher(baseDirFull, changes.Writer));
+            }
             foreach (var dir in configFiles.Select(Path.GetDirectoryName).Where(d => d is not null).Distinct(StringComparer.Ordinal))
             {
                 var w = new FileSystemWatcher(dir!)
@@ -156,32 +178,56 @@ void OnFsEvent(object s, FileSystemEventArgs e)
             }
         }
 
-        var watchingWhat = $"{Path.GetRelativePath(Environment.CurrentDirectory, baseDirFull)} (*.sql)"
-            + (configFiles.Count > 0 ? " + config files" : "")
-            + (polling ? " [polling]" : "");
+        var watchingParts = new List<string>(3);
+        if (baseDirFull is not null)
+        {
+            watchingParts.Add($"{Path.GetRelativePath(Environment.CurrentDirectory, baseDirFull)} (*.sql)");
+        }
+        if (configFiles.Count > 0)
+        {
+            watchingParts.Add("config files");
+        }
+        if (dbPollInterval > TimeSpan.Zero)
+        {
+            watchingParts.Add($"database (poll {dbPollInterval.TotalSeconds:0.#}s)");
+        }
+        var watchingWhat = string.Join(" + ", watchingParts) + (polling ? " [polling]" : "");
         output.Line($"watch mode: supervising the server process, watching {watchingWhat} — Ctrl+C to stop", ConsoleColor.Cyan);
 
         Process child = Spawn(args);
         Task exitTask = child.WaitForExitAsync(CancellationToken.None);
+        // The pending batch survives iterations that don't consume it (e.g. a database-change respawn),
+        // so the channel never has two competing readers.
+        Task<List<string>?>? pendingBatch = null;
 
         try
         {
             while (stopping is false)
             {
-                var batchTask = WatchUtils.NextChangeBatchAsync(changes.Reader, stop.Token);
-                var completed = await Task.WhenAny(exitTask, batchTask);
+                pendingBatch ??= WatchUtils.NextChangeBatchAsync(changes.Reader, stop.Token);
+                var completed = await Task.WhenAny(exitTask, pendingBatch);
 
                 if (stopping)
                 {
                     break;
                 }
 
-                if (completed == exitTask && batchTask.IsCompleted is false)
+                if (completed == exitTask && pendingBatch.IsCompleted is false)
                 {
+                    if (child.ExitCode == DbChangeExitCode)
+                    {
+                        // The child's database poller detected a routine/annotation change and asked to be
+                        // restarted.
+                        output.Line($"\n— {DateTime.Now:HH:mm:ss} database change detected — restarting —", ConsoleColor.Cyan);
+                        child = Spawn(args);
+                        exitTask = child.WaitForExitAsync(CancellationToken.None);
+                        continue;
+                    }
                     // The child died on its own (crash, config error, port conflict). Don't respawn in a
                     // loop — hold until the next file change, then try again.
                     output.Line($"\nserver exited (code {child.ExitCode}) — waiting for file changes", ConsoleColor.Yellow);
-                    var wakeBatch = await batchTask;
+                    var wakeBatch = await pendingBatch;
+                    pendingBatch = null;
                     if (wakeBatch is null || stopping)
                     {
                         break;
@@ -197,7 +243,8 @@ void OnFsEvent(object s, FileSystemEventArgs e)
                     continue;
                 }
 
-                var batch = await batchTask;
+                var batch = await pendingBatch;
+                pendingBatch = null;
                 if (batch is null)
                 {
                     break;
@@ -229,7 +276,7 @@ void OnFsEvent(object s, FileSystemEventArgs e)
     /// SqlFileSource FilePattern and does NOT match SkipPattern (a test-file edit must not bounce the
     /// server).
     /// </summary>
-    private static string? Relevant(List<string> batch, string baseDirFull, string skipPattern, HashSet<string> configFileSet)
+    private static string? Relevant(List<string> batch, string? baseDirFull, string skipPattern, HashSet<string> configFileSet)
     {
         foreach (var path in batch.Distinct(StringComparer.Ordinal))
         {
@@ -239,7 +286,8 @@ void OnFsEvent(object s, FileSystemEventArgs e)
             {
                 return rel;
             }
-            if (full.StartsWith(baseDirFull, StringComparison.Ordinal)
+            if (baseDirFull is not null
+                && full.StartsWith(baseDirFull, StringComparison.Ordinal)
                 && rel.EndsWith(".sql", StringComparison.OrdinalIgnoreCase)
                 && WatchUtils.MatchesCwdRelativePattern(rel, skipPattern) is false)
             {
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index 5a8cccba..450ada4e 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -1493,15 +1493,6 @@
     //
     "AllowEmpty": false,
     //
-    // Watch mode (interactive/dev-only; CLI flag: --watch): run everything once, then re-run on file
-    // changes until Ctrl+C. A changed test file re-runs alone; a changed ENDPOINT file (SqlFileSource
-    // FilePattern) rebuilds the endpoints in-process (delta reported; ErrorMode forced Exit->Skip so a
-    // broken file cannot kill the session) and re-runs everything; any other changed .sql under the test
-    // tree (e.g. an included fixture) re-runs everything. Teardown runs once, on exit; a graceful stop
-    // exits 0 (not for CI gating).
-    //
-    "Watch": false,
-    //
     // Endpoint-coverage summary after the run: exercised N of M testable endpoints + the list of untested
     // ones (endpoint kinds the runner rejects — SSE, upload, login/logout, outbound proxy — are excluded
     // from the ratio and counted separately). Tri-state: null (default) reports after FULL runs but stays
@@ -1560,6 +1551,31 @@
     "Teardown": []
   },
 
+  //
+  // Watch mode (interactive/dev-only) — one feature, two flavors: with --test it re-runs tests on
+  // changes (a changed test file re-runs alone; a changed endpoint file or database routine rebuilds
+  // endpoints in-process and re-runs everything; teardown runs once, on exit); without --test it
+  // supervises the SERVER and restarts it on SQL file source, configuration, and database routine
+  // changes. In both flavors a broken SQL file cannot kill the session (SqlFileSource ErrorMode is
+  // forced from Exit to Skip while watching).
+  //
+  "Watch": {
+    //
+    // Turn watch mode on. The --watch command line flag is the shorthand for this setting.
+    //
+    "Enabled": false,
+    //
+    // Poll the database for routine changes and restart the server (server watch) or rebuild endpoints and
+    // re-run the tests (test watch). The poll runs the SAME routine discovery query the endpoint source
+    // uses (same configured filters), hashed server-side into one value — so it detects exactly what
+    // changes discovered endpoints: functions/procedures (create/replace/drop/alter, grants), their
+    // COMMENT ON annotations, and the composite types and tables their signatures use; anything the
+    // discovery does not read can never trigger. Accepts "2s", "500ms", "1m", a plain number of seconds,
+    // or "hh:mm:ss"; 0 disables. One query per interval on a dedicated non-pooled connection.
+    //
+    "DatabasePollingInterval": "2s"
+  },
+
   //
   // Command retry strategies and options for client and middleware commands.
   //
diff --git a/NpgsqlRestTests/WatchDbFingerprintTests.cs b/NpgsqlRestTests/WatchDbFingerprintTests.cs
new file mode 100644
index 00000000..cbb81929
--- /dev/null
+++ b/NpgsqlRestTests/WatchDbFingerprintTests.cs
@@ -0,0 +1,75 @@
+using Npgsql;
+using NpgsqlRest;
+using NpgsqlRestClient;
+
+namespace NpgsqlRestTests;
+
+[Collection("TestFixture")]
+public class WatchDbFingerprintTests
+{
+    [Fact]
+    public void Fingerprint_TracksDiscoveryResult_Exactly()
+    {
+        using var conn = Database.CreateConnection();
+        conn.Open();
+        void Exec(string sql)
+        {
+            using var c = conn.CreateCommand();
+            c.CommandText = sql;
+            c.ExecuteNonQuery();
+        }
+        // The fingerprint is the routine discovery query itself, hashed server-side — so it tracks the
+        // discovered endpoints by definition, with the source's configured filters applied.
+        var source = new RoutineSource(nameSimilarTo: "watch\\_fp\\_%");
+        string Fp() => WatchDbPoller.GetFingerprint(conn, source)!;
+
+        Exec("drop function if exists watch_fp_test_fn(int)");
+        Exec("drop table if exists watch_fp_typed cascade");
+        var fp0 = Fp();
+        fp0.Should().NotBeNullOrEmpty();
+
+        // create function → changes
+        Exec("create function watch_fp_test_fn(a int) returns int language sql as 'select a'");
+        var fp1 = Fp();
+        fp1.Should().NotBe(fp0, "creating a function must change the fingerprint");
+
+        // replace body → changes (the result includes pg_get_functiondef)
+        Exec("create or replace function watch_fp_test_fn(a int) returns int language sql as 'select a + 1'");
+        var fp2 = Fp();
+        fp2.Should().NotBe(fp1, "replacing a function body must change the fingerprint");
+
+        // comment = annotations → changes
+        Exec("comment on function watch_fp_test_fn(int) is 'HTTP GET'");
+        var fp3 = Fp();
+        fp3.Should().NotBe(fp2, "COMMENT ON a function (annotations) must change the fingerprint");
+
+        // temp table → must NOT change
+        Exec("create temp table watch_fp_tmp(id int)");
+        var fp4 = Fp();
+        fp4.Should().Be(fp3, "temp objects must not look like a database change");
+
+        // a table NOT used by any discovered routine → must NOT change (precision: the discovery
+        // result doesn't mention it, so the hash cannot move)
+        Exec("drop table if exists watch_fp_unrelated");
+        Exec("create table watch_fp_unrelated(id int)");
+        var fp5 = Fp();
+        fp5.Should().Be(fp4, "an unrelated table is not part of the discovery result");
+        Exec("drop table watch_fp_unrelated");
+
+        // a table USED as a return type → its shape is part of the result: altering it changes the endpoint
+        Exec("create table watch_fp_typed(id int)");
+        Exec("create function watch_fp_typed_fn() returns setof watch_fp_typed language sql as 'select * from watch_fp_typed'");
+        var fp6 = Fp();
+        fp6.Should().NotBe(fp5, "a new routine (returning a table type) must change the fingerprint");
+        Exec("alter table watch_fp_typed add column name text");
+        var fp7 = Fp();
+        fp7.Should().NotBe(fp6, "adding a column to a table used as a return type reshapes the endpoint");
+
+        // cleanup; drops → change
+        Exec("drop function watch_fp_typed_fn()");
+        Exec("drop table watch_fp_typed");
+        Exec("drop function watch_fp_test_fn(int)");
+        var fp8 = Fp();
+        fp8.Should().NotBe(fp7, "dropping functions must change the fingerprint");
+    }
+}
diff --git a/changelog/v3.19.0.md b/changelog/v3.19.0.md
index 93cf8561..302763d8 100644
--- a/changelog/v3.19.0.md
+++ b/changelog/v3.19.0.md
@@ -281,7 +281,6 @@ The runner logs through its own channel — **`NpgsqlRestTest`** (configurable v
     "Keep": false,                        // skip Teardown (inspect state after a failed run)
     "DetailedReport": false,              // detailed console report: passed ✓ lines, full failing SQL, notices for passing tests
     "AllowEmpty": false,                  // exit 0 instead of 4 when no tests are found
-    "Watch": false,                       // watch mode (CLI: --watch): re-run on file changes until Ctrl+C; teardown on exit
     "Coverage": null,                     // coverage summary: null (default) = on for full runs, quiet when narrowed; true/false = always/never
     "CoverageThreshold": null,            // 0-100: always report + fail an otherwise-passing run (exit 2) below it
     "LoggerName": "NpgsqlRestTest",       // the runner's log channel (leveled via Log:MinimalLevels)
@@ -333,7 +332,7 @@ endpoint coverage: 1/2 (50%)
 
 Endpoint kinds the runner rejects (SSE, upload, login/logout, outbound proxy) are excluded from the ratio and counted separately, so the number is honest. **`CoverageThreshold`** (0–100) turns it into a CI gate — it always reports, regardless of the `Coverage` setting or run narrowing: an otherwise-passing run below the threshold exits `2` — set it to `100` and forgetting to write a test for a new endpoint fails the build, naming the endpoint. "Covered" means *invoked at least once by a test* — execution, not assertion depth (the same semantics as code coverage).
 
-**Watch mode** (`--watch`, or `TestRunner:Watch`) keeps the process alive and re-runs on change — and because the endpoint middleware is built once at startup, re-runs are near-instant:
+**Watch mode** (`--watch`, or `Watch:Enabled` in configuration) keeps the process alive and re-runs on change — and because the endpoint middleware is built once at startup, re-runs are near-instant:
 
 ```
 npgsqlrest ./config.json ./test-config.json --test --watch
@@ -396,14 +395,33 @@ What you get:
 
 ## 4. Watch mode: `--watch`
 
-The `--watch` flag runs in one of **two modes**, depending on whether `--test` is present:
+The `--watch` flag — shorthand for the `Watch:Enabled` configuration setting — runs in one of **two modes**, depending on whether `--test` is present:
 
 | Command | Mode | Watches | On change |
 |---|---|---|---|
-| `npgsqlrest ... --test --watch` | **Test watch** | test files, included fixtures/profiles, and — when the SQL file source is enabled — the endpoint SQL files | changed test re-runs alone; endpoint change rebuilds endpoints in-process and re-runs everything |
-| `npgsqlrest ... --watch` | **Server watch** | the SQL file source tree and the configuration files | the server restarts (~1s) |
+| `npgsqlrest ... --test --watch` | **Test watch** | test files, included fixtures/profiles, the endpoint SQL files (when the SQL file source is enabled), and **the database catalog** | changed test re-runs alone; endpoint or database change rebuilds endpoints in-process and re-runs everything |
+| `npgsqlrest ... --watch` | **Server watch** | the SQL file source tree, the configuration files, and **the database catalog** | the server restarts (~1s) |
 
-Test watch works with or without a SQL file source (database-routine endpoints are testable too — they are just not watchable) and is described in the test runner section above. Server watch requires an **enabled SQL file source** — `--watch` without it (and without `--test`) has nothing to watch and exits with an error.
+Test watch is described in the test runner section above. Server watch needs something to watch — an **enabled SQL file source**, **database polling** (on by default, below), or both; with neither, `--watch` without `--test` exits with an error.
+
+### Watching the routine source — database polling
+
+Routine-source endpoints (functions and procedures) have no files to watch — so watch mode polls the **database** instead, and it does it with perfect fidelity: the poll runs the **same routine discovery query the endpoint source uses**, with the same configured filters (schema/name/language includes and excludes), hashed server-side into a single value on a dedicated non-pooled connection (default every `2s`). If the hash changes, the discovered endpoints changed — *by definition*. That covers `create`/`create or replace`/`drop`/`alter` of functions and procedures (including `GRANT`/`REVOKE`), **`COMMENT ON` — i.e. annotation changes**, and changes to the **composite types and tables used as parameter or return types** (`alter table users add column` reshapes a `returns setof users` endpoint even though no function changed). Just as importantly, anything the discovery query does *not* read — an unrelated table, temp objects, data changes — can never cause a spurious restart. Any detected change triggers the same path a file change does: server watch restarts the server, test watch rebuilds endpoints in-process and re-runs the tests (`— change detected (database) —`); the test runner re-baselines after every rerun so self-inflicted changes never re-trigger.
+
+This makes a **routines-only** project fully watchable: run `npgsqlrest ./config.json --watch`, then `create or replace` a function in psql — the endpoint is live about two seconds later, annotations included.
+
+The whole feature lives in **one top-level configuration section** (the `--watch` flag is the shorthand for `Watch:Enabled`):
+
+```json
+{
+  "Watch": {
+    "Enabled": false,
+    "DatabasePollingInterval": "2s"
+  }
+}
+```
+
+`DatabasePollingInterval` accepts `"2s"`, `"500ms"`, `"1m"`, plain seconds, or `"hh:mm:ss"`; `0` disables polling. Both settings apply to both watch flavors.
 
 ### Server watch
 
@@ -421,6 +439,7 @@ Behavior:
 |---|---|
 | `.sql` change under the source tree | restart (files matching `SkipPattern` — test files — are ignored) |
 | configuration file change | restart with the new configuration |
+| database routine change (detected by polling, above) | restart — `— database change detected — restarting —` |
 | broken SQL file | restart; the error is logged, that endpoint drops, everything else serves |
 | child crashes/exits on its own | supervisor prints `server exited (code N) — waiting for file changes` and revives on the next save (no crash-looping) |
 | Ctrl+C / SIGTERM (`docker stop`) | child stopped gracefully, both processes exit, port freed |
@@ -460,4 +479,4 @@ Each named logger is controlled independently — e.g. mute the application logg
 
 ## Tests
 
-Full test suite green (2393), including 63 unit tests for the test-file, HTTP-block, header-annotation, and include parsers plus the filter and tag matchers (`NpgsqlRestTests/TestRunnerTests/ParserTests/`), and 29 for named SQL-file parameters — 22 rewriter unit tests (casts, `:=`, slices, strings, dollar-quotes, jsonb-path strings, case-insensitive repetition, cross-statement sharing, mixing detection, named type hints) plus 7 end-to-end endpoint tests (auto-naming through the camelCase converter, a repeated placeholder bound from one value, required-parameter matching, name-matched defaults, `type is` retype, claim mapping by placeholder name, mixed-style rejection, and a multi-command file sharing `:id` across statements as one API parameter). All three documentation examples verified end-to-end against live PostgreSQL — including example 21's template-clone workflow (template migrated once; the shared run database and **two parallel per-test isolated databases** cloned from it concurrently; deterministic sequence ids asserted independently in both clones; everything dropped on teardown), watch mode (single-file rerun on a test change, full rerun on a fixture change, teardown on SIGINT/SIGTERM), path and tag filtering (including tags carried through a profile include), and the coverage report with a failing threshold gate. The new configuration keys are covered by the configuration round-trip tests (the `--config` template output matches `appsettings.json`).
+Full test suite green (2394), including 63 unit tests for the test-file, HTTP-block, header-annotation, and include parsers plus the filter and tag matchers (`NpgsqlRestTests/TestRunnerTests/ParserTests/`), and 29 for named SQL-file parameters — 22 rewriter unit tests (casts, `:=`, slices, strings, dollar-quotes, jsonb-path strings, case-insensitive repetition, cross-statement sharing, mixing detection, named type hints) plus 7 end-to-end endpoint tests (auto-naming through the camelCase converter, a repeated placeholder bound from one value, required-parameter matching, name-matched defaults, `type is` retype, claim mapping by placeholder name, mixed-style rejection, and a multi-command file sharing `:id` across statements as one API parameter), plus a database-fingerprint test proving the watch poller's hash tracks the routine discovery result exactly (function create/replace/comment/drop and used-type changes fire; temp objects and unrelated tables never do). Watch mode verified live end-to-end in both flavors: file edit/break/fix cycles, config-change restarts, crash recovery, orphan prevention under SIGKILL, graceful SIGTERM teardown, polling-watcher mode, and database-driven changes (a function created in psql serving ~2s later; `alter table` reshaping a `returns setof` endpoint; unrelated tables causing zero restarts). All three documentation examples verified end-to-end against live PostgreSQL — including example 21's template-clone workflow (template migrated once; the shared run database and **two parallel per-test isolated databases** cloned from it concurrently; deterministic sequence ids asserted independently in both clones; everything dropped on teardown), watch mode (single-file rerun on a test change, full rerun on a fixture change, teardown on SIGINT/SIGTERM), path and tag filtering (including tags carried through a profile include), and the coverage report with a failing threshold gate. The new configuration keys are covered by the configuration round-trip tests (the `--config` template output matches `appsettings.json`).

From 76f4f56fbf344162b26c7387a366d64a97f77b14 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Fri, 3 Jul 2026 20:09:55 +0200
Subject: [PATCH 22/25] =?UTF-8?q?feat(test-runner):=20ResponseTempTable.De?=
 =?UTF-8?q?bugTable=20=E2=80=94=20permanent=20response=20debug=20mirror?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Captured responses live in per-connection temp tables that vanish with the
test's rollback and connection close — impossible to examine in a query
editor afterwards, and re-issuing the request from an .http file cannot
reproduce a response that depended on the test's uncommitted transactional
fixtures.

New setting ResponseTempTable.DebugTable (default null = off): when set
(e.g. "_responses_debug"), every captured response is ALSO mirrored into a
PERMANENT table with that name, written on a separate autocommit pooled
connection — immune to rollbacks and connection closes, append-only so
parallel test files cannot collide. The temp-table semantics (assertions,
naming, transactions) are completely unchanged.

ONE table covers the whole run: each HTTP block adds one row with
captured_at, test_file, block (that block's response-table name — Name, a
MultiNamePattern ordinal, or the # @response name), method, path, status,
body, content_type, headers, is_success. Recreated at the start of every
run, so it always holds the LAST run. Enabling it prints a loud warning
(debugging aid — do not enable in CI); mirror inserts are best-effort (a
failure logs a warning, never fails the test). In the fresh-test-database
workflow combine with Keep, or teardown drops the database and mirror.

Note: the naive alternative ("Permanent": true on the response table) was
rejected — parallel tests would collide on one permanent name, and CREATE
TABLE is transactional, so the rollback would erase the table exactly when
it was needed.

Config synced (appsettings.json, ConfigTemplate.cs, ConfigDefaults.cs,
ConfigSchemaGenerator.cs). Full suite green (2394). Live-verified on
example 19: all three block-naming schemes distinguishable in one query,
including the response body of a rolled-back fixture; rerun leaves exactly
the last run's rows. Changelog + docs updated.
---
 NpgsqlRestClient/Builder.cs                   |  1 +
 NpgsqlRestClient/ConfigDefaults.cs            |  1 +
 NpgsqlRestClient/ConfigSchemaGenerator.cs     |  1 +
 NpgsqlRestClient/ConfigTemplate.cs            | 12 +++
 NpgsqlRestClient/Testing/TestRunner.cs        | 90 ++++++++++++++++++-
 NpgsqlRestClient/Testing/TestRunnerOptions.cs | 13 +++
 NpgsqlRestClient/appsettings.json             |  2 +
 changelog/v3.19.0.md                          |  3 +
 8 files changed, 121 insertions(+), 2 deletions(-)

diff --git a/NpgsqlRestClient/Builder.cs b/NpgsqlRestClient/Builder.cs
index 8f1c8dbd..59702ecf 100644
--- a/NpgsqlRestClient/Builder.cs
+++ b/NpgsqlRestClient/Builder.cs
@@ -3093,6 +3093,7 @@ public TestRunnerOptions BuildTestRunnerOptions()
         {
             opt.ResponseTempTable.Name = _config.GetConfigStr("Name", rt) ?? opt.ResponseTempTable.Name;
             opt.ResponseTempTable.MultiNamePattern = _config.GetConfigStr("MultiNamePattern", rt) ?? opt.ResponseTempTable.MultiNamePattern;
+            opt.ResponseTempTable.DebugTable = _config.GetConfigStr("DebugTable", rt) ?? opt.ResponseTempTable.DebugTable;
             var cols = rt.GetSection("Columns");
             if (cols.Exists())
             {
diff --git a/NpgsqlRestClient/ConfigDefaults.cs b/NpgsqlRestClient/ConfigDefaults.cs
index 537fb66e..60eb888e 100644
--- a/NpgsqlRestClient/ConfigDefaults.cs
+++ b/NpgsqlRestClient/ConfigDefaults.cs
@@ -1124,6 +1124,7 @@ private static JsonObject GetTestRunnerDefaults()
             {
                 ["Name"] = "_response",
                 ["MultiNamePattern"] = "_response_{n}",
+                ["DebugTable"] = null,
                 ["Columns"] = new JsonObject
                 {
                     ["Status"] = "status",
diff --git a/NpgsqlRestClient/ConfigSchemaGenerator.cs b/NpgsqlRestClient/ConfigSchemaGenerator.cs
index 4636a6f3..dfceec1b 100644
--- a/NpgsqlRestClient/ConfigSchemaGenerator.cs
+++ b/NpgsqlRestClient/ConfigSchemaGenerator.cs
@@ -266,6 +266,7 @@ public static partial class ConfigSchemaGenerator
         ["TestRunner:LoggerName"] = "SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels (defaults to Information).\nDiscovery/parsing log at Debug, each query and HTTP invocation at Verbose, `raise notice` by severity. The console PASS/FAIL report is separate.",
         ["TestRunner:ResponseTempTable:Name"] = "Temp table name used when a test file has exactly ONE HTTP block.\nEach HTTP block gets its own fresh temp table (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified. Per-block override: `# @response <name>`.",
         ["TestRunner:ResponseTempTable:MultiNamePattern"] = "Temp table name pattern used when a test file has 2+ HTTP blocks.\n{n} is the 1-based block ordinal, e.g. \"_response_{n}\" => _response_1, _response_2, …",
+        ["TestRunner:ResponseTempTable:DebugTable"] = "Debugging aid: when set (e.g. \"_responses_debug\"), every captured response is ALSO mirrored into a PERMANENT table with this name — written on a separate autocommit connection, so it survives the test's rollback and connection close and can be examined in a query editor after the run.\nRecreated at the start of every run (holds the LAST run). ONE table covers everything: each HTTP block adds one row, with the block column recording that block's response-table name (Name, MultiNamePattern ordinal, or the # @response name) alongside test_file, method, path, status, body, content_type, headers, is_success, captured_at. Temp-table semantics unchanged. Do not enable in CI. Null (default) = off.",
         ["TestRunner:ResponseTempTable:Columns"] = "Maps each response component to a column name. A null or empty name omits that column.",
         ["TestRunner:Steps"] = "Named, reusable steps (name → step; same shape as Setup/Teardown entries). Reference them by name in Setup/Teardown, or from an individual test file's leading header comments:\n-- @setup StepName [StepName ...] (runs before that file); -- @teardown StepName [StepName ...] (runs after that file, always, best-effort); -- @connection Name (runs that file on a named ConnectionStrings entry).\nAnnotations are repeatable; names may be whitespace- or comma-separated and run in the order written.\nTest files can also reuse SQL scripts in place with psql-style includes: `\\i file` (cwd-relative) or `\\ir file` (relative to the including file) — executed on the test's connection, inside its transaction.",
         ["TestRunner:Setup"] = "Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written.\nEach entry is a step NAME from \"Steps\", or an inline object: { \"Command\": \"...\", \"WorkingDirectory\": \"...\" } (OS shell); { \"Sql\": \"...\" } | { \"SqlFile\": \"...\" } which run on the test connection, or set \"ConnectionName\" to run on another ConnectionStrings entry (e.g. an admin connection that runs `create database`).",
diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index 18119364..ff8d4ba8 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -1526,6 +1526,18 @@ public static partial class ConfigSchemaGenerator
         "ResponseTempTable": {
           "Name": "_response",
           "MultiNamePattern": "_response_{n}",
+          //
+          // Debugging aid: when set (e.g. "_responses_debug"), every captured response is ALSO mirrored into a
+          // PERMANENT table with this name — written on a separate autocommit connection, so it survives the
+          // test's rollback and the connection close and can be examined in a query editor after the run.
+          // Recreated at the start of every run (always holds the LAST run). ONE table covers everything: each
+          // HTTP block adds one row, and the "block" column records that block's response-table name (Name,
+          // MultiNamePattern ordinal, or the # @response name) alongside test_file, method, path, status, body,
+          // content_type, headers, is_success, captured_at. The temp-table semantics are unchanged. Do not
+          // enable in CI. In the fresh-test-database workflow combine with "Keep": true, or teardown drops the
+          // database (and the mirror with it).
+          //
+          "DebugTable": null,
           "Columns": {
             "Status": "status",
             "Body": "body",
diff --git a/NpgsqlRestClient/Testing/TestRunner.cs b/NpgsqlRestClient/Testing/TestRunner.cs
index 94729fa9..2fc9d9f7 100644
--- a/NpgsqlRestClient/Testing/TestRunner.cs
+++ b/NpgsqlRestClient/Testing/TestRunner.cs
@@ -44,6 +44,10 @@ public sealed class TestRunner
     private readonly NpgsqlRestOptions _rest;
     private readonly TestRunnerOptions _opt;
     private readonly string _connString;
+    // The debug mirror writes on its own POOLED connections (unlike test connections, which are
+    // deliberately non-pooled) — autocommit, outside any test transaction.
+    private readonly string _debugConnString;
+    private bool _debugTableWarned;
     private readonly IReadOnlyDictionary<string, string> _named;
     private readonly ILogger? _log;
     private readonly bool _logNotices;
@@ -108,6 +112,7 @@ public TestRunner(NpgsqlRestOptions rest, TestRunnerOptions opt, string baseConn
         // Always non-pooled: a fresh physical session per test (no temp-table / GUC / prepared-statement carryover).
         // In test mode baseConnectionString is already the test connection (TestRunner.ConnectionName, when set).
         _connString = new NpgsqlConnectionStringBuilder(baseConnectionString) { Pooling = false }.ConnectionString;
+        _debugConnString = baseConnectionString;
         // Named ConnectionStrings entries for Setup/Teardown steps that target another connection (e.g. an
         // "Admin" maintenance connection that runs create/drop database).
         _named = namedConnections ?? new Dictionary<string, string>();
@@ -239,6 +244,7 @@ private async Task<int> ExecuteDiscoveredFilesAsync(RoutineEndpoint[] endpoints,
     {
         _failFast = false; // reset per run (watch mode reuses the runner across iterations)
         if (only is null) _invoked.Clear(); // coverage counts per full run (partial watch reruns don't report)
+        await EnsureDebugTableAsync(ct); // debug mirror holds the LAST run — recreated per run
 
         var files = only ?? DiscoverFiles();
         if (only is null)
@@ -710,7 +716,7 @@ private async Task<FileResult> RunFileAsync(string file, IReadOnlyDictionary<str
                     else if (step is HttpStep http)
                     {
                         httpOrdinal++;
-                        sr = await InvokeHttpStepAsync(conn, http, ResolveResponseTable(http, httpOrdinal, httpTotal), lookup, ct);
+                        sr = await InvokeHttpStepAsync(conn, http, ResolveResponseTable(http, httpOrdinal, httpTotal), lookup, contextName, ct);
                     }
                     else
                     {
@@ -842,7 +848,7 @@ private async Task<StepResult> ExecuteSqlStepAsync(
     }
 
     private async Task<StepResult> InvokeHttpStepAsync(
-        NpgsqlConnection conn, HttpStep step, string responseTable, IReadOnlyDictionary<string, RoutineEndpoint> lookup, CancellationToken ct)
+        NpgsqlConnection conn, HttpStep step, string responseTable, IReadOnlyDictionary<string, RoutineEndpoint> lookup, string testFile, CancellationToken ct)
     {
         var httpName = $"{step.Method} {step.Path}";
         var pathOnly = StripQuery(step.Path);
@@ -894,6 +900,10 @@ private async Task<StepResult> InvokeHttpStepAsync(
             step.Method, step.Path, response.StatusCode, responseTable);
 
         await WriteResponseAsync(conn, responseTable, response, ct);
+        if (string.IsNullOrWhiteSpace(_opt.ResponseTempTable.DebugTable) is false)
+        {
+            await MirrorResponseAsync(testFile, responseTable, step, response, ct);
+        }
 
         // An HTTP block is an act step: it captures the response into the temp table and produces no test
         // of its own — the assertions are the boolean SELECTs that follow it. It only surfaces as a result
@@ -942,6 +952,82 @@ private async Task WriteResponseAsync(NpgsqlConnection conn, string table, Routi
         await ins.ExecuteNonQueryAsync(ct);
     }
 
+    /// <summary>
+    /// Debug mirror (ResponseTempTable.DebugTable): recreate the PERMANENT mirror table at the start of a
+    /// run and print the do-not-use-in-CI warning once. Runs on its own autocommit connection, so mirrored
+    /// rows survive test rollbacks and connection closes — that is the whole point.
+    /// </summary>
+    private async Task EnsureDebugTableAsync(CancellationToken ct)
+    {
+        var table = _opt.ResponseTempTable.DebugTable;
+        if (string.IsNullOrWhiteSpace(table))
+        {
+            return;
+        }
+        if (!ValidateIdentifier(table))
+        {
+            throw new InvalidOperationException($"invalid ResponseTempTable.DebugTable name '{table}'");
+        }
+        if (_debugTableWarned is false)
+        {
+            _debugTableWarned = true;
+            _out.Line($"WARNING: ResponseTempTable.DebugTable is enabled — every captured response is written to the PERMANENT table \"{table}\" (debugging aid; do not enable in CI)", ConsoleColor.Yellow);
+            _log?.LogWarning("ResponseTempTable.DebugTable enabled: mirroring responses into permanent table {Table}", table);
+        }
+        await using var conn = new NpgsqlConnection(_debugConnString);
+        await conn.OpenAsync(ct);
+        await using var cmd = conn.CreateCommand();
+        cmd.CommandText = $"""
+            drop table if exists "{table}";
+            create table "{table}" (
+                captured_at timestamptz not null default now(),
+                test_file text not null,
+                block text not null,
+                method text not null,
+                path text not null,
+                status int,
+                body text,
+                content_type text,
+                headers jsonb,
+                is_success boolean
+            )
+            """;
+        // The debug connection is plain Npgsql (SQL rewriting enabled is irrelevant here — no parameters),
+        // but the client disables rewriting globally, so run the two statements separately.
+        foreach (var statement in cmd.CommandText.Split(';', StringSplitOptions.RemoveEmptyEntries))
+        {
+            await using var one = new NpgsqlCommand(statement, conn);
+            await one.ExecuteNonQueryAsync(ct);
+        }
+    }
+
+    /// <summary>Best-effort mirror insert — a failure warns but never fails the test.</summary>
+    private async Task MirrorResponseAsync(string testFile, string block, HttpStep step, RoutineInvokeResult response, CancellationToken ct)
+    {
+        try
+        {
+            await using var conn = new NpgsqlConnection(_debugConnString);
+            await conn.OpenAsync(ct);
+            await using var ins = new NpgsqlCommand(
+                $"insert into \"{_opt.ResponseTempTable.DebugTable}\" (test_file, block, method, path, status, body, content_type, headers, is_success) values ($1,$2,$3,$4,$5,$6,$7,$8::jsonb,$9)",
+                conn);
+            ins.Parameters.AddWithValue(testFile);
+            ins.Parameters.AddWithValue(block);
+            ins.Parameters.AddWithValue(step.Method.ToString());
+            ins.Parameters.AddWithValue(step.Path);
+            ins.Parameters.AddWithValue(response.StatusCode);
+            ins.Parameters.AddWithValue((object?)response.Body ?? DBNull.Value);
+            ins.Parameters.AddWithValue((object?)response.ContentType ?? DBNull.Value);
+            ins.Parameters.AddWithValue((object?)response.Headers ?? DBNull.Value);
+            ins.Parameters.AddWithValue(response.IsSuccess);
+            await ins.ExecuteNonQueryAsync(ct);
+        }
+        catch (Exception ex)
+        {
+            _log?.LogWarning("debug table write failed for {File}: {Message}", testFile, ex.Message);
+        }
+    }
+
     // The temp-table name for an HTTP block: explicit `# @response` wins; otherwise a file with a single
     // HTTP block uses Name (`_response`), and a file with 2+ blocks uses MultiNamePattern with {n} = the
     // 1-based block ordinal (`_response_1`, `_response_2`, …).
diff --git a/NpgsqlRestClient/Testing/TestRunnerOptions.cs b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
index e1ff374a..5417983e 100644
--- a/NpgsqlRestClient/Testing/TestRunnerOptions.cs
+++ b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
@@ -112,6 +112,19 @@ public class ResponseTempTableOptions
     /// <summary>Temp table name pattern when a file has 2+ HTTP blocks. <c>{n}</c> = the 1-based block ordinal.</summary>
     public string MultiNamePattern { get; set; } = "_response_{n}";
 
+    /// <summary>
+    /// Debugging aid: when set (e.g. "_responses_debug"), every captured response is ALSO mirrored into a
+    /// PERMANENT table with this name — written on a separate autocommit connection, so it survives the
+    /// test's rollback and the connection close, and can be examined in a query editor after the run.
+    /// Recreated at the start of every run (always holds the LAST run). ONE table covers all blocks and
+    /// files: each HTTP block adds one row, with the block column recording that block's response-table
+    /// name (<see cref="Name"/>, a <see cref="MultiNamePattern"/> ordinal, or the `# @response` name)
+    /// alongside test_file/method/path and the response columns. The temp-table semantics are unchanged.
+    /// Null (default) = off. Do not enable in CI. In the fresh-test-database workflow combine with Keep,
+    /// or teardown drops the database (and the mirror with it).
+    /// </summary>
+    public string? DebugTable { get; set; } = null;
+
     public ResponseColumnOptions Columns { get; set; } = new();
 }
 
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index 450ada4e..b46f78e5 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -1517,6 +1517,8 @@
     "ResponseTempTable": {
       "Name": "_response",
       "MultiNamePattern": "_response_{n}",
+ 
+      "DebugTable": null,
       "Columns": {
         "Status": "status",
         "Body": "body",
diff --git a/changelog/v3.19.0.md b/changelog/v3.19.0.md
index 302763d8..f2a65443 100644
--- a/changelog/v3.19.0.md
+++ b/changelog/v3.19.0.md
@@ -123,6 +123,8 @@ select (select body::jsonb ->> 'email' from _response) = 'grace@example.com',
        'email is normalized to lowercase';
 ```
 
+**Debugging captured responses** — temp tables vanish with the test's rollback and connection, so you cannot inspect them afterwards (and re-issuing the request from an `.http` file cannot reproduce a response that depended on the test's uncommitted fixtures). Set **`ResponseTempTable.DebugTable`** (e.g. `"_responses_debug"`; default `null` = off) and every captured response is **also mirrored into a permanent table** — written on a separate autocommit connection, immune to rollbacks, recreated at the start of every run so it always holds the last run. One table covers everything: each HTTP block adds one row, with `test_file`, `block` (that block's response-table name — `_response`, a `_response_{n}` ordinal, or the `# @response` name), `method`, `path`, `status`, `body`, `content_type`, `headers`, `is_success`, and `captured_at` — so after a run you can open a query editor and dig into any response with jsonb operators. The temp-table semantics are unchanged; enabling it prints a loud warning (debugging aid — do not enable in CI). In the fresh-test-database workflow combine it with `Keep: true`, or teardown drops the database and the mirror with it.
+
 ### Reusing scripts: `\i` and `\ir` includes
 
 Shared SQL — fixture inserts, utility scripts — can be spliced into any test with psql's include syntax on its own line:
@@ -287,6 +289,7 @@ The runner logs through its own channel — **`NpgsqlRestTest`** (configurable v
     "ResponseTempTable": {
       "Name": "_response",                // table name when a file has ONE HTTP block
       "MultiNamePattern": "_response_{n}",// name pattern for 2+ blocks; {n} = 1-based block position
+      "DebugTable": null,                 // debugging aid: ALSO mirror every response into this PERMANENT table (survives rollback; last run; not for CI)
       "Columns": {                        // response → column mapping; null/empty omits the column
         "Status": "status", "Body": "body", "ContentType": "content_type",
         "Headers": "headers", "IsSuccess": "is_success"

From 0ef7a2ff6117d0701c2cd874ba056154f7e07a6a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Fri, 3 Jul 2026 20:18:40 +0200
Subject: [PATCH 23/25] fix(config): sync ConfigTemplate with the trimmed
 DebugTable comment in appsettings.json

The DebugTable comment block was removed from appsettings.json (leaving a
stray whitespace-only line) but ConfigTemplate.cs still carried it, so the
Config_OutputMatchesAppsettingsJson byte-match test failed on CI.
appsettings.json is the source of truth: the stray line is removed and the
template now matches it exactly. The setting stays documented in the JSON
schema description, the changelog, and the docs site.
---
 NpgsqlRestClient/ConfigTemplate.cs | 11 -----------
 NpgsqlRestClient/appsettings.json  |  1 -
 2 files changed, 12 deletions(-)

diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index ff8d4ba8..cd69451e 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -1526,17 +1526,6 @@ public static partial class ConfigSchemaGenerator
         "ResponseTempTable": {
           "Name": "_response",
           "MultiNamePattern": "_response_{n}",
-          //
-          // Debugging aid: when set (e.g. "_responses_debug"), every captured response is ALSO mirrored into a
-          // PERMANENT table with this name — written on a separate autocommit connection, so it survives the
-          // test's rollback and the connection close and can be examined in a query editor after the run.
-          // Recreated at the start of every run (always holds the LAST run). ONE table covers everything: each
-          // HTTP block adds one row, and the "block" column records that block's response-table name (Name,
-          // MultiNamePattern ordinal, or the # @response name) alongside test_file, method, path, status, body,
-          // content_type, headers, is_success, captured_at. The temp-table semantics are unchanged. Do not
-          // enable in CI. In the fresh-test-database workflow combine with "Keep": true, or teardown drops the
-          // database (and the mirror with it).
-          //
           "DebugTable": null,
           "Columns": {
             "Status": "status",
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index b46f78e5..e7059749 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -1517,7 +1517,6 @@
     "ResponseTempTable": {
       "Name": "_response",
       "MultiNamePattern": "_response_{n}",
- 
       "DebugTable": null,
       "Columns": {
         "Status": "status",

From 536b122c629b5789491ad47ac1b2fce957f44ddd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Fri, 3 Jul 2026 21:01:31 +0200
Subject: [PATCH 24/25] feat(test-runner): Steps.Enabled + shipped disabled
 example steps; "ms" interval support
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every Setup/Teardown step now has an "Enabled" flag (default true). A
disabled step is simply IGNORED wherever it is referenced — Setup/Teardown
arrays or per-file -- @setup / -- @teardown annotations — skipped with a
debug log line, never an error. Referencing an UNKNOWN name remains a loud
configuration error; Enabled=false is the one sanctioned skip.

The default configuration ships six DISABLED example steps in
TestRunner:Steps showing every step property (Sql, SqlFile, Command,
WorkingDirectory, ConnectionName, Enabled) across the typical scenarios:
CreateTestDatabase / DropTestDatabase ({rnd5}-named database on an "Admin"
connection), ApplySchema (SqlFile), RunMigrationTool (Command +
WorkingDirectory), StartDockerPostgres / StopDockerPostgres. Instead of
typing a step from scratch, copy one, adjust names/paths/connections, and
flip Enabled to true. (Defaults are a copy-from reference visible in
appsettings.json and --config output — not a runtime layer merged into
explicit config files.)

Also from the config-comment review:
- ParseTestTimeout gained "ms" support ("500ms") — the Watch comments and
  changelog already promised it but the parser silently fell back to the
  default (verified: --watch:databasepollinginterval=500ms -> poll 0.5s).
- ResponseTempTable section comment carries a compact one-line DebugTable
  description; FilePattern comment names both test layouts.

Config synced x4 + schema (byte-match green). Full suite green (2394).
Live-verified: disabled-referenced step skipped with debug line + run green;
flipped on via CLI override -> step executes; custom user step names produce
no validation warnings (example 20 clean). Changelog + docs updated.
---
 NpgsqlRestClient/Builder.cs                   |  5 +++
 NpgsqlRestClient/ConfigDefaults.cs            | 37 ++++++++++++++++++-
 NpgsqlRestClient/ConfigSchemaGenerator.cs     |  2 +-
 NpgsqlRestClient/ConfigTemplate.cs            | 23 ++++++++++--
 NpgsqlRestClient/Testing/TestRunner.cs        |  7 ++++
 NpgsqlRestClient/Testing/TestRunnerOptions.cs |  7 ++++
 NpgsqlRestClient/appsettings.json             | 23 ++++++++++--
 changelog/v3.19.0.md                          | 20 +++++++++-
 8 files changed, 113 insertions(+), 11 deletions(-)

diff --git a/NpgsqlRestClient/Builder.cs b/NpgsqlRestClient/Builder.cs
index 59702ecf..be187075 100644
--- a/NpgsqlRestClient/Builder.cs
+++ b/NpgsqlRestClient/Builder.cs
@@ -3140,6 +3140,7 @@ static List<string> SplitNames(string? value) =>
         {
             var step = new TestSetupStep
             {
+                Enabled = _config.GetConfigBool("Enabled", child, true),
                 Sql = _config.GetConfigStr("Sql", child),
                 SqlFile = _config.GetConfigStr("SqlFile", child),
                 Command = _config.GetConfigStr("Command", child),
@@ -3186,6 +3187,10 @@ internal static TimeSpan ParseTestTimeout(string? raw, TimeSpan def)
         if (string.IsNullOrWhiteSpace(raw)) return def;
         raw = raw.Trim();
         if (int.TryParse(raw, out var secs)) return TimeSpan.FromSeconds(secs);
+        if (raw.Length > 2 && raw.EndsWith("ms", StringComparison.OrdinalIgnoreCase) && int.TryParse(raw[..^2], out var ms))
+        {
+            return TimeSpan.FromMilliseconds(ms);
+        }
         if (raw.Length > 1 && int.TryParse(raw[..^1], out var n))
         {
             switch (char.ToLowerInvariant(raw[^1]))
diff --git a/NpgsqlRestClient/ConfigDefaults.cs b/NpgsqlRestClient/ConfigDefaults.cs
index 60eb888e..25f09878 100644
--- a/NpgsqlRestClient/ConfigDefaults.cs
+++ b/NpgsqlRestClient/ConfigDefaults.cs
@@ -1134,7 +1134,42 @@ private static JsonObject GetTestRunnerDefaults()
                     ["IsSuccess"] = "is_success"
                 }
             },
-            ["Steps"] = new JsonObject(),
+            ["Steps"] = new JsonObject
+            {
+                ["CreateTestDatabase"] = new JsonObject
+                {
+                    ["Enabled"] = false,
+                    ["ConnectionName"] = "Admin",
+                    ["Sql"] = "create database app_test_{rnd5}",
+                },
+                ["DropTestDatabase"] = new JsonObject
+                {
+                    ["Enabled"] = false,
+                    ["ConnectionName"] = "Admin",
+                    ["Sql"] = "drop database if exists app_test_{rnd5} with (force)",
+                },
+                ["ApplySchema"] = new JsonObject
+                {
+                    ["Enabled"] = false,
+                    ["SqlFile"] = "./migrations/schema.sql",
+                },
+                ["RunMigrationTool"] = new JsonObject
+                {
+                    ["Enabled"] = false,
+                    ["Command"] = "echo replace with your migration tool command",
+                    ["WorkingDirectory"] = ".",
+                },
+                ["StartDockerPostgres"] = new JsonObject
+                {
+                    ["Enabled"] = false,
+                    ["Command"] = "docker run -d --name npgsqlrest-test-pg -e POSTGRES_PASSWORD=postgres -p 54329:5432 postgres",
+                },
+                ["StopDockerPostgres"] = new JsonObject
+                {
+                    ["Enabled"] = false,
+                    ["Command"] = "docker rm -f npgsqlrest-test-pg",
+                },
+            },
             ["Setup"] = new JsonArray(),
             ["Teardown"] = new JsonArray()
         };
diff --git a/NpgsqlRestClient/ConfigSchemaGenerator.cs b/NpgsqlRestClient/ConfigSchemaGenerator.cs
index dfceec1b..0a262390 100644
--- a/NpgsqlRestClient/ConfigSchemaGenerator.cs
+++ b/NpgsqlRestClient/ConfigSchemaGenerator.cs
@@ -268,7 +268,7 @@ public static partial class ConfigSchemaGenerator
         ["TestRunner:ResponseTempTable:MultiNamePattern"] = "Temp table name pattern used when a test file has 2+ HTTP blocks.\n{n} is the 1-based block ordinal, e.g. \"_response_{n}\" => _response_1, _response_2, …",
         ["TestRunner:ResponseTempTable:DebugTable"] = "Debugging aid: when set (e.g. \"_responses_debug\"), every captured response is ALSO mirrored into a PERMANENT table with this name — written on a separate autocommit connection, so it survives the test's rollback and connection close and can be examined in a query editor after the run.\nRecreated at the start of every run (holds the LAST run). ONE table covers everything: each HTTP block adds one row, with the block column recording that block's response-table name (Name, MultiNamePattern ordinal, or the # @response name) alongside test_file, method, path, status, body, content_type, headers, is_success, captured_at. Temp-table semantics unchanged. Do not enable in CI. Null (default) = off.",
         ["TestRunner:ResponseTempTable:Columns"] = "Maps each response component to a column name. A null or empty name omits that column.",
-        ["TestRunner:Steps"] = "Named, reusable steps (name → step; same shape as Setup/Teardown entries). Reference them by name in Setup/Teardown, or from an individual test file's leading header comments:\n-- @setup StepName [StepName ...] (runs before that file); -- @teardown StepName [StepName ...] (runs after that file, always, best-effort); -- @connection Name (runs that file on a named ConnectionStrings entry).\nAnnotations are repeatable; names may be whitespace- or comma-separated and run in the order written.\nTest files can also reuse SQL scripts in place with psql-style includes: `\\i file` (cwd-relative) or `\\ir file` (relative to the including file) — executed on the test's connection, inside its transaction.",
+        ["TestRunner:Steps"] = "Named, reusable steps (name -> step; same shape as Setup/Teardown entries): \"Sql\", \"SqlFile\", \"Command\", \"WorkingDirectory\", \"ConnectionName\", \"Enabled\". Reference them by name in Setup/Teardown or from a test file's leading header comments (-- @setup Name / -- @teardown Name).\nA step with Enabled=false is simply IGNORED wherever referenced — the default configuration ships disabled example steps (create/drop test database, apply schema, run a migration tool, start/stop a Docker PostgreSQL) to flip on instead of typing.",
         ["TestRunner:Setup"] = "Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written.\nEach entry is a step NAME from \"Steps\", or an inline object: { \"Command\": \"...\", \"WorkingDirectory\": \"...\" } (OS shell); { \"Sql\": \"...\" } | { \"SqlFile\": \"...\" } which run on the test connection, or set \"ConnectionName\" to run on another ConnectionStrings entry (e.g. an admin connection that runs `create database`).",
         ["TestRunner:Teardown"] = "Run-once teardown, ALWAYS (best-effort), in the EXACT order written. Same entries as Setup (step names or inline objects, e.g. a `drop database` on an admin connection). The `Keep` option skips it.",
         ["CommandRetryOptions"] = "Command retry strategies and options for client and middleware commands.",
diff --git a/NpgsqlRestClient/ConfigTemplate.cs b/NpgsqlRestClient/ConfigTemplate.cs
index cd69451e..4075a6c7 100644
--- a/NpgsqlRestClient/ConfigTemplate.cs
+++ b/NpgsqlRestClient/ConfigTemplate.cs
@@ -1443,8 +1443,9 @@ public static partial class ConfigSchemaGenerator
       //
       "TestRunner": {
         //
-        // Glob (same engine as SqlFileSource) selecting test files. Empty disables discovery.
-        // Co-located convention: app.sql (endpoint) next to app.test.sql (test).
+        // Glob (same engine as SqlFileSource) selecting test files. Empty disables discovery. Two layouts:
+        // co-located (app.sql next to app.test.sql — SqlFileSource SkipPattern keeps tests out of the endpoints)
+        // or a separate tests tree (e.g. "./tests/**/*.test.sql").
         //
         "FilePattern": "",
         //
@@ -1521,7 +1522,9 @@ public static partial class ConfigSchemaGenerator
         // (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified.
         // A file with ONE HTTP block uses "Name"; a file with 2+ blocks uses "MultiNamePattern" where {n} is
         // the 1-based block ordinal (_response_1, _response_2, ...). Per-block override: `# @response <name>`.
-        // A null/empty column name omits that column.
+        // A null/empty column name omits that column. "DebugTable" (e.g. "_responses_debug"): ALSO mirror every
+        // response into a PERMANENT table for post-run inspection — survives rollbacks, holds the last run, one
+        // row per HTTP block with test_file/block/method/path metadata (debugging aid; do not enable in CI).
         //
         "ResponseTempTable": {
           "Name": "_response",
@@ -1545,7 +1548,19 @@ public static partial class ConfigSchemaGenerator
         // Test files can also reuse SQL scripts in place with psql-style includes: `\i file` (cwd-relative) or
         // `\ir file` (relative to the including file) — executed on the test's connection, inside its transaction.
         //
-        "Steps": {},
+        // The entries below are disabled EXAMPLES showing every step property ("Sql", "SqlFile", "Command",
+        // "WorkingDirectory", "ConnectionName") across the typical scenarios — flip "Enabled" to true (and adjust
+        // names, paths, and connections) instead of typing them from scratch. A step with "Enabled": false is
+        // simply IGNORED wherever it is referenced.
+        //
+        "Steps": {
+          "CreateTestDatabase":  { "Enabled": false, "ConnectionName": "Admin", "Sql": "create database app_test_{rnd5}" },
+          "DropTestDatabase":    { "Enabled": false, "ConnectionName": "Admin", "Sql": "drop database if exists app_test_{rnd5} with (force)" },
+          "ApplySchema":         { "Enabled": false, "SqlFile": "./migrations/schema.sql" },
+          "RunMigrationTool":    { "Enabled": false, "Command": "echo replace with your migration tool command", "WorkingDirectory": "." },
+          "StartDockerPostgres": { "Enabled": false, "Command": "docker run -d --name npgsqlrest-test-pg -e POSTGRES_PASSWORD=postgres -p 54329:5432 postgres" },
+          "StopDockerPostgres":  { "Enabled": false, "Command": "docker rm -f npgsqlrest-test-pg" }
+        },
         //
         // Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written. Each entry is a step
         // NAME from "Steps" above, or an inline step object:
diff --git a/NpgsqlRestClient/Testing/TestRunner.cs b/NpgsqlRestClient/Testing/TestRunner.cs
index 2fc9d9f7..cf58e70e 100644
--- a/NpgsqlRestClient/Testing/TestRunner.cs
+++ b/NpgsqlRestClient/Testing/TestRunner.cs
@@ -193,6 +193,13 @@ public async Task<bool> SetupAsync(CancellationToken ct = default)
     // `phase` ("setup" | "teardown") is only used to label the step's log lines.
     private async Task RunStepAsync(TestSetupStep step, string phase, CancellationToken ct)
     {
+        if (step.Enabled is false)
+        {
+            // Disabled steps are ignored wherever referenced — the default config ships example steps
+            // ("Enabled": false) that users flip on instead of typing them from scratch.
+            _log?.LogDebug("{Phase} step {Step}: skipped (Enabled is false)", phase, step.Name ?? step.SqlFile ?? step.Command ?? "(inline)");
+            return;
+        }
         if (step.IsCommand)
         {
             await RunCommandAsync(step, phase, ct);
diff --git a/NpgsqlRestClient/Testing/TestRunnerOptions.cs b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
index 5417983e..eefbfc99 100644
--- a/NpgsqlRestClient/Testing/TestRunnerOptions.cs
+++ b/NpgsqlRestClient/Testing/TestRunnerOptions.cs
@@ -143,6 +143,13 @@ public class TestSetupStep
     /// <summary>Registry name when the step is defined under <c>Steps</c>; null for inline steps. Used in logs.</summary>
     public string? Name { get; set; }
 
+    /// <summary>
+    /// A disabled step is simply IGNORED wherever it is referenced (Setup/Teardown, per-file
+    /// <c>-- @setup</c>/<c>-- @teardown</c> annotations) — skipped with a debug log line, never an error.
+    /// Lets the default configuration ship ready-made example steps that users flip on instead of typing.
+    /// </summary>
+    public bool Enabled { get; set; } = true;
+
     /// <summary>Inline SQL executed as a single batch.</summary>
     public string? Sql { get; set; }
 
diff --git a/NpgsqlRestClient/appsettings.json b/NpgsqlRestClient/appsettings.json
index e7059749..4d88af0a 100644
--- a/NpgsqlRestClient/appsettings.json
+++ b/NpgsqlRestClient/appsettings.json
@@ -1434,8 +1434,9 @@
   //
   "TestRunner": {
     //
-    // Glob (same engine as SqlFileSource) selecting test files. Empty disables discovery.
-    // Co-located convention: app.sql (endpoint) next to app.test.sql (test).
+    // Glob (same engine as SqlFileSource) selecting test files. Empty disables discovery. Two layouts:
+    // co-located (app.sql next to app.test.sql — SqlFileSource SkipPattern keeps tests out of the endpoints)
+    // or a separate tests tree (e.g. "./tests/**/*.test.sql").
     //
     "FilePattern": "",
     //
@@ -1512,7 +1513,9 @@
     // (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified.
     // A file with ONE HTTP block uses "Name"; a file with 2+ blocks uses "MultiNamePattern" where {n} is
     // the 1-based block ordinal (_response_1, _response_2, ...). Per-block override: `# @response <name>`.
-    // A null/empty column name omits that column.
+    // A null/empty column name omits that column. "DebugTable" (e.g. "_responses_debug"): ALSO mirror every
+    // response into a PERMANENT table for post-run inspection — survives rollbacks, holds the last run, one
+    // row per HTTP block with test_file/block/method/path metadata (debugging aid; do not enable in CI).
     //
     "ResponseTempTable": {
       "Name": "_response",
@@ -1536,7 +1539,19 @@
     // Test files can also reuse SQL scripts in place with psql-style includes: `\i file` (cwd-relative) or
     // `\ir file` (relative to the including file) — executed on the test's connection, inside its transaction.
     //
-    "Steps": {},
+    // The entries below are disabled EXAMPLES showing every step property ("Sql", "SqlFile", "Command",
+    // "WorkingDirectory", "ConnectionName") across the typical scenarios — flip "Enabled" to true (and adjust
+    // names, paths, and connections) instead of typing them from scratch. A step with "Enabled": false is
+    // simply IGNORED wherever it is referenced.
+    //
+    "Steps": {
+      "CreateTestDatabase":  { "Enabled": false, "ConnectionName": "Admin", "Sql": "create database app_test_{rnd5}" },
+      "DropTestDatabase":    { "Enabled": false, "ConnectionName": "Admin", "Sql": "drop database if exists app_test_{rnd5} with (force)" },
+      "ApplySchema":         { "Enabled": false, "SqlFile": "./migrations/schema.sql" },
+      "RunMigrationTool":    { "Enabled": false, "Command": "echo replace with your migration tool command", "WorkingDirectory": "." },
+      "StartDockerPostgres": { "Enabled": false, "Command": "docker run -d --name npgsqlrest-test-pg -e POSTGRES_PASSWORD=postgres -p 54329:5432 postgres" },
+      "StopDockerPostgres":  { "Enabled": false, "Command": "docker rm -f npgsqlrest-test-pg" }
+    },
     //
     // Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written. Each entry is a step
     // NAME from "Steps" above, or an inline step object:
diff --git a/changelog/v3.19.0.md b/changelog/v3.19.0.md
index f2a65443..2f64d0e9 100644
--- a/changelog/v3.19.0.md
+++ b/changelog/v3.19.0.md
@@ -164,6 +164,23 @@ Run-once steps around the whole test session. **`Setup` runs before endpoint dis
 
 Steps can be defined once in the **`Steps` registry** (name → step, like `ConnectionStrings` or `CacheOptions.Profiles`) and referenced by name; `Setup`/`Teardown` arrays accept names and inline objects mixed. Referencing an unknown name is a configuration error (exit 3).
 
+Every step also has an **`Enabled`** flag (default `true`): a disabled step is simply **ignored** wherever it is referenced — skipped with a debug log line, never an error. The default configuration ships **disabled example steps** covering the typical scenarios (create/drop a `{rnd}`-named test database on an admin connection, apply a schema file, run a migration tool, start/stop a Docker PostgreSQL) — they show every step property in place, so instead of typing a step from scratch you copy one, adjust the names, and flip `Enabled` to `true`:
+
+```json
+{
+  "TestRunner": {
+    "Steps": {
+      "CreateTestDatabase":  { "Enabled": false, "ConnectionName": "Admin", "Sql": "create database app_test_{rnd5}" },
+      "DropTestDatabase":    { "Enabled": false, "ConnectionName": "Admin", "Sql": "drop database if exists app_test_{rnd5} with (force)" },
+      "ApplySchema":         { "Enabled": false, "SqlFile": "./migrations/schema.sql" },
+      "RunMigrationTool":    { "Enabled": false, "Command": "echo replace with your migration tool command", "WorkingDirectory": "." },
+      "StartDockerPostgres": { "Enabled": false, "Command": "docker run -d --name npgsqlrest-test-pg -e POSTGRES_PASSWORD=postgres -p 54329:5432 postgres" },
+      "StopDockerPostgres":  { "Enabled": false, "Command": "docker rm -f npgsqlrest-test-pg" }
+    }
+  }
+}
+```
+
 ```jsonc
 {
   "TestRunner": {
@@ -295,7 +312,8 @@ The runner logs through its own channel — **`NpgsqlRestTest`** (configurable v
         "Headers": "headers", "IsSuccess": "is_success"
       }
     },
-    "Steps": {},                          // named, reusable steps (name → step) for Setup/Teardown and -- @setup/-- @teardown
+    "Steps": { },                         // named, reusable steps (name → step) for Setup/Teardown and -- @setup/-- @teardown;
+                                          // each has "Enabled" (false = ignored wherever referenced); ships disabled examples
     "Setup": [],                          // run-once, BEFORE endpoint discovery, in written order (step names or inline objects)
     "Teardown": []                        // run-once, ALWAYS, in written order (Keep skips; same entries as Setup)
   }

From 7573f8f9cb6b34e31530e8079c3e7c2e0c9bb40e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vedran=20Bilopavlovi=C4=87?= <vbilopav@gmail.com>
Date: Fri, 3 Jul 2026 21:13:58 +0200
Subject: [PATCH 25/25] bump 3.19.0 and update skill files

---
 .claude/skills/npgsqlrest/SKILL.md            |  56 ++++-
 .../npgsqlrest/annotations-reference.md       |   7 +-
 .../npgsqlrest/configuration-reference.jsonc  | 202 +++++++++++++++++-
 .../CommentParsers/AnnotationReference.cs     |   4 +-
 README.md                                     |  87 ++++++--
 changelog/v3.19.0.md                          |  19 +-
 docker/Dockerfile.jit                         |   3 +
 npm/package.json                              |   2 +-
 version.txt                                   |   2 +-
 9 files changed, 336 insertions(+), 46 deletions(-)

diff --git a/.claude/skills/npgsqlrest/SKILL.md b/.claude/skills/npgsqlrest/SKILL.md
index 2cb12cd5..4b7c9da7 100644
--- a/.claude/skills/npgsqlrest/SKILL.md
+++ b/.claude/skills/npgsqlrest/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: npgsqlrest
-description: Build and modify REST APIs with NpgsqlRest — exposing PostgreSQL as HTTP endpoints from two sources (database functions/procedures/tables/views, and plain .sql files), driven by SQL comment annotations (no C# needed). Use when working in an NpgsqlRest project: writing or changing endpoint SQL (functions or .sql files), comment annotations (HTTP routing, authorize, cached, proxy, HTTP Custom Types, SSE, MCP, upload), appsettings.json config, or running/troubleshooting the `npgsqlrest` client.
+description: Build and modify REST APIs with NpgsqlRest — exposing PostgreSQL as HTTP endpoints from two sources (database functions/procedures/tables/views, and plain .sql files), driven by SQL comment annotations (no C# needed). Use when working in an NpgsqlRest project: writing or changing endpoint SQL (functions or .sql files), comment annotations (HTTP routing, authorize, cached, proxy, HTTP Custom Types, SSE, MCP, upload), appsettings.json config, testing endpoints with SQL test files (`--test`), running in watch mode (`--watch`), or running/troubleshooting the `npgsqlrest` client.
 ---
 
 # Working with NpgsqlRest
@@ -67,20 +67,20 @@ Annotations live in **leading line comments** (`-- ...` or `/* ... */`) in a `.s
 { "NpgsqlRest": { "SqlFileSource": { "Enabled": true, "FilePattern": "sql/**/*.sql" } } }
 ```
 
+Files matching `SkipPattern` (default `"*.test.sql"`) are excluded from endpoint discovery — they are test files for the [test runner](#testing-sql-test-files---test), which makes the co-located layout (`app.sql` next to `app.test.sql`) safe.
+
 ```sql
 -- sql/get-reports.sql
 -- HTTP GET
--- @param $1 from_date
--- @param $2 to_date
 -- @authorize
 select id, title, created_at
 from reports
-where created_at between $1 and $2;
+where created_at between :from_date and :to_date;
 ```
 
 - **Filename → path**: `get-reports.sql` → `/api/get-reports`.
 - **Startup Describe = static type checking.** Each statement is parsed/described against the live DB (no execution); SQL errors fail startup (`ErrorMode: Exit`; set `Skip` to log-and-continue). This catches `column does not exist` etc. before serving.
-- **Parameters are positional** (`$1, $2`). `@param $N name [type] [default ...]` names/retypes/defaults them (positional params have no native DEFAULT). `@define_param name [type]` creates a *virtual* param (for placeholders/claims; not bound to SQL).
+- **Parameters: named (`:name`) or positional (`$1, $2`)** — one style per file (mixing is a startup error). **Prefer named**: the placeholder IS the parameter name (camelCased for the API: `:from_date` → `fromDate`), a repeated name is ONE parameter (also across statements), and claim mappings (`@user_parameters` + `:_user_id`) hook up with zero annotations. `@param` then only handles type/default: `@param from_date default null`, `@param :from_date date` (Describe type hint), `@param from_date type is date` (retype without rename). Positional: `@param $N name [type] [default ...]` names/retypes/defaults. `@define_param name [type]` creates a *virtual* param (placeholders/claims; not bound to SQL). Tokenizer caveats for `:name`: `::casts`, `:=`, and `a[1:3]` never match; a variable slice bound needs a space (`a[1 : n]`).
 - **Verb inference** when no `HTTP` tag: `SELECT`→GET, `INSERT`→PUT, `UPDATE`→POST, `DELETE`→DELETE, `DO`→POST (most destructive wins). Explicit `-- HTTP POST` overrides.
 - **Multi-command files** (statements split on `;`) run in **one batch / round-trip** and return a JSON object keyed per statement. Positional annotations apply to the *next* statement (or inline after `;`):
   - `@result name` — name the result key (default `result1`, `result2`, …)
@@ -120,6 +120,9 @@ Same annotations apply to functions and `.sql` files. Confirm exact syntax/alias
 **Other**
 - `@rate_limiter_policy name`. `@command_timeout 30s`. `@connection Name` (multi-connection). `@buffer_rows N`. `@validate _email using required, email`. `@error_code_policy 23505 -> 409`. `@upload [for csv|excel|file_system|large_object]`.
 
+**Test files only** (`*.test.sql`, run by `--test` — not endpoint annotations)
+- Header: `-- @setup Step ...`, `-- @teardown Step ...`, `-- @connection Name`, `-- @tag a, b`. Inside HTTP blocks: `# @claim name=value`, `# @response name`. Includes: `\i file` / `\ir file`.
+
 ## HTTP Custom Types (outbound HTTP from SQL)
 
 A **composite type** whose comment defines an outbound HTTP request. When a routine (or `.sql` param) is of that type, NpgsqlRest performs the call **before** running the endpoint and fills the composite fields.
@@ -215,10 +218,48 @@ npgsqlrest                                  # appsettings.json in cwd
 npgsqlrest ./config/appsettings.json ./config/appsettings.development.json
 npgsqlrest --connectionstrings:default="Host=localhost;Database=db;Username=postgres;Password=postgres"
 npgsqlrest --log:minimallevels:npgsqlrest=debug    # see every annotation parsed
+npgsqlrest ./config.json --test             # run SQL test files, then exit (0 pass / 1 fail / 2 error / 3 config / 4 none)
+npgsqlrest ./config.json --watch            # dev server: restart on SQL file / config / database routine changes
+npgsqlrest ./config.json --test --watch     # dev test loop: re-run tests on changes
 ```
 
 Install via the GitHub release binary, `npm install -g npgsqlrest`, or the `vbilopav/npgsqlrest` Docker image.
 
+## Testing: SQL test files (`--test`)
+
+Tests are plain `.sql` files (glob: `TestRunner.FilePattern`, e.g. `./tests/**/*.test.sql` or co-located next to endpoints). Each file runs on its **own non-pooled connection**, in parallel; endpoints are invoked **in-process** (full pipeline: routing, auth, params, serialization) **on the test's own connection/transaction** — so a test can `begin`, insert fixtures, call the endpoint (it sees the uncommitted rows), assert, and `rollback`.
+
+```sql
+begin;
+insert into users (email) values ('x@example.com');
+
+/*
+GET /api/get-users
+# @claim user_id=1
+*/
+select status = 200, 'authenticated caller gets 200' from _response;
+select body::jsonb @> '[{"email": "x@example.com"}]', 'fixture listed' from _response;
+
+rollback;
+```
+
+Essentials:
+- **Assertions**: a SELECT whose first column is `boolean` (2nd column = assertion name), or a `do $$ ... assert ... $$` block. Everything else is arrange/act.
+- **HTTP blocks**: block comment, first line `METHOD /full/path` (incl. `/api` prefix). Directives: `# @claim name=value` (repeatable; any claim = authenticated principal, none = anonymous), `# @response name` (custom capture table). Body after a blank line. Response lands in temp table `_response` (`_response_{n}` for 2+ blocks): `status int, body text, content_type text, headers jsonb, is_success boolean`.
+- **Per-file header annotations** (leading `--` comments, TEST files only): `-- @setup StepName ...`, `-- @teardown StepName ...`, `-- @connection Name` (perfect isolation: run the file on its own database), `-- @tag smoke, slow`. Reuse scripts with psql-style `\i file` / `\ir file` includes (paste semantics).
+- **Setup/Teardown/Steps** (`TestRunner` config): run-once steps in written order — `{ "Sql": ... }` / `{ "SqlFile": ... }` / `{ "Command": ... }`, each with optional `ConnectionName` and `Enabled` (false = ignored wherever referenced; the default config ships disabled examples to flip on). `Setup` runs BEFORE endpoint discovery → it can `create database app_test_{rnd5}` on an admin connection; `TestRunner.ConnectionName` points the whole run at it; teardown drops it (guaranteed — runs even on Ctrl+C/SIGTERM). `{rnd1}`..`{rnd10}` are per-run-stable random tokens (`{rndN_1}`.. for independent instances).
+- **Selection**: `--testrunner:filter=login` (path substring/glob), `--testrunner:tag=smoke --testrunner:excludetag=slow`.
+- **Endpoint coverage** reports after full runs (on by default; `CoverageThreshold: 100` fails the build naming untested endpoints). `JUnitOutput` for CI.
+- **Debugging**: `DetailedReport: true` (richer report); `ResponseTempTable.DebugTable: "_responses_debug"` mirrors every response into a permanent table (survives rollback; query it after the run; not for CI); the `NpgsqlRestTest` log channel at `Verbose` shows every statement and HTTP call.
+
+## Watch mode (`--watch`)
+
+One flag (`--watch`, or config `Watch: { "Enabled": true }`), two flavors chosen by `--test`:
+- **Server watch** (`--watch`): a supervisor restarts the server (~1s) on `.sql` source changes (SkipPattern-filtered), **configuration file** changes, and **database routine changes** — polling runs the routine discovery query hashed server-side (`Watch:DatabasePollingInterval`, default `2s`; detects create/replace/drop/comment on functions, grants, and type/table shape changes; never fires on unrelated objects). Code generation (TS client, HTTP files) re-runs every cycle. A broken SQL file logs its error and drops only its endpoint (`ErrorMode` forced to `Skip` while watching).
+- **Test watch** (`--test --watch`): a changed test re-runs alone; a changed endpoint file or database routine rebuilds endpoints in-process (endpoint delta reported) and re-runs everything; teardown runs once, on exit.
+
+For Docker Desktop bind mounts set `DOTNET_USE_POLLING_FILE_WATCHER=1` (file events only; database polling is unaffected).
+
 ## Project conventions worth copying (from real projects)
 
 - **One schema for the API** (`IncludeSchemas: ["myapi"]`); internal helpers in another schema.
@@ -234,5 +275,8 @@ Install via the GitHub release binary, `npm install -g npgsqlrest`, or the `vbil
 - **HTTP-type directives** are safest **before the request line**.
 - **Passthrough proxy doesn't run the function** — declare proxy-response params (transform mode) if you need the body executed.
 - **`HttpClientOptions.Enabled` / `ProxyOptions.Enabled` / `SqlFileSource.Enabled`** must be true for those features. `@cache` on a non-GET HTTP type is ignored with a warning.
-- **SQL files:** annotations are in `--`/`/* */` comments; params are positional `$N` (name via `@param`); a startup Describe error fails boot unless `ErrorMode: Skip`; use `@returns` for statements over not-yet-existing objects (temp tables); `DO` blocks can't take `$N` or return values.
+- **SQL files:** annotations are in `--`/`/* */` comments; params are named `:name` (preferred — auto-named) or positional `$N` (name via `@param`) — **never mixed in one file** (startup error); a startup Describe error fails boot unless `ErrorMode: Skip`; use `@returns` for statements over not-yet-existing objects (temp tables); `DO` blocks can't take params or return values.
+- **A `.sql` file named `*.test.sql` never becomes an endpoint** — `SqlFileSource.SkipPattern` excludes test files by default.
+- **Test HTTP block paths must be the FULL path** including `UrlPathPrefix` (`/api/...`) — a bare `/get-users` is a 404 with a warning.
+- **`ResponseTempTable.DebugTable` is a dev-only debugging aid** — never enable in CI; combine with `Keep: true` when the run drops its test database.
 - After changing an annotation, re-run with `--log:minimallevels:npgsqlrest=debug` (or `--validate`) to confirm it parsed as intended.
diff --git a/.claude/skills/npgsqlrest/annotations-reference.md b/.claude/skills/npgsqlrest/annotations-reference.md
index d9c612ca..1dc513ad 100644
--- a/.claude/skills/npgsqlrest/annotations-reference.md
+++ b/.claude/skills/npgsqlrest/annotations-reference.md
@@ -1,6 +1,6 @@
 # NpgsqlRest — Full Annotation Reference
 
-Every comment annotation, generated from `npgsqlrest --annotations` (NpgsqlRest v3.18.1).
+Every comment annotation, generated from `npgsqlrest --annotations` (NpgsqlRest v3.19.0).
 Annotations apply to both endpoint sources (database routines via `comment on`, and `.sql` files via leading `--` comments). The `@` prefix is optional. Regenerate with `npgsqlrest --annotations`.
 
 ## `http`
@@ -188,9 +188,9 @@ Enable file upload for this endpoint, optionally specifying upload handlers.
 ## `param`
 
 - **Aliases:** parameter, param
-- **Syntax:** `param <name> is hash of <other_name> | param <name> is upload metadata | param <original> <new_name> [type] | param <original> is <new_name> [type]`
+- **Syntax:** `param <name> is hash of <other_name> | param <name> is upload metadata | param <original> <new_name> [type] | param <original> is <new_name> [type] | param <name> type is <type> | param <name> default <value>`
 
-Configure parameter behavior: hash computation, upload metadata binding, or rename/retype. Rename forms: 'param $1 user_id', 'param $1 user_id integer', 'param $1 is user_id', 'param _old_name better_name'. Works on all endpoint types.
+Configure parameter behavior: hash computation, upload metadata binding, rename/retype, retype WITHOUT rename ('param user_id type is integer'), or default value ('param user_id default null'). Rename forms: 'param $1 user_id', 'param $1 user_id integer', 'param $1 is user_id', 'param _old_name better_name'. In SQL files with named (:name) placeholders the parameter is addressed by the placeholder's own name (a leading ':' is tolerated). Works on all endpoint types.
 
 ## `sse_path`
 
@@ -352,4 +352,3 @@ Rename a result key in multi-command SQL file responses. N is the 1-based comman
 - **Syntax:** `define_param <name> [type]`
 
 Define a virtual parameter that exists for HTTP matching and claim mapping but is NOT bound to the PostgreSQL command. Useful for SQL file endpoints where you need parameters for comment placeholders or claim mapping without referencing them in SQL. Default type is text. SQL file source only.
-
diff --git a/.claude/skills/npgsqlrest/configuration-reference.jsonc b/.claude/skills/npgsqlrest/configuration-reference.jsonc
index f986c9e0..49f8dd89 100644
--- a/.claude/skills/npgsqlrest/configuration-reference.jsonc
+++ b/.claude/skills/npgsqlrest/configuration-reference.jsonc
@@ -1,5 +1,5 @@
 // NpgsqlRest — FULL configuration reference (every option, with inline comments).
-// Generated verbatim from: npgsqlrest --config   (NpgsqlRest v3.18.1)
+// Generated verbatim from: npgsqlrest --config   (NpgsqlRest v3.19.0)
 // This is the source of truth for configuration. Regenerate with: npgsqlrest --config
 
 {
@@ -885,11 +885,14 @@
     //
     // See https://github.com/serilog/serilog/wiki/Configuration-Basics#minimum-level
     // Verbose, Debug, Information, Warning, Error, Fatal.
+    // Set a level to "Off" (aliases "None"/"Silent") to mute that logger entirely; use null (or omit it) to fall back to its built-in default.
     // Note: NpgsqlRest logger applies to main application logger, which will, by default have the name defined in the ApplicationName setting.
+    // NpgsqlRestTest is the SQL test runner (--test) channel (see TestRunner:LoggerName): discovery/parsing at Debug, each query and HTTP call at Verbose, notices by severity.
     //
     "MinimalLevels": {
       "NpgsqlRest": "Information",
       "NpgsqlRestClient": "Information",
+      "NpgsqlRestTest": "Information",
       "System": "Warning",
       "Microsoft": "Warning"
     },
@@ -1426,6 +1429,173 @@
     "ActivityPath": "/stats/activity"
   },
 
+  //
+  // SQL test runner. Invoked with the `--test` command-line flag (this section is otherwise inert).
+  // Discovers *.test.sql files, runs each in an isolated non-pooled connection, can invoke endpoints
+  // in-process from an embedded `/* GET /path */` block (response captured into a temp table), and
+  // asserts via boolean-returning SELECTs or `do $$ ... assert ... $$;` blocks. Exit codes:
+  // 0 pass, 1 failures, 2 errors, 3 config/runner error, 4 no tests found.
+  //
+  "TestRunner": {
+    //
+    // Glob (same engine as SqlFileSource) selecting test files. Empty disables discovery. Two layouts:
+    // co-located (app.sql next to app.test.sql — SqlFileSource SkipPattern keeps tests out of the endpoints)
+    // or a separate tests tree (e.g. "./tests/**/*.test.sql").
+    //
+    "FilePattern": "",
+    //
+    // Optional filter narrowing the discovered set — the fast path for iterating on one test:
+    //   npgsqlrest ... --test --testrunner:filter=login
+    // Matched against each file's cwd-relative path: a value without wildcards is a substring match;
+    // with wildcards it is the same glob engine as FilePattern. Empty = run everything discovered.
+    //
+    "Filter": "",
+    //
+    // Tag filtering (comma- or whitespace-separated lists; case-insensitive). A test file declares tags
+    // with a `-- @tag name [name ...]` header annotation. "Tag" runs only files carrying at least one of
+    // the listed tags; "ExcludeTag" skips files carrying any of them (exclude wins). Composes with Filter.
+    //   npgsqlrest ... --test --testrunner:tag=smoke --testrunner:excludetag=slow
+    //
+    "Tag": "",
+    "ExcludeTag": "",
+    //
+    // Optional: a ConnectionStrings entry to run the tests against instead of the app's main connection. In
+    // test mode it becomes the connection used for endpoint type-checking (Describe) and execution, so it can
+    // point at a dedicated test database that a Setup step creates first (it need not exist at startup).
+    // Empty = use the main connection. Tip: {rnd1}..{rnd10} are random lowercase tokens (length = the digit),
+    // stable for the whole run, usable in any connection string or Setup/Teardown SQL (e.g. Database=app_test_{rnd6}).
+    // Need several distinct tokens of the same length? Indexed instances {rndN_1}..{rndN_9} are each independent.
+    //
+    "ConnectionName": "",
+    //
+    // Max test files run concurrently. 0 => processor count. Each test uses its own non-pooled connection.
+    //
+    "MaxParallelism": 0,
+    //
+    // Stop scheduling new tests after the first failure/error (in-flight tests still finish).
+    //
+    "FailFast": false,
+    //
+    // Per-test timeout. Accepts "30s", "5m", "1h", a plain number of seconds, or "hh:mm:ss". 0 disables.
+    //
+    "PerTestTimeout": "30s",
+    //
+    // Optional path to also write a JUnit XML report (console output is always printed).
+    //
+    "JUnitOutput": null,
+    //
+    // Skip Teardown so a failed run's state can be inspected.
+    //
+    "Keep": false,
+    //
+    // Detailed console REPORT: list passed assertions, print the full failing SQL statement, and show
+    // captured `raise notice` output for passing tests too. This shapes the report only — for diagnostic
+    // logging of every executed query/HTTP call, raise the log channel instead (Log:MinimalLevels + LoggerName).
+    //
+    "DetailedReport": false,
+    //
+    // Treat "no tests discovered" as success (exit 0) instead of exit 4.
+    //
+    "AllowEmpty": false,
+    //
+    // Endpoint-coverage summary after the run: exercised N of M testable endpoints + the list of untested
+    // ones (endpoint kinds the runner rejects — SSE, upload, login/logout, outbound proxy — are excluded
+    // from the ratio and counted separately). Tri-state: null (default) reports after FULL runs but stays
+    // quiet when the run is narrowed by Filter/Tag (a deliberately partial run would just nag); true always
+    // reports; false never. CoverageThreshold (0-100) always reports and fails an otherwise-passing run
+    // with exit 2 when coverage is below it — CI gating for "every endpoint has a test".
+    //
+    "Coverage": null,
+    "CoverageThreshold": null,
+    //
+    // SourceContext name for the runner's own log channel; set its level independently under Log:MinimalLevels.
+    // Discovery/parsing log at Debug, each query and HTTP invocation at Verbose, `raise notice` by severity.
+    //
+    "LoggerName": "NpgsqlRestTest",
+    //
+    // Per-HTTP-block temp table that captures the response. Each block gets its own fresh temp table
+    // (created without IF NOT EXISTS, so a duplicate name fails the test); writes are pg_temp-qualified.
+    // A file with ONE HTTP block uses "Name"; a file with 2+ blocks uses "MultiNamePattern" where {n} is
+    // the 1-based block ordinal (_response_1, _response_2, ...). Per-block override: `# @response <name>`.
+    // A null/empty column name omits that column. "DebugTable" (e.g. "_responses_debug"): ALSO mirror every
+    // response into a PERMANENT table for post-run inspection — survives rollbacks, holds the last run, one
+    // row per HTTP block with test_file/block/method/path metadata (debugging aid; do not enable in CI).
+    //
+    "ResponseTempTable": {
+      "Name": "_response",
+      "MultiNamePattern": "_response_{n}",
+      "DebugTable": null,
+      "Columns": {
+        "Status": "status",
+        "Body": "body",
+        "ContentType": "content_type",
+        "Headers": "headers",
+        "IsSuccess": "is_success"
+      }
+    },
+    //
+    // Named, reusable steps (name → step; same shape as Setup/Teardown entries). Reference them by name in
+    // Setup/Teardown below, or from an individual test file's leading header comments:
+    //   -- @setup StepName [StepName ...]      runs before that file
+    //   -- @teardown StepName [StepName ...]   runs after that file (always, best-effort)
+    //   -- @connection Name                    runs that file on a named ConnectionStrings entry
+    // Annotations are repeatable; names may be whitespace- or comma-separated and run in the order written.
+    // Test files can also reuse SQL scripts in place with psql-style includes: `\i file` (cwd-relative) or
+    // `\ir file` (relative to the including file) — executed on the test's connection, inside its transaction.
+    //
+    // The entries below are disabled EXAMPLES showing every step property ("Sql", "SqlFile", "Command",
+    // "WorkingDirectory", "ConnectionName") across the typical scenarios — flip "Enabled" to true (and adjust
+    // names, paths, and connections) instead of typing them from scratch. A step with "Enabled": false is
+    // simply IGNORED wherever it is referenced.
+    //
+    "Steps": {
+      "CreateTestDatabase":  { "Enabled": false, "ConnectionName": "Admin", "Sql": "create database app_test_{rnd5}" },
+      "DropTestDatabase":    { "Enabled": false, "ConnectionName": "Admin", "Sql": "drop database if exists app_test_{rnd5} with (force)" },
+      "ApplySchema":         { "Enabled": false, "SqlFile": "./migrations/schema.sql" },
+      "RunMigrationTool":    { "Enabled": false, "Command": "echo replace with your migration tool command", "WorkingDirectory": "." },
+      "StartDockerPostgres": { "Enabled": false, "Command": "docker run -d --name npgsqlrest-test-pg -e POSTGRES_PASSWORD=postgres -p 54329:5432 postgres" },
+      "StopDockerPostgres":  { "Enabled": false, "Command": "docker rm -f npgsqlrest-test-pg" }
+    },
+    //
+    // Run-once setup, BEFORE endpoint discovery. Steps run in the EXACT order written. Each entry is a step
+    // NAME from "Steps" above, or an inline step object:
+    //   { "Command": "...", "WorkingDirectory": "..." }    — runs via the OS shell
+    //   { "Sql": "..." } | { "SqlFile": "..." }            — runs on the test connection; set "ConnectionName"
+    //                                                         to run on another ConnectionStrings entry (e.g.
+    //                                                         an admin connection that runs `create database`).
+    //
+    "Setup": [],
+    //
+    // Run-once teardown, ALWAYS (best-effort), in the EXACT order written. `Keep` skips it. Same entries as Setup.
+    //
+    "Teardown": []
+  },
+
+  //
+  // Watch mode (interactive/dev-only) — one feature, two flavors: with --test it re-runs tests on
+  // changes (a changed test file re-runs alone; a changed endpoint file or database routine rebuilds
+  // endpoints in-process and re-runs everything; teardown runs once, on exit); without --test it
+  // supervises the SERVER and restarts it on SQL file source, configuration, and database routine
+  // changes. In both flavors a broken SQL file cannot kill the session (SqlFileSource ErrorMode is
+  // forced from Exit to Skip while watching).
+  //
+  "Watch": {
+    //
+    // Turn watch mode on. The --watch command line flag is the shorthand for this setting.
+    //
+    "Enabled": false,
+    //
+    // Poll the database for routine changes and restart the server (server watch) or rebuild endpoints and
+    // re-run the tests (test watch). The poll runs the SAME routine discovery query the endpoint source
+    // uses (same configured filters), hashed server-side into one value — so it detects exactly what
+    // changes discovered endpoints: functions/procedures (create/replace/drop/alter, grants), their
+    // COMMENT ON annotations, and the composite types and tables their signatures use; anything the
+    // discovery does not read can never trigger. Accepts "2s", "500ms", "1m", a plain number of seconds,
+    // or "hh:mm:ss"; 0 disables. One query per interval on a dedicated non-pooled connection.
+    //
+    "DatabasePollingInterval": "2s"
+  },
+
   //
   // Command retry strategies and options for client and middleware commands.
   //
@@ -2461,7 +2631,11 @@
       //
       // Set to true to overwrite existing files.
       //
-      "FileOverwrite": true
+      "FileOverwrite": true,
+      //
+      // When true, parameters filled by the server and not settable by the client are omitted from the generated HTTP file's query string and request body. Covers optional automatic parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and (on endpoints using user parameters) IP-address and user-claim parameters. Default is false.
+      //
+      "OmitAutomaticParameters": false
     },
 
     //
@@ -2563,7 +2737,11 @@
       // documented. Anonymous endpoints — typically health, login, probes — are omitted. Useful
       // for partner-facing documents. Default false = document everything.
       //
-      "RequiresAuthorizationOnly": false
+      "RequiresAuthorizationOnly": false,
+      //
+      // When true, parameters filled by the server and not settable by the client are omitted from documented query parameters and request bodies. Covers optional automatic parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and (on endpoints using user parameters) IP-address and user-claim parameters. Default is false.
+      //
+      "OmitAutomaticParameters": false
     },
     //
     // Enable or disable the MCP (Model Context Protocol) server endpoint. Disabled by default. Tools are NEVER auto-exposed: only routines explicitly opted in with the `mcp` comment annotation become MCP tools. Implements MCP specification 2025-11-25.
@@ -2763,7 +2941,11 @@
       //
       // TypeScript type for error response. Only used when IncludeStatusCode is true.
       //
-      "ErrorType": "{status: number; title: string; detail?: string | null} | undefined"
+      "ErrorType": "{status: number; title: string; detail?: string | null} | undefined",
+      //
+      // When true, parameters filled by the server and not settable by the client are omitted from the generated request interface, query string, and body. Covers optional automatic parameters: HTTP Custom Type fields, resolved-parameter expressions, upload metadata, and (on endpoints using user parameters) IP-address and user-claim parameters. Default is false.
+      //
+      "OmitAutomaticParameters": false
     },
 
     //
@@ -2877,7 +3059,11 @@
       //
       // When true, for upload endpoints marked as proxy, the raw multipart/form-data content is forwarded directly to the upstream proxy instead of being processed locally. This allows the upstream service to handle file uploads. When false (default), upload endpoints with proxy annotation will process uploads locally and upload metadata will not be available to the proxy.
       //
-      "ForwardUploadContent": false
+      "ForwardUploadContent": false,
+      //
+      // Maximum length (characters) of a single automatic parameter value appended to the proxy upstream query string. Server-filled values (claims, IP, HTTP Custom Type fields, resolved-parameter expressions) longer than this are skipped with a warning instead of producing an unusable request line (HTTP 414/431). 0 or less disables the guard. To forward a large value, use a body-carrying proxy method (POST/PUT/PATCH). Default is 2048.
+      //
+      "MaxForwardedQueryParamLength": 2048
     },
 
     //
@@ -2896,6 +3082,12 @@
       //
       "FilePattern": "",
       //
+      // Glob (same semantics as FilePattern) for files to EXCLUDE from endpoint discovery.
+      // Default "*.test.sql" so co-located SQL test files (run by the test runner, see "TestRunner")
+      // are never exposed as endpoints. Empty string disables the exclusion.
+      //
+      "SkipPattern": "*.test.sql",
+      //
       // How comment annotations are processed for SQL file endpoints.
       // Possible values: Ignore, ParseAll, OnlyAnnotated, OnlyWithHttpTag.
       // OnlyAnnotated (default; OnlyWithHttpTag is a back-compat alias) requires an explicit
diff --git a/NpgsqlRest/Defaults/CommentParsers/AnnotationReference.cs b/NpgsqlRest/Defaults/CommentParsers/AnnotationReference.cs
index a9544173..0ba4d522 100644
--- a/NpgsqlRest/Defaults/CommentParsers/AnnotationReference.cs
+++ b/NpgsqlRest/Defaults/CommentParsers/AnnotationReference.cs
@@ -233,8 +233,8 @@ static JsonArray ToJsonArray(string[] values)
         {
             ["name"] = "param",
             ["aliases"] = ToJsonArray(ParameterKey),
-            ["syntax"] = "param <name> is hash of <other_name> | param <name> is upload metadata | param <original> <new_name> [type] | param <original> is <new_name> [type]",
-            ["description"] = "Configure parameter behavior: hash computation, upload metadata binding, or rename/retype. Rename forms: 'param $1 user_id', 'param $1 user_id integer', 'param $1 is user_id', 'param _old_name better_name'. Works on all endpoint types."
+            ["syntax"] = "param <name> is hash of <other_name> | param <name> is upload metadata | param <original> <new_name> [type] | param <original> is <new_name> [type] | param <name> type is <type> | param <name> default <value>",
+            ["description"] = "Configure parameter behavior: hash computation, upload metadata binding, rename/retype, retype WITHOUT rename ('param user_id type is integer'), or default value ('param user_id default null'). Rename forms: 'param $1 user_id', 'param $1 user_id integer', 'param $1 is user_id', 'param _old_name better_name'. In SQL files with named (:name) placeholders the parameter is addressed by the placeholder's own name (a leading ':' is tolerated). Works on all endpoint types."
         });
 
         annotations.Add((JsonNode)new JsonObject
diff --git a/README.md b/README.md
index e5d2c3c0..badc4453 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 [![Build, Test, Publish and Release](https://github.com/NpgsqlRest/NpgsqlRest/actions/workflows/build-test-publish.yml/badge.svg)](https://github.com/NpgsqlRest/NpgsqlRest/actions/workflows/build-test-publish.yml)
 [![Tests](https://github.com/NpgsqlRest/NpgsqlRest/actions/workflows/test.yml/badge.svg)](https://github.com/NpgsqlRest/NpgsqlRest/actions/workflows/test.yml)
-![1800+ integration tests](https://img.shields.io/badge/integration%20tests-1837%2B-brightgreen)
+![2300+ integration tests](https://img.shields.io/badge/integration%20tests-2394%2B-brightgreen)
 ![License](https://img.shields.io/badge/license-MIT-green)
 ![GitHub Stars](https://img.shields.io/github/stars/NpgsqlRest/NpgsqlRest?style=social)
 ![GitHub Forks](https://img.shields.io/github/forks/NpgsqlRest/NpgsqlRest?style=social)
@@ -11,9 +11,9 @@
 
 **Automatic REST API for PostgreSQL** | [6.1x faster than PostgREST](https://npgsqlrest.github.io/blog/postgresql-rest-api-benchmark-2026.html)
 
-> SQL files and PostgreSQL objects become REST endpoints. TypeScript clients are generated automatically.
+> SQL files and PostgreSQL objects become REST endpoints. TypeScript clients are generated automatically. Tests are SQL files too.
 
-**4,500+ req/s** on a single host · **1,800+ integration tests** · **12K LOC SQL** in production · **MIT** licensed
+**4,500+ req/s** on a single host · **2,394 integration tests** · **12K LOC SQL** in production · **MIT** licensed
 
 *"Simplicity is the ultimate sophistication."* — Leonardo da Vinci
 
@@ -42,38 +42,45 @@ Write a SQL file:
 -- sql/process_order.sql
 -- HTTP POST
 -- @authorize admin
--- @param $1 order_id
 -- @result validate
-select count(*) as found from orders where id = $1;
-update orders set status = 'processing' where id = $1;
+-- @single
+select count(*) as found from orders where id = :order_id;
+update orders set status = 'processing' where id = :order_id;
 -- @result confirm
-select id, status from orders where id = $1;
+select id, status from orders where id = :order_id;
 ```
 
 That gives you `POST /api/process-order`:
 
 ```json
-{"validate": [1], "result2": 1, "confirm": [{"id": 42, "status": "processing"}]}
+{"validate": 1, "result2": 1, "confirm": [{"id": 42, "status": "processing"}]}
 ```
 
 And a generated TypeScript client with full type safety:
 
 ```typescript
-export async function processOrder(orderid: number) : Promise<{
-    validate: number[],
-    result2: number,
-    confirm: { id: number, status: string }[]
-}> {
+interface IProcessOrderResponse {
+    validate: number;
+    result2: number;
+    confirm: { id: number, status: string }[];
+}
+
+export async function processOrder(
+    request: IProcessOrderRequest
+) : Promise<ApiResult<IProcessOrderResponse>> {
     const response = await fetch(baseUrl + "/api/process-order", {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ orderid }),
+        body: JSON.stringify(request)
     });
-    return await response.json();
+    return {
+        status: response.status,
+        response: response.ok ? await response.json() as IProcessOrderResponse : undefined!,
+        error: !response.ok && response.headers.get("content-length") !== "0" ? await response.json() as ApiError : undefined
+    };
 }
 ```
 
-No framework, no ORM, no boilerplate. Authorization, parameters, type safety — from a SQL file.
+No framework, no ORM, no boilerplate. The named placeholder `:order_id` — used three times, bound once — *is* the API parameter, and every result key is typed, down to the `@single` scalar and the column shapes. `ApiResult<T>` carries the status and a typed error, so failures are type-safe too.
 
 ## Endpoint Sources
 
@@ -107,9 +114,51 @@ where $1 is null or department_id = $1;
 
 Same pattern for PostgreSQL functions via `comment on function ... is '...'`. No middleware to register, no decorators, no controllers — the SQL is the source of truth. See [all annotations](https://npgsqlrest.github.io/annotations/).
 
+## Tests Are SQL Files Too
+
+No test framework, no running server, no mocks. `npgsqlrest --test` invokes the **real endpoint pipeline in-process, on the test's own transaction** — insert fixtures, call the endpoint (it sees your uncommitted rows), assert with SQL, roll back:
+
+```sql
+-- tests/get_users.test.sql
+begin;
+
+insert into users (email) values ('fixture@example.com');
+
+/*
+GET /api/get-users
+# @claim user_id=1
+*/
+select status = 200, 'authenticated caller gets 200' from _response;
+select body::jsonb @> '[{"email": "fixture@example.com"}]', 'fixture is listed' from _response;
+
+rollback;
+```
+
+```
+npgsqlrest ./config.json --test
+
+PASS  tests/get_users.test.sql  (2 assertions, 52ms)
+19 passed, 0 failed, 0 error(s)  —  19 assertions in 9 files
+endpoint coverage: 2/2 (100%)
+```
+
+Parallel isolated connections, throwaway test databases (`create database app_test_{rnd5}` as a plain setup step), per-test database clones, tags, JUnit XML, and **endpoint coverage** with a CI threshold gate — [Testing Guide](https://npgsqlrest.github.io/guide/testing).
+
+## Watch Mode
+
+```sh
+npgsqlrest ./config.json --watch
+```
+
+Save a `.sql` file and the running API restarts with the change (~1s). `create or replace` a function in psql and the endpoint is live seconds later — **the database itself is watched**, annotations included. The TypeScript client regenerates every cycle, so your frontend types follow your SQL as you type. Add `--test` and it becomes a millisecond test loop instead — a changed test re-runs alone; a changed endpoint rebuilds in-process. [Watch Mode](https://npgsqlrest.github.io/config/watch).
+
 ## Features
 
 - **Multi-command SQL scripts** — multiple statements in one file execute as a batch, returning named result sets
+- **Named parameters in SQL files** — `where email = :email`; the placeholder is the API parameter, repeated names bind once
+- **SQL test runner** (`--test`) — tests as plain SQL files, in-process endpoint invocation inside the test's transaction, throwaway test databases, JUnit XML, endpoint-coverage gating
+- **Watch mode** (`--watch`) — restart on SQL file, configuration, and database routine changes; test watch re-runs in milliseconds
+- **MCP server** — `@mcp` exposes any endpoint as a Model Context Protocol tool for AI agents, same auth and rate limits
 - **TypeScript/JS code generation** and `.http` files — types flow from PostgreSQL to your frontend
 - **AOT-compiled native binaries** — zero dependencies, instant startup
 - [**6.1x faster than PostgREST**](https://npgsqlrest.github.io/blog/postgresql-rest-api-benchmark-2026.html) at 100 concurrent users
@@ -142,7 +191,7 @@ Same pattern for PostgreSQL functions via `comment on function ... is '...'`. No
 
 ## Claude Code skill
 
-A [Claude Code](https://claude.com/claude-code) skill that teaches the agent how to build with NpgsqlRest — both endpoint sources (database functions/procedures/tables/views and `.sql` files), the full annotation set, configuration, HTTP custom types, proxy, caching, auth, SSE, and MCP. It lives in [`.claude/skills/npgsqlrest/`](.claude/skills/npgsqlrest/) and bundles a complete annotation reference and a full annotated `appsettings.json`.
+A [Claude Code](https://claude.com/claude-code) skill that teaches the agent how to build with NpgsqlRest — both endpoint sources (database functions/procedures/tables/views and `.sql` files), the full annotation set, configuration, HTTP custom types, proxy, caching, auth, SSE, MCP, the SQL test runner (`--test`), and watch mode (`--watch`). It lives in [`.claude/skills/npgsqlrest/`](.claude/skills/npgsqlrest/) and bundles a complete annotation reference and a full annotated `appsettings.json`.
 
 Install it for your own NpgsqlRest projects — per-user (available everywhere):
 
@@ -158,7 +207,7 @@ done
 
 ## About
 
-NpgsqlRest is built and maintained by [Vedran Bilopavlović](https://www.linkedin.com/in/vb-software/). The C# library, parser, codegen, and runtime are hand-written, covered by 1,800+ integration tests, and battle-tested in production.
+NpgsqlRest is built and maintained by [Vedran Bilopavlović](https://www.linkedin.com/in/vb-software/). The C# library, parser, codegen, and runtime are hand-written, covered by 2,394 integration tests, and battle-tested in production.
 
 ## Contributing
 
diff --git a/changelog/v3.19.0.md b/changelog/v3.19.0.md
index 2f64d0e9..f93848de 100644
--- a/changelog/v3.19.0.md
+++ b/changelog/v3.19.0.md
@@ -26,10 +26,12 @@ insert into app.users (id, email, name) values (100, 'x@example.com', 'Fixture')
 GET /api/get-users
 # @claim user_id=1
 */
-select (select status from _response) = 200,
-       'authenticated caller gets 200';
-select (select body::jsonb @> '[{"email": "x@example.com"}]' from _response),
-       'the fixture user is listed';
+select status = 200,
+       'authenticated caller gets 200'
+from _response;
+select body::jsonb @> '[{"email": "x@example.com"}]',
+       'the fixture user is listed'
+from _response;
 
 rollback;
 ```
@@ -119,8 +121,9 @@ Each HTTP block's response is captured into its own **temp table** on the test's
 Naming: a file with **one** HTTP block uses `ResponseTempTable.Name` (default **`_response`**); a file with **two or more** uses `ResponseTempTable.MultiNamePattern` (default **`_response_{n}`**) where `{n}` is the block's 1-based position — `_response_1`, `_response_2`, … A block with `# @response name` uses that name instead (it still counts in the numbering of the others). Column names are configurable; setting one to null/empty omits that column.
 
 ```sql
-select (select body::jsonb ->> 'email' from _response) = 'grace@example.com',
-       'email is normalized to lowercase';
+select body::jsonb ->> 'email' = 'grace@example.com',
+       'email is normalized to lowercase'
+from _response;
 ```
 
 **Debugging captured responses** — temp tables vanish with the test's rollback and connection, so you cannot inspect them afterwards (and re-issuing the request from an `.http` file cannot reproduce a response that depended on the test's uncommitted fixtures). Set **`ResponseTempTable.DebugTable`** (e.g. `"_responses_debug"`; default `null` = off) and every captured response is **also mirrored into a permanent table** — written on a separate autocommit connection, immune to rollbacks, recreated at the start of every run so it always holds the last run. One table covers everything: each HTTP block adds one row, with `test_file`, `block` (that block's response-table name — `_response`, a `_response_{n}` ordinal, or the `# @response` name), `method`, `path`, `status`, `body`, `content_type`, `headers`, `is_success`, and `captured_at` — so after a run you can open a query editor and dig into any response with jsonb operators. The temp-table semantics are unchanged; enabling it prints a loud warning (debugging aid — do not enable in CI). In the fresh-test-database workflow combine it with `Keep: true`, or teardown drops the database and the mirror with it.
@@ -136,7 +139,7 @@ begin;
 \i  ./shared/reset_counters.sql -- path relative to the cwd, like every other configured path
 
 /* GET /api/get-users */
-select (select jsonb_array_length(body::jsonb) from _response) = 5, 'seed + fixture users listed';
+select jsonb_array_length(body::jsonb) = 5, 'seed + fixture users listed' from _response;
 
 rollback;
 ```
@@ -255,7 +258,7 @@ Results are **per assertion** (like pgTAP/xUnit — each boolean `SELECT` / DO b
 PASS  tests/login_succeeds.test.sql  (3 assertions, 50ms)
 FAIL  tests/get_users.test.sql  (49ms)
         ✗ the caller is excluded — 2 of 3 users listed  [tests/get_users.test.sql:17]
-        select (select jsonb_array_length(body::jsonb) from _response) = 2, …
+        select jsonb_array_length(body::jsonb) = 2, …
 
 18 passed, 1 failed, 0 error(s)  —  19 assertions in 9 files
 ```
diff --git a/docker/Dockerfile.jit b/docker/Dockerfile.jit
index 5b0ce475..8fe063c1 100644
--- a/docker/Dockerfile.jit
+++ b/docker/Dockerfile.jit
@@ -24,10 +24,13 @@ COPY NpgsqlRest/ NpgsqlRest/
 # Shared source compiled into NpgsqlRest.csproj (<Compile Include="..\NpgsqlRest.Common\*.cs"/> + global
 # usings). Without this the JIT build fails: NpgsqlRest.GlobalUsings.g.cs -> CS0234 'NpgsqlRest.Common'.
 COPY NpgsqlRest.Common/ NpgsqlRest.Common/
+# NOTE: `COPY NpgsqlRestClient/*.cs` is NOT recursive — every SUBFOLDER of NpgsqlRestClient must be
+# copied explicitly below, or the JIT build fails with CS0234/CS0246 (this bit Fido2 and Testing already).
 COPY NpgsqlRestClient/*.cs NpgsqlRestClient/
 COPY NpgsqlRestClient/*.csproj NpgsqlRestClient/
 COPY NpgsqlRestClient/appsettings.json NpgsqlRestClient/
 COPY NpgsqlRestClient/Fido2/ NpgsqlRestClient/Fido2/
+COPY NpgsqlRestClient/Testing/ NpgsqlRestClient/Testing/
 COPY plugins/ plugins/
 
 # Build and publish
diff --git a/npm/package.json b/npm/package.json
index 6cefc2e8..53675f0e 100644
--- a/npm/package.json
+++ b/npm/package.json
@@ -1,6 +1,6 @@
 {
   "name": "npgsqlrest",
-  "version": "3.18.2",
+  "version": "3.19.0",
   "description": "Automatic REST API for PostgreSQL Databases Client Build",
   "scripts": {
     "postinstall": "node postinstall.js",
diff --git a/version.txt b/version.txt
index 05d97541..209f5795 100644
--- a/version.txt
+++ b/version.txt
@@ -1 +1 @@
-3.18.2
\ No newline at end of file
+3.19.0
\ No newline at end of file