npgsqlrest - npm Package Versions

Version 2.10.0 (2024-08-06)

Full Changelog

New Routine Endpoint Options With Annotations

These two options will only apply when raw is on. Also, comment annotation values will accept standard escape sequences such as \n, \r or \t, etc.

These are:

• RoutineEndpoint option public string? RawValueSeparator { get; set; } = null; that maps to new comment annotation separator

Defines a standard separator between raw values.

• RoutineEndpoint option public string? RawNewLineSeparator { get; set; } = null; that maps to new comment annotation newline

Defines a standard separator between raw value columns.

Dynamic Custom Header Values

In this version, when you define custom headers, either trough:

• CustomRequestHeaders option for all requests.
• On EndpointsCreated option event as ResponseHeaders on a specific endpoint.
• Or, as comment annotation on a PostgreSQL routine.

Now, you can set header value from a routine parameter. For, example, if the header value has a name in curly brackets like this Content-Type: {_type}, then a Content-Type header will have to value of the _type routine parameter (if the parameter exists).

See CSV example:

CSV Example:

• Routine:

create function header_template_response1(_type text, _file text) 
returns table(n numeric, d timestamp, b boolean, t text)
language sql
as 
$$
select sub.* 
from (
values 
    (123, '2024-01-01'::timestamp, true, 'some text'),
    (456, '2024-12-31'::timestamp, false, 'another text')
)
sub (n, d, b, t)
$$;

comment on function header_template_response1(text, text) is '
raw
separator ,
newline \n
Content-Type: {_type}
Content-Disposition: attachment; filename={_file}
';

Request on this enpoint with parameters:

• _type = 'text/csv'
• _file = 'test.csv'

Will produce a download response to a 'test.csv' file with content type 'test.csv'. Raw values separator will be , character and row values separator will be new line.

---

Version 2.9.0 (2024-08-02)

Full Changelog

Added raw endpoint options and comment annotation:

Sets response to a "raw" mode. HTTP response is written exactly as it is received from PostgreSQL (raw mode).

This is useful for creating CSV responses automatically. For example:

create function raw_csv_response1() 
returns setof text
language sql
as 
$$
select trim(both '()' FROM sub::text) || E'\n' from (
values 
    (123, '2024-01-01'::timestamp, true, 'some text'),
    (456, '2024-12-31'::timestamp, false, 'another text')
)
sub (n, d, b, t)
$$;
comment on function raw_csv_response1() is '
raw
Content-Type: text/csv
';

Produces the following response:

HTTP/1.1 200 OK                                                  
Connection: close
Content-Type: text/csv
Date: Tue, 08 Aug 2024 14:25:26 GMT
Server: Kestrel
Transfer-Encoding: chunked

123,"2024-01-01 00:00:00",t,"some text"
456,"2024-12-31 00:00:00",f,"another text"

---

Version 2.8.0 (2024-05-02)

Full Changelog

• New Option: Dictionary<string, StringValues> CustomRequestHeaders

Custom request headers dictionary that will be added to NpgsqlRest requests.

Note: these values are added to the request headers dictionary before they are sent as a context or parameter to the PostgreSQL routine and as such not visible to the browser debugger.

Version 2.7.0 (2024-04-17)

Full Changelog

New callback option: Action<NpgsqlConnection, Routine, RoutineEndpoint, HttpContext>? BeforeConnectionOpen.

This is used to set the application name parameter (for example) without having to use the service provider. It executes before the new connection is open for the request. For example:

app.UseNpgsqlRest(new()
{
    ConnectionString = connectionString,
    BeforeConnectionOpen = (NpgsqlConnection connection, Routine routine, RoutineEndpoint endpoint, HttpContext context) =>
    {
        var username = context.User.Identity?.Name;
        connection.ConnectionString = new NpgsqlConnectionStringBuilder(connectionString)
        {
            ApplicationName = string.Concat(
                    "{\"app\":\"",
                    builder.Environment.ApplicationName,
                    username is null ? "\",\"user\":null}" : string.Concat("\",\"user\":\"", username, "\"}"))
        }.ConnectionString;
    }
}

---

Version 2.6.0 (2024-04-16)

Full Changelog

Improved error handling. Two new options are available:

ReturnNpgsqlExceptionMessage:

• Set to true to return message property on exception from the NpgsqlException object on response body. The default is true.

• Set to false to return empty body on exception.

PostgreSqlErrorCodeToHttpStatusCodeMapping

Dictionary setting that maps the PostgreSQL Error Codes (see the errcodes-appendix to HTTP Status Codes.

Default is { "57014", 205 } which maps PostgreSQL query_canceled error to HTTP 205 Reset Content. If the mapping doesn't exist, the standard HTTP 500 Internal Server Error is returned.

---

Version 2.5.0 (2024-04-15)

Full Changelog

• New endpoint parameter option BufferRows.

Now it's possible to set the number of buffered rows that are returned before they are written to HTTP response on an endpoint level.

It is also possible to set this endpoint parameter as a comment annotation:

comment on function my_streaming_function() is 'HTTP GET
bufferrows 1';

See the full comment annotation list here.

Setting this parameter to 1 is useful in the HTTP streaming scenarios.

• New TsClient plugin options and fixes

/// <summary>
/// Module name to import "baseUrl" constant, instead of defining it in a module.
/// </summary>
public string? ImportBaseUrlFrom { get; set; } = importBaseUrlFrom;

/// <summary>
/// Module name to import "pasreQuery" function, instead of defining it in a module.
/// </summary>
public string? ImportParseQueryFrom { get; set; } = importParseQueryFrom;

---

Version 2.4.0 (2024-04-08)

Full Changelog

• Remove AotTemplate subproject directory. AOT Template is now NpgsqlRestTestWebApi with full configuration for the entire application.
• The auth handler doesn't complete the response if it doesn't have to on login and logout.
• Changed wording Schema to Scheme everywhere because that appears to be standard with the auth (unlike with databases).
• Changed IRoutineSource interface to:
  • Have CommentsMode mode fully exposed with getters and setters.
  • Have Query property exposed.
  • Every parameter for the query exposed (SchemaSimilarTo, SchemaNotSimilarTo, etc).
• Replaced interfaces with concrete implementation for better performance.
• Fixed bug with service scope disposal when using ConnectionFromServiceProvider.
• Obfuscated auth parameters in logs (with ObfuscateAuthParameterLogValues option).
• Implemented SerializeAuthEndpointsResponse to serialize the auth (log in or log out) when it's possible.
• Fixed ParameterValidationValues to use NpgsqlRestParameter instead of NpgsqlParameter to expose the actual parameter name.
• Added IsAuth read-only property to the endpoint.
• Fixed automatic port detection in the code-gen plugins.
• Added CommentHeaderIncludeComments to the TsClient plugin.

---

Version 2.3.0 (2024-04-04)

Full Changelog

• Login Endpoints can return text messages.
• A new option that supports this feature: AuthenticationOptions.MessageColumnName.
• Login endpoints always return text.
• Interface IRoutineSource exposes string Query { get; set; }. If the value doesn't contain blanks it is interpreted as the function name.
• TsClient plugin new version (1.2.0):
  • New TsClweint option BySchema. If true, create a file by schema. The default is false.
  • Fix handling login endpoints.
  • Bugfixes.

---

Version 2.2.0 (2024-04-02)

Full Changelog

• Login endpoints
• Logout endpoints
• Small name refactoring (ReturnRecordNames -> ColumnNames)

To enable authentication, the authentication service first needs to be enabled in the application:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication().AddCookie();

The login-enabled endpoints must return a named record.

The program will result in the ArgumentException exception if the login-enabled routine is either of these:

• void
• returns simple value
• returns set of record unnamed records

The login operation will be interpreted as an unsuccessful login attempt and return the status code 401 Unauthorized without creating a user identity if either:

• The routine returns an empty record.
• The returned record includes a status column, and the value of the status column name is:
  • False for boolean types.
  • Not 200 for numeric types.

The login operation will be interpreted as a successful login attempt and return the status code 200 OK with creating a new user identity if either:

• The routine returns a record without status status column.
• The returned record includes a status column, and the value of the status column name is:
  • True for boolean types.
  • 200 for numeric types.

To authorize a different authorization scheme, return a schema column name with the value of that schema.

Any other records will be set as new claims for the created user identity on successful login, where:

• The column name is claim type. This type will by default try to match the constant name in the ClaimTypes class to retrieve the value. Use the [UseActiveDirectoryFederationServicesClaimTypes Option][https://vb-consulting.github.io/npgsqlrest/options/#authenticationoptionsuseactivedirectoryfederationservicesclaimtypes] to control this behavior.
• The record value (as string) is the claim value.

---