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",
    "QueryStringNullHandling": "Ignore",
    "TextResponseNullHandling": "EmptyString",
    "DefaultServerSentEventsEventNoticeLevel": "INFO",
    "ServerSentEventsResponseHeaders": {},
    "RoutineOptions": { ... },
    "AuthenticationOptions": { ... },
    "CrudSource": { ... },
    "UploadOptions": { ... },
    "ClientCodeGen": { ... },
    "HttpFileOptions": { ... },
    "OpenApiOptions": { ... }
  }
}

See related configuration pages:

• Routine Options for RoutineOptions configuration
• Authentication Options for AuthenticationOptions configuration
• CRUD Source for CrudSource configuration
• Upload Options for UploadOptions configuration
• Code Generation for ClientCodeGen configuration
• HTTP Files for HttpFileOptions configuration
• OpenAPI Options for OpenApiOptions 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 using interval format (e.g., "30s", "1m"). 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 annotation in comments (default).

With the default OnlyWithHttpTag mode, routines without the HTTP annotation in their comment will not be exposed as endpoints. This provides explicit control over which database routines are accessible via the API.

See also CRUD Source CommentsMode for table/view endpoint generation settings.

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"	Execution request header name. Used for request tracking and SSE correlation and in ConnectionSettings.UseJsonApplicationName.

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.

NULL Handling

Setting	Type	Default	Description
QueryStringNullHandling	string	"Ignore"	How empty or "null" query string values are interpreted.
TextResponseNullHandling	string	"EmptyString"	How NULL database results are returned in plain text responses.

QueryStringNullHandling Values

Value	Description
Ignore	No special handling - empty strings stay as empty strings, "null" literal stays as "null" string (default).
EmptyString	Empty query string values are interpreted as NULL values.
NullLiteral	Literal string "null" (case insensitive) is interpreted as NULL value.

TextResponseNullHandling Values

Value	Description
EmptyString	Returns an empty string response with status code 200 OK (default).
NullLiteral	Returns a string literal "NULL" with status code 200 OK.
NoContent	Returns status code 204 NO CONTENT.

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
';

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
• 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

Next Steps

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