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

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

Basic Authentication

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

Request Configuration

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

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

Raw Output Mode

• 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

Caching

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

Performance

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

Format References

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

Server-Sent Events

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

Upload

• UPLOAD - File upload handling

Policies

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

Context & Security

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

Parameter Annotations

• 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

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)

Custom

• Custom Parameters - Custom key-value settings