Changelog v4.1.0
Version 4.1.0 (2026-11-21)
This release makes NpgsqlRest easier to work with from an editor or any other tool, and moves it to Npgsql 11.
- "Why is there no endpoint?" has an answer.
npgsqlrest --inspectlists every routine and SQL file that was looked at and did not become an endpoint, each with the reason and what to change. It also says which files were generated for each endpoint, with the name and the line. npgsqlrest --parsereads a comment the way the server does, without a database: which lines are annotations, which are text, which are written as annotations and read by nothing.RequireAtPrefix: an optional strict reading of comments in which only a line that begins with@is an annotation. It is off by default, so nothing changes for existing projects.- Npgsql 11. Performance is the same as 4.0.1 (measured, as JIT and as native AOT).
- Fixes: an upload that ended the server process, a tab between the words of an annotation, quoted identifiers and
$1$2in SQL files, logout without a valid token in an application that only uses JWT, and theNpgsqlRest.Mcppackage, which had never been published to NuGet.
Nothing changes in the behavior of an existing application unless it has one of the four things listed under What to check.
What to check
- A tab inside an annotation now separates words.
@authorize<TAB>adminwas read as one unknown word and gave the endpoint no authorization; it is nowauthorize admin. If a comment has a tab where a space was meant, the annotation takes effect with this release. → details @Name: valueresponse headers. A header line written with the@prefix produced a header named@Name. The prefix is no longer part of the name. → detailsMultiplexingin a connection string is now an error (Npgsql 11). → details- The pool name in Npgsql's metrics is now the application name (Npgsql 11). → details
For tools: what became an endpoint, what did not, and why
A common moment in development: a function or a SQL file is there, and the endpoint is not. The reason was somewhere in the debug log, or nowhere. Now it can be asked for.
npgsqlrest --inspect
Starts like --endpoints (it connects, builds the endpoints, prints JSON and exits) and prints an object with three lists:
json
{
"requireAtPrefix": false,
"endpoints": [ { "method": "GET", "path": "/api/orders", "routine": { "sourceFile": "/app/sql/orders.sql" }, "generated": [ ] } ],
"notExposed": [ ],
"generatedFiles": [ ]
}endpoints is what --endpoints prints (both now mark an endpoint that has no HTTP route, such as an MCP-only tool, with "internalOnly": true). The other two are new.
Like --endpoints and like a normal start, --inspect runs the generators that are enabled, so it writes the client, HTTP and OpenAPI files: that is how it knows their lines.
notExposed: everything that was looked at and is not an endpoint.
json
{
"kind": "function",
"schema": "public",
"name": "get_orders",
"definition": "function public.get_orders(_customer_id integer)\nreturns ...",
"reason": "no_http_annotation",
"message": "Its comment has no HTTP annotation. Under this CommentsMode an endpoint is created only for a comment that has one."
}reason | What it means |
|---|---|
no_comment | It has no comment, and the CommentsMode creates endpoints only for annotated routines. |
no_http_annotation | Its comment (or, for a SQL file, its comments) has no HTTP line. |
unprefixed_annotations | Its HTTP line is written without @ and RequireAtPrefix is on. |
disabled | Its comment has the disabled annotation. |
tag_mismatch | Its HTTP line comes after a for <tags> line that does not name this routine. |
excluded_by_filter | A schema, name or language setting leaves it out (IncludeSchemas, NameNotSimilarTo ...). The message names the setting. Only routines whose comment has an HTTP line are reported, so a database full of unrelated functions adds nothing to the list. |
sql_error | A SQL file that PostgreSQL does not accept, or that the parser rejects. diagnostics has the error. |
empty_file | A SQL file without a statement. |
rejected_by_callback | A source's own endpoint handler returned nothing for it. |
For a SQL file, sourceFile is its path. A SQL file that is not in either list was never read: it is not matched by SqlFileSource:FilePattern (or it is matched by SkipPattern).
--inspect keeps going when a SQL file has an error (as watch mode does), so one broken file does not hide the others.
generated (on each endpoint) and generatedFiles: what the generators wrote.
json
"generated": [
{ "generator": "tsclient", "file": "/app/src/api/orders.ts", "role": "client", "symbol": "getOrders", "line": 42 },
{ "generator": "tsclient", "file": "/app/src/api/ordersHooks.ts", "role": "hooks", "symbol": "useGetOrders", "line": 18 },
{ "generator": "httpfiles", "file": "/app/http/public.http", "role": "requests", "symbol": "GET {{host}}/api/orders", "line": 7 },
{ "generator": "openapi", "file": "/app/openapi.json", "role": "document", "symbol": "public_get_orders_get", "line": 1 }
]symbolis what the endpoint is called in that file: the function, the hook, the request line, the operation id. It is the stable key.lineis where it begins in the file as written by this run. Editing or reformatting the file moves it.generatedFileslists every file once, including the ones that belong to no single endpoint (a types file, the Dart models file, MCP tool schema documents).- The TypeScript client, its hooks, the Dart client, HTTP files and the OpenAPI document report per endpoint.
--endpointshas thegeneratedlist too.
Together with routine.sourceFile this goes both ways: from a routine or SQL file to the code generated for it, and from a generated function back to its source.
npgsqlrest --parse: how a comment is read, without a database
console
npgsqlrest --parse=sql/orders.sql
npgsqlrest --parse-comment=comment.txt
npgsqlrest --parse=- # the SQL file from standard inputIt runs the parsers the server runs, on the text alone:
json
{
"source": "sql_file",
"file": "/app/sql/orders.sql",
"requireAtPrefix": false,
"commentsMode": "OnlyAnnotated",
"endpoint": true,
"statements": 1,
"lines": [
{ "line": 1, "text": "HTTP GET", "kind": "annotation", "name": "http", "owner": "core", "form": "keyword" },
{ "line": 2, "text": "Orders of a customer.", "kind": "text" },
{ "line": 3, "text": "@authorize", "kind": "annotation", "name": "authorize", "owner": "core", "form": "keyword" },
{ "line": 4, "text": "@nothing_reads_this", "kind": "unknown_annotation", "name": "nothing_reads_this" },
{ "line": 5, "text": "@single", "kind": "annotation", "name": "single", "owner": "core", "form": "keyword" }
]
}kindisannotation,text(the description: what OpenAPI and MCP publish) orunknown_annotation(written with@, read by nothing: usually a misspelt name).nameis the canonical name from the annotation reference (npgsqlrest --annotations),ownerwho reads it (core,tsclient,mcp...),formone ofkeyword,key_value,header.lineis the line in the file (for--parse-comment, in the comment).endpointsays whether this text would become an endpoint as far as the text decides it; when not,reasonandmessagesay why, with the codes of--inspect.RequireAtPrefix,CommentsModeand the SQL file source'sCommentScopeare taken from the configuration, so the answer is the one this project's server would give.
What depends on the routine itself is not in this output: whether a key = value line names a parameter, whether a for tag matches, parameter types. Those need the database, and --inspect has them.
An editor that keeps its own reader for speed can use this output as its reference: the same input, and what the real parser makes of it.
RequireAtPrefix: only a line that begins with @ is an annotation
The @ in front of an annotation has always been optional: HTTP GET and @http get are the same line. That is convenient, and it has a cost. A comment is also where the description of an endpoint is written, and a sentence can begin with a word that is an annotation:
sql
comment on function get_report() is '
HTTP GET
Login for staff only.
Note: see the wiki
';Here the second line is the login annotation and the third a response header named Note. Neither was meant. A tool that edits such comments cannot tell either.
jsonc
{
"NpgsqlRest": {
"RequireAtPrefix": true // new, default false
}
}With RequireAtPrefix on, a line is an annotation only if it begins with @, and every other line is text, whatever word it begins with:
sql
comment on function get_report() is '
@http get
@authorize admin
@timeout = 30s
@Content-Type: text/csv
Login for staff only.
Note: see the wiki
';- It applies to everything read from an endpoint comment: the built-in annotations including
@http,key = valuelines, response headers,fortags, and the annotations of plugins. - In SQL files also to the lines the source reads itself:
@returns,@result,@single,@skip,@param,@define_param. - In the comment of an HTTP Custom Type to its directives (
@timeout,@retry_delay,@cache). Its request line and its headers are HTTP syntax and take no prefix. - SQL test files are unaffected: their annotations have always needed the
@.
The default is false, and with it nothing changes: a line is read with or without the prefix. We would have liked to make the prefix mandatory in 4.0.0, and did not think of it in time; turning it on for everyone now would break every project written in the short form. So it is a choice: turn it on for a new project, or for an existing one after its comments are written with @.
Switching an existing project on is safe in one direction: a comment that is entirely in the short form has an HTTP line without @, so it creates no endpoint (and says so in a warning and in --inspect, reason unprefixed_annotations), instead of creating one without its restrictions. For a comment that is partly converted, lines without @ that begin with an annotation that restricts access (authorize, disabled, internal, login, logout, basic_auth, security_sensitive) are logged as a warning, because the endpoint exists without that restriction:
code
Function public.get_report mapped to GET /api/get-report: "authorize" is read as text, not as the annotation authorize,
because annotations need the @ prefix (RequireAtPrefix is on). Write @authorize, or reword the line if it is a sentence.Writing the @ always is the form that is read the same in both settings. For library users: NpgsqlRestOptions.RequireAtPrefix.
For library users and plugin authors
EndpointReport(static):NotExposed,GeneratedFor(endpoint),GeneratedFiles, replaced by every build of the endpoints. A source reports what it leaves out withEndpointReport.AddNotExposed(...), a generator what it wrote withEndpointReport.AddGenerated(generator, file, role, text, items), which finds each endpoint's line in the text that was written.EndpointReport.IncludeFilteredOut = trueadds the routines left out by filters (one more query per routine source;--inspectsets it).SqlFileParser.ParseandExtractParamTypeHintshave arequireAtPrefixparameter (defaultfalse).
Npgsql 11
Performance is the same as 4.0.1. Both versions were put under the same load, as JIT builds and as native AOT executables: requests per second, response times, PostgreSQL's CPU time and memory are equal within the noise of the measurement. The one difference that showed in every round is small: responses with rows need about 3% less server CPU per request. The numbers are under Performance.
Npgsql 10.0.3 → 11.0.0 in the NpgsqlRest library, and with it in the npgsqlrest client and its Docker images.
- Npgsql 11 targets
net10.0, so the library keeps both of its targets (net10.0andnet11.0). Applications on .NET 10 can take this release; they get version 11.0.0 of two small packages that Npgsql 11 depends on (Microsoft.Extensions.DependencyInjection.AbstractionsandMicrosoft.Extensions.Logging.Abstractions). The whole test suite passes on both runtimes. - The request context still travels with the routine. That uses one non-public member of Npgsql (the text-results switch of a batch, see 4.0.0). It is still there and still not public in Npgsql 11, and it works as before: the context tests and the Native AOT smoke test cover it.
- Uploads to large objects are not affected by the removal of Npgsql's large object classes: NpgsqlRest has always used the PostgreSQL functions (
lo_create,lo_put). - Runtime Async stays off. Npgsql 11 is built for .NET 10 and is not compiled with Runtime Async, so what 4.0.0 measured still holds: a request spends its waiting time inside Npgsql, and nothing is gained by compiling only NpgsqlRest that way.
Two things in Npgsql 11 that can affect a setup
Multiplexingin a connection string is now an error. Npgsql 11 removed multiplexing together with its connection string keys. A connection string that containsMultiplexing=...orWrite Coalescing Buffer Threshold Bytes=...(alsoMultiplexing=false) no longer opens: remove the key. NpgsqlRest never set these keys itself.- The pool name in Npgsql's metrics. For connection metrics (
db.client.connection.*), Npgsql 11 names a pool after theApplication Nameof its connection string when it has one, where Npgsql 10 used the connection string. Thenpgsqlrestclient sets an application name by default, so thedb.client.connection.pool.namelabel changes to that name. Dashboards or alerts that filter on the old value need the new one.
Performance against 4.0.1
Npgsql 11 lists internal work on its text and UTF-8 converters and on the reader, without numbers. To see what that means here, 4.0.1 (built from its release tag, with Npgsql 10.0.3) and 4.1.0 (Npgsql 11.0.0) were measured the way 4.0.0 was: the published builds with default settings, an HTTP/1.1 keep-alive load generator on the same machine (Apple M4 Pro, PostgreSQL 17 in a container), four rounds with the order of the builds rotating, five seconds per measurement. Values are the averages of the four rounds.
| JIT 4.0.1 | JIT 4.1.0 | AOT 4.0.1 | AOT 4.1.0 | |||
|---|---|---|---|---|---|---|
| Requests per second (32 connections) | ||||||
| Text value | 38,912 | 39,344 | +1.1% | 37,992 | 38,623 | +1.7% |
| PL/pgSQL function, five queries | 31,931 | 31,457 | -1.5% | 31,874 | 30,175 | -5.3% ¹ |
| POST, four parameters | 36,817 | 37,599 | +2.1% | 36,145 | 36,307 | +0.4% |
| 100 rows (15 KB) | 19,288 | 19,401 | +0.6% | 18,214 | 18,535 | +1.8% |
| One json value (170 KB) | 4,407 | 4,502 | +2.2% | 4,497 | 4,537 | +0.9% |
Text value, user_context | 36,552 | 36,420 | -0.4% | 36,343 | 36,403 | +0.2% |
100 rows, user_context | 19,100 | 19,133 | +0.2% | 18,054 | 18,375 | +1.8% |
| Server CPU per request, µs (8 connections) | ||||||
| Text value | 143.3 | 142.7 | -0.5% | 144.1 | 142.7 | -1.0% |
| PL/pgSQL function, five queries | 153.3 | 154.3 | +0.7% | 156.9 | 156.7 | -0.1% |
| POST, four parameters | 150.7 | 150.4 | -0.2% | 155.1 | 155.8 | +0.5% |
| 100 rows (15 KB) | 284.2 | 275.4 | -3.1% | 315.6 | 306.1 | -3.0% |
| One json value (170 KB) | 544.6 | 542.9 | -0.3% | 542.2 | 546.8 | +0.8% |
Text value, user_context | 148.2 | 149.9 | +1.2% | 152.7 | 153.7 | +0.7% |
100 rows, user_context | 285.6 | 279.2 | -2.2% | 317.1 | 308.1 | -2.9% |
| Response time, one request at a time, µs | ||||||
| Text value | 188.8 | 191.6 | +1.4% | 187.5 | 189.4 | +1.0% |
| PL/pgSQL function, five queries | 261.8 | 259.3 | -1.0% | 265.3 | 270.2 | +1.8% |
| 100 rows (15 KB) | 423.0 | 412.8 | -2.4% | 455.6 | 433.4 | -4.9% |
| One json value (170 KB) | 2,279 | 2,171 | -4.7% | 2,288 | 2,258 | -1.3% |
| Memory (resident, MB, at the end of a round) | 116 | 115 | 82 | 83 |
¹ One of the four rounds was low (28,207; the others 30,545 to 31,381, against 31,151 to 32,421). The CPU per request of the same endpoint is unchanged, so this is taken as noise.
Reading: differences under about 3% are within what the same build shows from round to round. The exception is the server CPU of responses with rows: lower in all four rounds, for JIT and AOT, with and without a request context (for example JIT 287/283/283/284 against 275/278/272/276). PostgreSQL's own CPU per request is the same in every row (within 1.4%), as expected: it receives the same statements.
The load generator, the database script and the raw rows of this comparison are in the repository (BenchmarkTests/LoadTest, BenchmarkTests/Baselines/LoadTest-4.1.0-npgsql11.tsv).
Fixes
A tab between the words of an annotation
Annotation words were separated by spaces and commas only. With a tab, @authorize<TAB>admin was one word: an annotation that nothing knew, which was dropped. The endpoint had no authorization. The same for @http<TAB>get, @timeout<TAB>30s and every other annotation. A tab now separates words like a space. (The check that decides whether a SQL file is an endpoint candidate already accepted HTTP<TAB>GET; the parser then did not.)
Also: a response header line written with the prefix, @X-Frame-Options: DENY, produced a header named @X-Frame-Options. The @ marks the line as an annotation and is not part of the name.
SQL files: quoted identifiers, escape strings and $1$2
The SQL file source splits a file into statements and collects its comments. Three things it did not know:
- Quoted identifiers. In
select 1 as "a--b"the rest of the line after--was taken for a comment, and"a;b"ended the statement at the semicolon. Nothing inside"..."is a comment or the end of a statement now. - Escape strings. In
E'it\'s'the backslash-escaped quote ended the string. InsideE'...'a backslash now escapes the next character. $1$2. Two parameters side by side were read as the opening of a dollar-quoted string tagged1, and the rest of the file became that string. A dollar-quote tag is an identifier and cannot begin with a digit.
An Excel file and a CSV file in one upload ended the server
What was wrong. With an upload endpoint for Excel that falls back to CSV:
sql
comment on function import(json) is '
upload for excel
fallback_handler = csv
...';a request that carried an Excel file and a CSV file ended the server process. The Excel handler hands the request to the CSV handler because of the CSV file. A fallback handles the whole request with the same parameters, so the CSV handler had fallback_handler = csv too, and for the Excel file it handed the request to itself, and again, until the stack overflowed. Any caller who may upload to such an endpoint could do it with one request. This is not new in 4.x.
What changed. A handler is never handed the same request twice. The CSV handler now answers for both files: the CSV file is imported and the Excel file is refused ("status": "ProbablyBinary").
Found by running the examples against this release (example 7).
Logout without a valid token in an application that only uses JWT
4.0.1 stopped a logout that carries a JWT from answering 500. One case was left: an application whose only authentication scheme is JWT, and a logout endpoint called without a token, or with an expired one. There is then no scheme that authenticated the request, the default sign-out scheme is the JWT handler again, and it cannot sign out. Such a logout now answers normally: there is no session on the server to end.
NpgsqlRest.Mcp was never published to NuGet
The MCP plugin has been part of the npgsqlrest executable and its Docker images since 3.17.0. As a library package it did not exist: its project did not produce a package, so the release had nothing to push, and an application that uses NpgsqlRest as a library could not install it. NpgsqlRest.Mcp 1.2.1 is the first version on NuGet.
Tests
3,360 tests on .NET 11 (3,341 on .NET 10), 62 of them new, green on .NET 11, on .NET 10 and with Runtime Async, with Npgsql 11; Native AOT publish without new warnings, and the AOT smoke test.
RequireAtPrefixTests: an application with the setting on: a comment in the short form creates no endpoint and is reported; prefixed comments are read as before; unprefixed lines are text whatever they begin with (annotations,key = value, headers, tags, plugin lines); the warnings for unprefixed lines that restrict access.EndpointReportTests: every reason ofnotExposed, the routines left out by schema and name filters, the tab separator, and for the TypeScript client, its hooks, HTTP files and OpenAPI the file, name and line of each endpoint (including two endpoints whose paths begin alike).CommentInspectorTestsand the command-line tests for--parse,--parse-commentand--inspect(with SQL files that are good, without an HTTP line, broken and empty).LexerAndPrefixTests: quoted identifiers, escape strings,$1$2, dollar-quoted strings, and the SQL file source's own lines under both settings.ExcelUploadTests.Test_excel_and_csv_in_one_request_with_a_fallback_answers.JwtOnlyLogoutTests: logout with no token, a token that is not valid, and a valid one, in an application whose only scheme is JWT.
NuGet Package Upgrades
| Package | Version |
|---|---|
NpgsqlRest | 4.0.1 → 4.1.0 (Npgsql 10.0.3 → 11.0.0) |
NpgsqlRest.TsClient | 1.38.1 → 1.39.0 |
NpgsqlRest.DartClient | 1.1.0 → 1.2.0 |
NpgsqlRest.OpenAPI | 1.3.0 → 1.4.0 |
NpgsqlRest.HttpFiles | 1.5.0 → 1.6.0 |
NpgsqlRest.SqlFileSource | 1.2.0 → 1.3.0 |
NpgsqlRest.CrudSource | 1.5.0 → 1.5.1 |
NpgsqlRest.Mcp | 1.2.1 (first version on NuGet) |
The generators report what they write (EndpointReport), the SQL file source reads RequireAtPrefix and has the lexer fixes, and every plugin has the tab separator.