NpgsqlRest

Appearance

Comments
Written with Claude
IMPORTANT

As you may notice, this page and pretty much the entire website were obviously created with the help of AI. I wonder how you could tell? Was it a big "Written With Claude" badge on every page? I moved it to the top now (with the help of AI of course) to make it even more obvious. There are a few blogposts that were written by me manually, the old-fashioned way, I hope there will be more in the future, and those have a similar "Human Written" badge. This project (not the website), on the other hand, is a very, very different story. It took me more than two years of painstaking and unpaid work in my own free time. A story that, hopefully, I will tell someday. But meanwhile, what would you like me to do? To create a complex documentation website with a bunch of highly technical articles with the help of AI and fake it, to give you an illusion that I also did that manually? Like the half of itnernet is doing at this point? How does that makes any sense? Is that even fair to you? Or maybe to create this website manually, the old-fashioned way, just for you? While working a paid job for a salary, most of you wouldn't even get up in the morning. Would you like me to sing you a song while we're at it? For your personal entertainment? Seriously, get a grip. Do you find this information less valuable because of the way this website was created? I give my best to fix it to keep the information as accurate as possible, and I think it is very accurate at this point. If you find some mistakes, inaccurancies or problems, there is a comment section at the bottom of every page, which I also made with the help of the AI. And I woould very much appreciate if you leave your feedback there. Look, I'm just a guy who likes SQL, that's all. If you don't approve of how this website was constructed and the use of AI tools, I suggest closing this page and never wever coming back. And good riddance. And I would ban your access if I could know how. Thank you for your attention to this matter.

Config Section ​

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

json
json
{
  "Config": {
    "AddEnvironmentVariables": false,
    "ParseEnvironmentVariables": true,
    "EnvFile": null,
    "ValidateConfigKeys": "Warning"
  }
}

Settings Reference ​

SettingTypeDefaultDescription
AddEnvironmentVariablesboolfalseAllow environment variables to override configuration settings.
ParseEnvironmentVariablesbooltrueParse {ENV_VAR_NAME} placeholders in config values and replace with environment variable values.
EnvFilestringnullPath to a .env file for loading environment variables. See below.
ValidateConfigKeysstring"Warning"Validate configuration keys against known defaults at startup. See below.

Environment Variable Override ​

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

bash
bash
# 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:

json
json
{
  "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.

Loading from .env File ​

When AddEnvironmentVariables or ParseEnvironmentVariables is true and EnvFile is set, the application will load environment variables from the specified file:

json
json
{
  "Config": {
    "AddEnvironmentVariables": false,
    "ParseEnvironmentVariables": true,
    "EnvFile": ".env"
  }
}

The .env file format supports:

  • KEY=VALUE pairs (one per line)
  • Comments (lines starting with #)
  • Quoted values (both single and double quotes)

Example .env file:

code
# Database connection settings
PGHOST=localhost
PGPORT=5432
PGDATABASE=example_db
PGUSER=postgres
PGPASSWORD=postgres

The variables are loaded into the environment and made available for configuration parsing with the {ENV_VAR_NAME} syntax.

Configuration Key Validation ​

New in 3.8.0

Configuration key validation was added in version 3.8.0.

At startup, NpgsqlRest can validate all configuration keys in appsettings.json against the known defaults schema. This catches typos and unknown keys that would otherwise be silently ignored (e.g., LogCommand instead of LogCommands).

The ValidateConfigKeys setting has three modes:

ModeBehavior
"Warning" (default)Logs warnings for unknown keys, startup continues.
"Error"Logs errors for unknown keys and exits the application.
"Ignore"No validation is performed.
json
json
{
  "Config": {
    "ValidateConfigKeys": "Warning"
  }
}

Example output:

code
[12:34:56 WRN] Unknown configuration key: NpgsqlRest:KebabCaselUrls

Validation also covers the Kestrel section, checking against the known Kestrel schema including Limits, Http2, Http3, and top-level flags like DisableStringReuse and AllowSynchronousIO. User-defined endpoint and certificate names under Endpoints and Certificates remain open-ended and won't trigger warnings.

TIP

Use the --config CLI switch to inspect the current configuration with syntax highlighting, or --validate for a pre-flight check of configuration and database connectivity.

Next Steps ​

Comments