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. :::

Each annotation has its own page with:

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

• 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 - Enable endpoint for specific tags
• DISABLED - Disable endpoint 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)

• AUTHORIZE - Require authentication
• ALLOW_ANONYMOUS - Allow unauthenticated access
• LOGIN - Mark as sign-in endpoint
• LOGOUT - Mark as sign-out endpoint

• BASIC_AUTH - Enable HTTP Basic Authentication
• BASIC_AUTH_REALM - Set authentication realm
• BASIC_AUTH_COMMAND - Set validation function

• REQUEST_PARAM_TYPE - Query string vs body parameters
• REQUEST_HEADERS_MODE - Control header passing
• REQUEST_HEADERS_PARAMETER_NAME - Header parameter name
• BODY_PARAMETER_NAME - Body parameter name
• QUERY_STRING_NULL_HANDLING - NULL handling in query strings
• VALIDATE - Parameter validation before database execution

• 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

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

• RAW - Return raw text instead of JSON
• SEPARATOR - Column separator for raw output
• NEW_LINE - Row separator for raw output
• COLUMN_NAMES - Include column headers

• CACHED - Enable response caching
• CACHE_EXPIRES_IN - Set cache expiration
• CACHE_PROFILE - Select a named cache profile (multiple backends, dynamic TTL, skip-on-condition rules)

• BUFFER_ROWS - Row buffering count
• COMMAND_TIMEOUT - Query timeout
• RETRY_STRATEGY - Retry behavior

• Interval Format - Time/duration format for timeouts and cache expiration

• SSE - Enable Server-Sent Events
• SSE_EVENTS_LEVEL - Notice level for SSE
• SSE_EVENTS_SCOPE - SSE distribution scope

• UPLOAD - File upload handling

• ERROR_CODE_POLICY - Error handling policy
• RATE_LIMITER_POLICY - Rate limiting policy

• USER_CONTEXT - Enable user context
• USER_PARAMETERS - Add user parameters
• CONNECTION - Named database connection
• SECURITY_SENSITIVE - Obfuscate logs

• PARAM - Rename, retype, set defaults, and configure parameters
• PARAMETER_HASH - Hash one parameter using another
• ENCRYPT - Encrypt parameter values before sending to PostgreSQL
• DECRYPT - Decrypt result column values before returning to client

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

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 Parameters - Custom key-value settings