NpgsqlRest

Appearance

Comments

CONNECTION ​

Also known as

connection_name (with or without @ prefix)

Specify a named database connection for the endpoint.

Syntax ​

code
@connection <connection-name>
@connection_name <connection-name>

The key = value form works too:

code
@connection = <connection-name>
@connection_name = <connection-name>

Examples ​

Use Named Connection ​

sql
sql
comment on function get_analytics() is
'HTTP GET
@connection analytics_db';

Reporting Database ​

sql
sql
comment on function generate_report() is
'HTTP GET
@connection_name reporting';

Read Replica ​

sql
sql
comment on function read_heavy_query() is
'HTTP GET
@connection read_replica';

Behavior ​

  • References a connection string defined in ConnectionStrings configuration (matched case-insensitively). The main connection's own name is valid too (3.21.0+).
  • Allows different endpoints to use different databases
  • Requires UseMultipleConnections: true in NpgsqlRest options — or RoutineOptions.ReadMetadataFromConnections, which enables multiple connections implicitly (3.21.0+)
  • The annotation changes where the endpoint executes, not where it is discovered: the routine must exist (with this comment) on the metadata connection, and the target database is assumed to have the same routine — right for replicas and shards. When different databases host different routines, use per-connection routine discovery instead; the annotation then overrides the source's connection.
  • An unknown connection name logs a startup warning and fails the request with a 500 at run time. Opt into startup verification of routed endpoints with RoutineOptions.VerifyRoutedEndpoints (3.21.0+).
  • See Connection Settings configuration

See Also ​

Comments