NpgsqlRest Options

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

Overview

{
  "NpgsqlRest": {
    "ConnectionName": null,
    "UseMultipleConnections": false,
    "CommandTimeout": null,
    "SchemaSimilarTo": null,
    "SchemaNotSimilarTo": null,
    "IncludeSchemas": null,
    "ExcludeSchemas": null,
    "NameSimilarTo": null,
    "NameNotSimilarTo": null,
    "IncludeNames": null,
    "ExcludeNames": null,
    "CommentsMode": "OnlyWithHttpTag",
    "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",
    "DefaultServerSentEventsEventNoticeLevel": "INFO",
    "ServerSentEventsResponseHeaders": {},
    "RoutineOptions": { ... }
  }
}

See Routine Options for RoutineOptions configuration.

Connection Settings

Setting	Type	Default	Description
ConnectionName	string	null	Connection name from ConnectionStrings section. Uses first available if null.
UseMultipleConnections	bool	false	Allow individual routines to use different connections from ConnectionStrings.
CommandTimeout	string	null	Command timeout in PostgreSQL interval format (e.g., "30 seconds", "1 minute"). Uses default 30 seconds if null. Can be overridden per endpoint with command_timeout annotation.

Schema and Name Filtering

Filter which PostgreSQL routines are exposed as endpoints.

Setting	Type	Default	Description
SchemaSimilarTo	string	null	Include schemas matching this SQL SIMILAR TO pattern.
SchemaNotSimilarTo	string	null	Exclude schemas matching this SQL SIMILAR TO pattern.
IncludeSchemas	array	null	List of schema names to include.
ExcludeSchemas	array	null	List of schema names to exclude.
NameSimilarTo	string	null	Include routine names matching this SQL SIMILAR TO pattern.
NameNotSimilarTo	string	null	Exclude routine names matching this SQL SIMILAR TO pattern.
IncludeNames	array	null	List of routine names to include.
ExcludeNames	array	null	List of routine names to exclude.

Filtering Examples

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"
  }
}

Comments Mode

Setting	Type	Default	Description
CommentsMode	string	"OnlyWithHttpTag"	How comment annotations affect endpoint creation.

Available modes:

Mode	Description
Ignore	Create all endpoints, ignore comment annotations.
ParseAll	Create all endpoints, parse comment annotations to modify them.
OnlyWithHttpTag	Only create endpoints for routines with HTTP tag in comments (default).

URL and Naming

Setting	Type	Default	Description
UrlPathPrefix	string	"/api"	URL prefix for all generated endpoints.
KebabCaseUrls	bool	true	Convert URL paths to kebab-case from PostgreSQL names.
CamelCaseNames	bool	true	Convert parameter names to camelCase from PostgreSQL names.

URL Examples

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

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

Authorization

Setting	Type	Default	Description
RequiresAuthorization	bool	true	Force all endpoints to require authorization. Can be overridden per endpoint via comment annotations.

Logging

Setting	Type	Default	Description
LogConnectionNoticeEvents	bool	true	Log PostgreSQL connection events (triggered by RAISE statements).
LogConnectionNoticeEventsMode	string	"FirstStackFrameAndMessage"	How to format notice event logs.
LogCommands	bool	false	Log every executed command and query at debug level.
LogCommandParameters	bool	false	Include parameter values in command logs. Only applies when LogCommands is true.

Notice Event Modes

Mode	Description
MessageOnly	Log only the message.
FirstStackFrameAndMessage	Log first stack frame and message (default).
FullStackAndMessage	Log full stack trace and message.

HTTP Method and Parameters

Setting	Type	Default	Description
DefaultHttpMethod	string	null	Force HTTP method for all endpoints (GET, POST, PUT, DELETE, etc.).
DefaultRequestParamType	string	null	Force parameter location for all endpoints (QueryString or BodyJson).

Default Behavior

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

Request Headers

Setting	Type	Default	Description
RequestHeadersMode	string	"Parameter"	How to send request headers to PostgreSQL routines.
RequestHeadersContextKey	string	"request.headers"	Context variable name when mode is Context.
RequestHeadersParameterName	string	"_headers"	Parameter name when mode is Parameter.
CustomRequestHeaders	object	{}	Custom headers added to requests before sending to PostgreSQL.
InstanceIdRequestHeaderName	string	null	Header name for NpgsqlRest instance ID. Set to null to disable.
ExecutionIdHeaderName	string	"X-NpgsqlRest-ID"	Header name for request tracking and SSE correlation.

Request Headers Modes

Mode	Description
Ignore	Don't send request headers to routines.
Context	Set context variable context.headers with JSON string via set_config().
Parameter	Send headers to parameter named by RequestHeadersParameterName. Parameter must be JSON/text type with default value.

Server-Sent Events

Setting	Type	Default	Description
DefaultServerSentEventsEventNoticeLevel	string	"INFO"	Minimum PostgreSQL notice level for SSE events (INFO, NOTICE, WARNING).
ServerSentEventsResponseHeaders	object	{}	Custom headers added to SSE responses.

Complete Example

Production configuration:

{
  "NpgsqlRest": {
    "ConnectionName": null,
    "UseMultipleConnections": true,
    "CommandTimeout": "30 seconds",
    "IncludeSchemas": ["api"],
    "ExcludeSchemas": ["internal"],
    "CommentsMode": "OnlyWithHttpTag",
    "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
  }
}

Related

• 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
• sse annotation - Enable Server-Sent Events
• Comment Annotations Guide - How annotations work
• Configuration Guide - How configuration works

Next Steps

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