NpgsqlRest HTTP middleware general configuration for endpoint generation and request handling.

{
  "NpgsqlRest": {
    "ConnectionName": null,
    "UseMultipleConnections": false,
    "CommandTimeout": null,
    "SchemaSimilarTo": null,
    "SchemaNotSimilarTo": null,
    "IncludeSchemas": null,
    "ExcludeSchemas": null,
    "NameSimilarTo": null,
    "NameNotSimilarTo": null,
    "IncludeNames": null,
    "ExcludeNames": null,
    "CommentsMode": "OnlyAnnotated",
    "UrlPathPrefix": "/api",
    "KebabCaseUrls": true,
    "CamelCaseNames": true,
    "RequiresAuthorization": true,
    "LogConnectionNoticeEvents": true,
    "LogConnectionNoticeEventsMode": "FirstStackFrameAndMessage",
    "LogCommands": false,
    "LogCommandParameters": false,
    "DefaultHttpMethod": null,
    "DefaultRequestParamType": null,
    "RequestHeadersMode": "Parameter",
    "RequestHeadersContextKey": "request.headers",
    "RequestHeadersParameterName": "_headers",
    "InstanceIdRequestHeaderName": null,
    "CustomRequestHeaders": {},
    "ExecutionIdHeaderName": "X-NpgsqlRest-ID",
    "QueryStringNullHandling": "Ignore",
    "TextResponseNullHandling": "EmptyString",
    "DefaultServerSentEventsEventNoticeLevel": "INFO",
    "ServerSentEventsResponseHeaders": {},
    "RoutineOptions": { ... },
    "AuthenticationOptions": { ... },
    "SqlFileSource": { ... },
    "UploadOptions": { ... },
    "ClientCodeGen": { ... },
    "HttpFileOptions": { ... },
    "OpenApiOptions": { ... }
  }
}

See related configuration pages:

• Routine Options for RoutineOptions configuration
• Authentication Options for AuthenticationOptions configuration
• SQL File Source for SqlFileSource configuration
• Upload Options for UploadOptions configuration
• Code Generation for ClientCodeGen configuration
• HTTP Files for HttpFileOptions configuration
• OpenAPI Options for OpenApiOptions configuration

Filter which PostgreSQL routines are exposed as endpoints.

Include only specific schemas:

{
  "NpgsqlRest": {
    "IncludeSchemas": ["api", "public"]
  }
}

Exclude internal schemas:

{
  "NpgsqlRest": {
    "ExcludeSchemas": ["pg_catalog", "information_schema", "internal"]
  }
}

Filter by name pattern:

{
  "NpgsqlRest": {
    "NameSimilarTo": "api_%",
    "NameNotSimilarTo": "%_internal"
  }
}

Available modes:

With the default OnlyAnnotated mode, routines without an HTTP (or endpoint-requesting plugin) annotation in their comment will not be exposed as endpoints. This provides explicit control over which database routines are accessible via the API.

::: info Client vs. library default The standalone client (npgsqlrest executable) defaults to OnlyAnnotated since 3.17.0. The C# library (NpgsqlRestOptions.CommentsMode) defaults to OnlyWithHttpTag; the two behave identically unless a plugin (such as MCP) requests endpoints. :::

With default settings, get_user_profile becomes /api/get-user-profile.

{
  "NpgsqlRest": {
    "UrlPathPrefix": "/v1/api",
    "KebabCaseUrls": true
  }
}

When DefaultHttpMethod is null:

• GET is used when routine is not volatile, or name starts with get_, contains _get_, or ends with _get
• POST is used otherwise

When DefaultRequestParamType is null:

• QueryString for GET and DELETE endpoints
• BodyJson for all other methods

::: tip New in 3.13.0 WrapInTransaction and BeforeRoutineCommands options for connection pooler compatibility and pre-routine SQL commands. :::

This is required for connection poolers in transaction mode — including PgBouncer transaction-pool, AWS RDS Proxy in transaction mode, and Supabase Pooler. Previously, set_config(name, value, false) would set the GUC at the session level on the underlying PostgreSQL backend. With a transaction-mode pooler, the same backend is reused for unrelated client requests, which means session-scoped GUCs from one request could be visible to the next. With WrapInTransaction = true, GUCs are scoped to the request transaction and discarded on COMMIT.

The default remains false to preserve existing behavior; it is safe to leave off when using Npgsql's native pool only (which issues DISCARD ALL on connection return).

{
  "NpgsqlRest": {
    "WrapInTransaction": true
  }
}

Each entry can be either a raw SQL string (no parameters) or an object with Sql and Parameters. Each parameter has a Source (Claim, RequestHeader, or IpAddress) and an optional Name (claim type or header name). Parameter values are bound at request time from HttpContext — claim and header values are passed as parameterized SQL inputs (no string interpolation, no injection risk).

The most useful pattern is multi-tenant search_path setup driven by a JWT/cookie claim:

{
  "NpgsqlRest": {
    "WrapInTransaction": true,
    "BeforeRoutineCommands": [
      "select set_config('app.request_time', clock_timestamp()::text, true)",
      {
        "Sql": "select set_config('search_path', $1, true)",
        "Parameters": [{ "Source": "Claim", "Name": "tenant_id" }]
      }
    ]
  }
}

Per-request execution order with this config:

1. BEGIN
2. Each BeforeRoutineCommand is added as a NpgsqlBatchCommand (with parameters bound from claims/headers/IP) and dispatched in a single batch.
3. The main routine call.
4. COMMIT.

Steps 1–3 share a single network round-trip.

These settings can be overridden per-endpoint using comment annotations:

comment on function my_func(text) is '
@query_string_null_handling empty_string
@text_response_null_handling no_content
';

When true (default, recommended):

• Z-suffixed and offset-bearing ISO strings (e.g. "2026-05-20T06:00:00Z", "2026-05-20T08:00:00+02:00") are converted to UTC.
• Naive ISO strings with no offset and no Z (e.g. "2026-05-20T06:00:00") are assumed UTC rather than interpreted as the host's local time.

The result is host-TZ-independent: the same JSON payload produces the same stored value regardless of the TZ environment of the process serving the request.

When false, the parsers fall back to the pre-3.16.0 behavior:

• Z / offset-bearing strings are converted to the host's local time zone and tagged Kind=Local.
• Naive strings are parsed as Kind=Unspecified.
• The timestamptz / timetz parsers then re-apply SpecifyKind(Utc) on top of the local-shifted value — silently shifting the stored value by the host's UTC offset on non-UTC hosts.

::: warning Opt-out only — not recommended for new deployments JsonTimestampsAreUtc: false exists as a compatibility escape hatch for callers that genuinely depend on the legacy "naive timestamps are host-local" behavior and cannot be updated to send Z-suffixed values. It reproduces the bug class fixed in 3.16.0. Leave at the default unless you have a specific legacy reason to flip it. :::

Example:

{
  "NpgsqlRest": {
    "JsonTimestampsAreUtc": true
  }
}

Configure Server-Sent Events (SSE) for real-time streaming of PostgreSQL RAISE statements to connected clients.

The DefaultServerSentEventsEventNoticeLevel setting determines which PostgreSQL RAISE statements generate SSE events by default when the level is not specified in the annotation.

::: warning Important SSE events are sent only for the exact level configured, not for "this level and above". For example, if set to NOTICE, only RAISE NOTICE statements generate SSE events—RAISE INFO and RAISE WARNING are ignored. :::

This default can be overridden per-endpoint using the @sse annotation.

{
  "NpgsqlRest": {
    "DefaultServerSentEventsEventNoticeLevel": "NOTICE",
    "ServerSentEventsResponseHeaders": {
      "X-Accel-Buffering": "no"
    }
  }
}

The X-Accel-Buffering: no header is commonly needed when running behind nginx to disable response buffering for SSE streams.

• SSE Annotation - Enable SSE streaming per endpoint
• SSE_EVENTS_LEVEL Annotation - Override notice level per endpoint
• SSE_EVENTS_SCOPE Annotation - Control event distribution scope

::: warning Security A value substituted into 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. a server/environment name). Only allowlisted names are ever read from the environment. :::

Production configuration:

{
  "NpgsqlRest": {
    "ConnectionName": null,
    "UseMultipleConnections": true,
    "CommandTimeout": "30 seconds",
    "IncludeSchemas": ["api"],
    "ExcludeSchemas": ["internal"],
    "CommentsMode": "OnlyAnnotated",
    "UrlPathPrefix": "/api",
    "KebabCaseUrls": true,
    "CamelCaseNames": true,
    "RequiresAuthorization": true,
    "LogConnectionNoticeEvents": true,
    "LogConnectionNoticeEventsMode": "FirstStackFrameAndMessage",
    "LogCommands": false,
    "LogCommandParameters": false,
    "RequestHeadersMode": "Parameter",
    "RequestHeadersParameterName": "_headers",
    "ExecutionIdHeaderName": "X-NpgsqlRest-ID"
  }
}

Development configuration with verbose logging:

{
  "NpgsqlRest": {
    "CommentsMode": "ParseAll",
    "RequiresAuthorization": false,
    "LogConnectionNoticeEvents": true,
    "LogConnectionNoticeEventsMode": "FullStackAndMessage",
    "LogCommands": true,
    "LogCommandParameters": true
  }
}

• http annotation - Expose function as HTTP endpoint
• path annotation - Set custom endpoint path
• request_param_type annotation - Query string vs body parameters
• request_headers_mode annotation - Control header passing
• command_timeout annotation - Set query timeout
• query_string_null_handling annotation - NULL in query strings
• response_null_handling annotation - NULL in responses
• sse annotation - Enable Server-Sent Events
• Comment Annotations Guide - How annotations work
• Configuration Guide - How configuration works

• Routine Options - Configure routine handling options
• Connection Settings - Configure database connections
• Code Generation - Configure code generation options
• Error Handling - Configure error responses