NpgsqlRest

Appearance

Comments

Annotations Reference ​

Complete reference for all NpgsqlRest comment annotations. For an introduction to how annotations work, see the Comment Annotations Guide.

INFO

All annotations work in both PostgreSQL function/procedure comments (COMMENT ON FUNCTION ...) and SQL file endpoints (-- and /* */ comments in .sql files). The "SQL File Annotations" section below lists annotations that are specific to SQL files.

How to Use This Reference ​

Each annotation has its own page with:

  • Recognized keywords
  • Syntax explanation
  • Working examples from the test suite
  • Related annotations

Annotation Categories ​

HTTP & Routing ​

  • HTTP - Expose function as HTTP endpoint
  • PATH - Set custom endpoint path
  • PROXY - Mark endpoint as reverse proxy
  • PROXY_OUT - Execute function first, then forward result to upstream
  • ENABLED - Re-enable an endpoint after @disabled, optionally only for specific tags
  • DISABLED - Disable endpoint, optionally only for specific tags
  • TAGS - Filter annotations by tags
  • OPENAPI - Hide from the OpenAPI document or override the section tag
  • MCP - Expose a routine as a Model Context Protocol (MCP) tool for AI agents
  • HTTP CUSTOM TYPES - Define HTTP request on composite type for external API calls
  • INTERNAL - Mark endpoint as internal-only (accessible via proxy/HTTP client types, not public HTTP)

Authorization ​

Basic Authentication ​

Request Configuration ​

Response Configuration ​

  • Response Headers - Set custom response headers
  • RESPONSE_NULL_HANDLING - NULL handling in responses
  • NESTED - Serialize composite type columns as nested JSON objects
  • SINGLE - Return a single record as a JSON object instead of an array
  • VOID - Force endpoint to return 204 No Content

Table Format Output ​

  • TABLE_FORMAT - table_format, excel_file_name, excel_sheet for HTML table and Excel rendering

Client Code Generation ​

  • TSCLIENT - Control TypeScript client generation per endpoint (disable, module names, URL exports, TanStack Query hooks opt-out)
  • DARTCLIENT - Control Dart (Flutter) client generation per endpoint (disable, module names, URL exports, response options)

Raw Output Mode ​

Caching ​

Performance ​

Format References ​

Server-Sent Events ​

Upload ​

Policies ​

Context & Security ​

Parameter Annotations ​

SQL File Annotations ​

  • DEFINE_PARAM - Define virtual HTTP parameters not bound to SQL
  • RESULT_NAME - Rename result keys in multi-command SQL file endpoints
  • SKIP - Exclude commands from multi-command results
  • RETURNS - Skip Describe step and resolve return columns from a composite type (for runtime-created temp tables)

Test File Annotations ​

These apply only to test files run by the SQL test runner (npgsqlrest --test) — not to endpoint SQL files or routine comments:

  • TEST @setup - Run named steps before an individual test file
  • TEST @teardown - Run named steps after an individual test file, always
  • TEST @connection - Run a test file on a different named connection
  • TEST @tag - Tag a test file for Tag/ExcludeTag filtering
  • TEST @claim - Set the acting principal for an in-process endpoint call (HTTP block directive)
  • TEST @response - Name the captured response temp table (HTTP block directive)

Custom ​

Comments