Configuration Guide

NpgsqlRest can be configured through multiple sources, each with different precedence levels. Common configuration sources are configuration files, usually different versions for different environments, environment variables, and command-line arguments.

Configuration Sources

NpgsqlRest reads configuration from the following sources (in order of precedence, lowest to highest):

1. Configuration files (appsettings.json, then appsettings.Development.json)
2. Command-line arguments

Environment variables can be referenced in configuration values using {VARIABLE_NAME} syntax. This works in both configuration files and command-line arguments.

Use command-line arguments to override any configuration value.

Default Values

If a configuration value is not explicitly set in any source, NpgsqlRest uses the default value. All default values are defined in the default configuration file.

Configuration Files

Default Configuration Files

By default, NpgsqlRest loads configuration files from the current working directory in this order:

1. appsettings.json
2. appsettings.Development.json (overrides values from the first)

Both files are optional — no error occurs if either is missing. You can specify additional or alternative configuration files using command-line arguments.

# Use default appsettings.json and/or appsettings.Development.json from current directory
npgsqlrest

# Specify a custom configuration file
npgsqlrest appsettings.production.json

# Load multiple configuration files (later files override earlier ones)
npgsqlrest appsettings.json appsettings.production.json appsettings.local.json

Optional Configuration Files

Use the -o or --optional switch to mark configuration files as optional. Optional files won't cause an error if they don't exist:

# appsettings.local.json is optional - no error if missing
npgsqlrest appsettings.json -o appsettings.local.json

# Multiple optional files
npgsqlrest appsettings.json --optional development.json --optional local.json

Configuration File Format

Configuration files use standard JSON format with support for comments:

{
  // Application identification
  "ApplicationName": "MyApi",

  // Database connection
  "ConnectionStrings": {
    "Default": "Host=localhost;Database=mydb;Username=user;Password=pass"
  },

  // NpgsqlRest options
  "NpgsqlRest": {
    "UrlPathPrefix": "/api",
    "RequiresAuthorization": false
  }
}

Environment Variables

By default, environment variable binding is disabled. Instead, environment variables can be referenced in configuration values using {VARIABLE_NAME} syntax:

{
  "ConnectionStrings": {
    "Default": "Host={DB_HOST};Database={DB_NAME};Username={DB_USER};Password={DB_PASS}"
  }
}

This works in both configuration files and command-line arguments.

For non-string configuration values, use the quoted form "{VARIABLE_NAME}" in the configuration file. The value will be automatically parsed to the appropriate type:

{
  "NpgsqlRest": {
    "CommandTimeout": "{COMMAND_TIMEOUT}",
    "RequiresAuthorization": "{REQUIRES_AUTH}"
  }
}

Enabling Environment Variable Binding

To enable automatic environment variable binding (where variables override configuration values directly), set AddEnvironmentVariables to true:

{
  "Config": {
    "AddEnvironmentVariables": true
  }
}

When enabled, environment variables can override any configuration value. The naming convention uses double underscores (__) to represent JSON hierarchy levels:

# Override a top-level setting
export ApplicationName=MyApi

# Override nested settings (use __ for hierarchy)
export ConnectionStrings__Default="Host=localhost;Database=mydb"
export NpgsqlRest__UrlPathPrefix="/api/v2"
export NpgsqlRest__RequiresAuthorization=true

# Then run
npgsqlrest

Environment Variable Naming Rules

JSON Path	Environment Variable
ApplicationName	ApplicationName
ConnectionStrings.Default	ConnectionStrings__Default
NpgsqlRest.UrlPathPrefix	NpgsqlRest__UrlPathPrefix
Auth.CookieAuth.Enabled	Auth__CookieAuth__Enabled

Command-Line Arguments

Command-line arguments have the highest precedence and override all other configuration sources. Use the --key=value syntax:

# Override settings via command line
npgsqlrest --ApplicationName=MyApi --NpgsqlRest:UrlPathPrefix=/api/v2

# Override connection string
npgsqlrest --ConnectionStrings:Default="Host=localhost;Database=mydb"

# Combine with configuration files
npgsqlrest appsettings.json --NpgsqlRest:RequiresAuthorization=false

Command-Line Syntax Rules

• Use --key=value format
• Use colons (:) to separate hierarchy levels (alternative to __)
• Keys are case-insensitive
• Boolean values: true, false, 1, 0

# These are equivalent
npgsqlrest --npgsqlrest:urlpathprefix=/api
npgsqlrest --NpgsqlRest:UrlPathPrefix=/api
npgsqlrest --NPGSQLREST:URLPATHPREFIX=/api

Configuration Precedence Example

Consider this scenario with multiple configuration sources:

appsettings.json:

{
  "ApplicationName": "DefaultApp",
  "NpgsqlRest": {
    "UrlPathPrefix": "/api",
    "RequiresAuthorization": true
  }
}

Environment variables:

export NpgsqlRest__UrlPathPrefix="/api/v2"

Command line:

npgsqlrest --NpgsqlRest:RequiresAuthorization=false

Resulting configuration:

Setting	Value	Source
ApplicationName	"DefaultApp"	appsettings.json
NpgsqlRest.UrlPathPrefix	"/api/v2"	Environment variable
NpgsqlRest.RequiresAuthorization	false	Command line

Quick Reference

Common Command-Line Overrides

# Database connection
npgsqlrest --ConnectionStrings:Default="Host=localhost;Database=mydb;Username=user;Password=pass"

# Change listening URL
npgsqlrest --Urls="http://localhost:8080"

# Disable authorization for development
npgsqlrest --NpgsqlRest:RequiresAuthorization=false

# Set log level
npgsqlrest --Log:MinimalLevels:NpgsqlRest=Debug

Configuration Structure Overview

This section provides a complete overview of the NpgsqlRest configuration file structure.

{
  // Application Identification
  "ApplicationName": null,
  "EnvironmentName": "Production",
  "Urls": "http://localhost:8080",
  "StartupMessage": "Started in {time}, listening on {urls}, version {version}",

  // Configuration Options
  "Config": { ... },

  // Database Connections
  "ConnectionStrings": { ... },
  "ConnectionSettings": { ... },

  // Server & SSL
  "Ssl": { ... },
  "Kestrel": { ... },

  // Security
  "DataProtection": { ... },
  "Auth": { ... },
  "Antiforgery": { ... },

  // Threading
  "ThreadPool": { ... },

  // Logging
  "Log": { ... },

  // Performance & Features
  "ResponseCompression": { ... },
  "StaticFiles": { ... },
  "Cors": { ... },
  "CommandRetryOptions": { ... },
  "CacheOptions": { ... },
  "RateLimiterOptions": { ... },

  // Error Handling
  "ErrorHandlingOptions": { ... },

  // Core API Options
  "NpgsqlRest": {
    // Connection & Query Settings
    "ConnectionName": null,
    "UseMultipleConnections": false,
    "CommandTimeout": null,

    // Schema & Name Filtering
    "SchemaSimilarTo": null,
    "SchemaNotSimilarTo": null,
    "IncludeSchemas": [],
    "ExcludeSchemas": [],
    "NameSimilarTo": null,
    "NameNotSimilarTo": null,
    "IncludeNames": [],
    "ExcludeNames": [],

    // URL & Naming Options
    "UrlPathPrefix": "/api",
    "KebabCaseUrls": true,
    "CamelCaseNames": true,
    "CommentsMode": "OnlyWithHttpTag",

    // Request Handling
    "DefaultHttpMethod": null,
    "DefaultRequestParamType": null,
    "RequiresAuthorization": false,

    // Request Headers
    "RequestHeadersMode": "Parameter",
    "RequestHeadersContextKey": "request.headers",
    "RequestHeadersParameterName": "_headers",
    "InstanceIdRequestHeaderName": null,
    "CustomRequestHeaders": [],
    "ExecutionIdHeaderName": "X-NpgsqlRest-ID",

    // Server-Sent Events
    "DefaultServerSentEventsEventNoticeLevel": "INFO",
    "ServerSentEventsResponseHeaders": { ... },

    // Logging
    "LogConnectionNoticeEvents": false,
    "LogConnectionNoticeEventsMode": "FirstStackFrameAndMessage",
    "LogCommands": false,
    "LogCommandParameters": false,

    // Nested Configuration Objects
    "RoutineOptions": { ... },
    "UploadOptions": { ... },
    "AuthenticationOptions": { ... },
    "HttpFileOptions": { ... },
    "OpenApiOptions": { ... },
    "ClientCodeGen": { ... },
    "CrudSource": { ... }
  }
}

Top-Level Settings

These settings configure the application identity and server binding.

Setting	Type	Default	Description
ApplicationName	string	null	Application identifier. Defaults to the top-level directory name if not set.
EnvironmentName	string	"Production"	Environment designation (Development, Staging, Production).
Urls	string	"http://localhost:8080"	Server listening URLs. Separate multiple URLs with semicolons.
StartupMessage	string	"Started in {time}, listening on {urls}, version {version}"	Message displayed on startup. Supports placeholders.

Urls Configuration

The Urls setting accepts multiple URLs separated by semicolons:

{
  "Urls": "http://localhost:8080;https://localhost:8443"
}

To listen on all interfaces:

{
  "Urls": "http://0.0.0.0:8080;https://0.0.0.0:8443"
}

Startup Message

Customize the startup message with placeholders:

{
  "StartupMessage": "Started in {time}, listening on {urls}, version {version}, env: {environment}"
}

Available placeholders:

• {time} - Startup time
• {urls} - Listening URLs
• {version} - Application version
• {environment} - Environment name (from EnvironmentName)
• {application} - Application name (from ApplicationName)

Config Section Options

The Config section controls how the configuration file itself is processed.

Setting	Type	Default	Description
ExposeAsEndpoint	string	null	Expose current configuration to an endpoint for debugging. Set to a path like "/config" to enable. Passwords in connection strings are not exposed.
AddEnvironmentVariables	bool	false	Allow environment variables to override configuration settings.
ParseEnvironmentVariables	bool	true	Parse {ENV_VAR_NAME} placeholders in config values and replace with environment variable values.

Environment Variable Override

When AddEnvironmentVariables is true, environment variables can override any configuration setting. Use double underscores for nested keys:

# Override ConnectionStrings.Default
export ConnectionStrings__Default="Host=production-server;..."

# Override NpgsqlRest.UrlPathPrefix
export NpgsqlRest__UrlPathPrefix="/v2/api"

Environment Variable Parsing

When ParseEnvironmentVariables is true (default), you can use {ENV_VAR} syntax anywhere in configuration values:

{
  "ConnectionStrings": {
    "Default": "Host={PGHOST};Port={PGPORT};Database={PGDATABASE};Username={PGUSER};Password={PGPASSWORD}"
  }
}

This allows sensitive values to be kept in environment variables rather than in the configuration file.

Next Steps

• Comment Annotations Guide - Use SQL comments to configure endpoints
• Annotations Reference - Complete reference of all annotations
• Configuration Reference - Complete reference for all configuration options
• Connection Settings - Configure database connections
• Server & SSL - Configure HTTPS and Kestrel web server
• Authentication - Set up authentication methods