PgGucRegistry

Namespace: Ankus

Assembly: Ankus.Runtime.dll

Defines PostgreSQL configuration parameters whose names and metadata are computed at run time, as pgrx’s GucRegistry does.

public static class PgGucRegistry

Call these methods from a [PgModuleLoadAttribute](/api/ankus.pgmoduleloadattribute/) method, as a pgrx extension calls GucRegistry from _PG_init. PostgreSQL owns each definition for the life of the process: parsing, permissions, source priority, SET, RESET and placeholder adoption behave as for attribute-declared settings.

Defining a parameter again with identical metadata returns another reader for it, so a retried module load is harmless. A different definition with the same name, or a name declared by a [PgGucAttribute](/api/ankus.pggucattribute/), is rejected. [Postmaster](/api/ankus.pgguccontext/#member-34f544a17b8dfb73) parameters can be defined only while shared_preload_libraries is processed. Names follow PostgreSQL's custom setting rules, as the attributes require.

Prefer the [PgGucAttribute](/api/ankus.pggucattribute/) family for names known at compile time. Attributes add compile-time validation and typed C# enum settings. Both forms accept check, assign and show hooks; pass [PgGucHooks<T>](/api/ankus.pgguchooks-1/) here, as pgrx's define_*_guc_with_hooks functions take hook functions.

Inheritance: object

Methods

DefineBool(string, bool, string, string?, PgGucContext, PgGucOptions, PgGucHooks<bool>?)

Defines a Boolean configuration parameter.

public static PgGucSetting<bool> DefineBool(string name, bool defaultValue, string shortDescription, string? longDescription = null, PgGucContext context = PgGucContext.UserSet, PgGucOptions flags = PgGucOptions.None, PgGucHooks<bool>? hooks = null)

Parameters:

name — string

The qualified name, including the extension’s prefix.

defaultValue — bool

The value before any configuration source sets one.

shortDescription — string

The short description shown in PostgreSQL’s configuration metadata.

longDescription — string

An optional long description.

context — PgGucContext

When and by whom the parameter can be changed.

flags — PgGucOptions

PostgreSQL configuration flags.

hooks — PgGucHooks<bool>

Optional check, assign and show hooks.

Returns: PgGucSetting<bool>

A reader for the parameter’s current value.

Exceptions:

ArgumentException: Text is blank or contains a zero character, or an option is undefined.
PgException: PostgreSQL rejected the definition.

DefineEnum(string, int, string, IReadOnlyList<PgGucEnumOption>, string?, PgGucContext, PgGucOptions, PgGucHooks<int>?)

Defines an enumerated configuration parameter whose labels are supplied at run time.

public static PgGucSetting<int> DefineEnum(string name, int defaultValue, string shortDescription, IReadOnlyList<PgGucEnumOption> options, string? longDescription = null, PgGucContext context = PgGucContext.UserSet, PgGucOptions flags = PgGucOptions.None, PgGucHooks<int>? hooks = null)

Parameters:

name — string

The qualified name, including the extension’s prefix.

defaultValue — int

The ordinal used before any configuration source sets one.

shortDescription — string

The short description shown in PostgreSQL’s configuration metadata.

options — IReadOnlyList<PgGucEnumOption>

The accepted labels in display order.

longDescription — string

An optional long description.

context — PgGucContext

When and by whom the parameter can be changed.

flags — PgGucOptions

PostgreSQL configuration flags.

hooks — PgGucHooks<int>

Optional check, assign and show hooks; their values are label ordinals.

Returns: PgGucSetting<int>

A reader for the current ordinal.

Exceptions:

ArgumentException: Text is blank or contains a zero character, an option is undefined, or no label is supplied.
ArgumentOutOfRangeException: No label has the default ordinal.
PgException: PostgreSQL rejected the definition.

Use PgGucEnumAttribute for a typed C# enum known at compile time.

DefineInt(string, int, string, int, int, string?, PgGucContext, PgGucOptions, PgGucUnit, PgGucHooks<int>?)

Defines an integer configuration parameter.

public static PgGucSetting<int> DefineInt(string name, int defaultValue, string shortDescription, int minimum = -2147483648, int maximum = 2147483647, string? longDescription = null, PgGucContext context = PgGucContext.UserSet, PgGucOptions flags = PgGucOptions.None, PgGucUnit unit = PgGucUnit.None, PgGucHooks<int>? hooks = null)

Parameters:

name — string

The qualified name, including the extension’s prefix.

defaultValue — int

The value before any configuration source sets one.

shortDescription — string

The short description shown in PostgreSQL’s configuration metadata.

minimum — int

The inclusive minimum.

maximum — int

The inclusive maximum.

longDescription — string

An optional long description.

context — PgGucContext

When and by whom the parameter can be changed.

flags — PgGucOptions

PostgreSQL configuration flags.

unit — PgGucUnit

The unit PostgreSQL accepts and displays.

hooks — PgGucHooks<int>

Optional check, assign and show hooks.

Returns: PgGucSetting<int>

A reader for the parameter’s current value.

Exceptions:

ArgumentException: Text is blank or contains a zero character, or an option is undefined.
ArgumentOutOfRangeException: The range is empty or excludes the default.
PgException: PostgreSQL rejected the definition.

DefineReal(string, double, string, double, double, string?, PgGucContext, PgGucOptions, PgGucUnit, PgGucHooks<double>?)

Defines a floating-point configuration parameter.

public static PgGucSetting<double> DefineReal(string name, double defaultValue, string shortDescription, double minimum = -1.7976931348623157E+308, double maximum = 1.7976931348623157E+308, string? longDescription = null, PgGucContext context = PgGucContext.UserSet, PgGucOptions flags = PgGucOptions.None, PgGucUnit unit = PgGucUnit.None, PgGucHooks<double>? hooks = null)

Parameters:

name — string

The qualified name, including the extension’s prefix.

defaultValue — double

The value before any configuration source sets one.

shortDescription — string

The short description shown in PostgreSQL’s configuration metadata.

minimum — double

The inclusive minimum.

maximum — double

The inclusive maximum.

longDescription — string

An optional long description.

context — PgGucContext

When and by whom the parameter can be changed.

flags — PgGucOptions

PostgreSQL configuration flags.

unit — PgGucUnit

The unit PostgreSQL accepts and displays.

hooks — PgGucHooks<double>

Optional check, assign and show hooks.

Returns: PgGucSetting<double>

A reader for the parameter’s current value.

Exceptions:

ArgumentException: Text is blank or contains a zero character, or an option is undefined.
ArgumentOutOfRangeException: A bound or the default is not a number, the range is empty, or it excludes the default.
PgException: PostgreSQL rejected the definition.

DefineString(string, string?, string, string?, PgGucContext, PgGucOptions, PgGucHooks<string?>?)

Defines a string configuration parameter.

public static PgGucSetting<string?> DefineString(string name, string? defaultValue, string shortDescription, string? longDescription = null, PgGucContext context = PgGucContext.UserSet, PgGucOptions flags = PgGucOptions.None, PgGucHooks<string?>? hooks = null)

Parameters:

name — string

The qualified name, including the extension’s prefix.

defaultValue — string

The value before any configuration source sets one, or null for an absent value.

shortDescription — string

The short description shown in PostgreSQL’s configuration metadata.

longDescription — string

An optional long description.

context — PgGucContext

When and by whom the parameter can be changed.

flags — PgGucOptions

PostgreSQL configuration flags.

hooks — PgGucHooks<string>

Optional check, assign and show hooks.

Returns: PgGucSetting<string>

A reader for the parameter’s current value.

Exceptions:

ArgumentException: Text is blank or contains a zero character, or an option is undefined.
PgException: PostgreSQL rejected the definition.