Interface INpgsqlTypeMapper

Namespace

Npgsql.TypeMapping

Assembly

Npgsql.dll

A type mapper, managing how to read and write CLR values to PostgreSQL data types.

public interface INpgsqlTypeMapper

Remarks

The preferred way to manage type mappings is on NpgsqlDataSourceBuilder. An alternative, but discouraged, method, is to manage them globally via GlobalTypeMapper).

Properties

DefaultNameTranslator

The default name translator to convert CLR type names and member names. Defaults to NpgsqlSnakeCaseNameTranslator.

INpgsqlNameTranslator DefaultNameTranslator { get; set; }

Property Value

INpgsqlNameTranslator

Methods

AddTypeInfoResolverFactory(PgTypeInfoResolverFactory)

Adds a type info resolver factory which can add or modify support for PostgreSQL types. Typically used by plugins.

void AddTypeInfoResolverFactory(PgTypeInfoResolverFactory factory)

Parameters

factory PgTypeInfoResolverFactory

The type resolver factory to be added.

ConfigureJsonOptions(JsonSerializerOptions)

Configures the JSON serializer options used when reading and writing all System.Text.Json data.

INpgsqlTypeMapper ConfigureJsonOptions(JsonSerializerOptions serializerOptions)

Parameters

serializerOptions JsonSerializerOptions

Options to customize JSON serialization and deserialization.

Returns

INpgsqlTypeMapper

EnableDynamicJson(Type[]?, Type[]?)

Sets up dynamic System.Text.Json mappings. This allows mapping arbitrary .NET types to PostgreSQL json and jsonb types, as well as JsonNode and its derived types.

INpgsqlTypeMapper EnableDynamicJson(Type[]? jsonbClrTypes = null, Type[]? jsonClrTypes = null)

Parameters

jsonbClrTypes Type[]

A list of CLR types to map to PostgreSQL jsonb (no need to specify Jsonb).

jsonClrTypes Type[]

A list of CLR types to map to PostgreSQL json (no need to specify Json).

Returns

INpgsqlTypeMapper

Remarks

Due to the dynamic nature of these mappings, they are not compatible with NativeAOT or trimming.

EnableRecordsAsTuples()

Sets up mappings for the PostgreSQL record type as a .NET ValueTuple or Tuple.

INpgsqlTypeMapper EnableRecordsAsTuples()

Returns

INpgsqlTypeMapper

The same builder instance so that multiple calls can be chained.

EnableUnmappedTypes()

Sets up mappings allowing the use of unmapped enum, range and multirange types.

INpgsqlTypeMapper EnableUnmappedTypes()

Returns

INpgsqlTypeMapper

The same builder instance so that multiple calls can be chained.

MapComposite(Type, string?, INpgsqlNameTranslator?)

Maps a CLR type to a composite type.

INpgsqlTypeMapper MapComposite(Type clrType, string? pgName = null, INpgsqlNameTranslator? nameTranslator = null)

Parameters

clrType Type

The .NET type to be mapped.

pgName string

A PostgreSQL type name for the corresponding composite type in the database. If null, the name translator given in nameTranslator will be used.

nameTranslator INpgsqlNameTranslator

A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to DefaultNameTranslator.

Returns

INpgsqlTypeMapper

Remarks

Maps CLR fields and properties by string to PostgreSQL names. The translation strategy can be controlled by the nameTranslator parameter, which defaults to DefaultNameTranslator. If there is a discrepancy between the .NET type and database type while a composite is read or written, an exception will be raised.

MapComposite<T>(string?, INpgsqlNameTranslator?)

Maps a CLR type to a PostgreSQL composite type.

INpgsqlTypeMapper MapComposite<T>(string? pgName = null, INpgsqlNameTranslator? nameTranslator = null)

Parameters

pgName string

A PostgreSQL type name for the corresponding composite type in the database. If null, the name translator given in nameTranslator will be used.

nameTranslator INpgsqlNameTranslator

A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to DefaultNameTranslator.

Returns

INpgsqlTypeMapper

Type Parameters

T

The .NET type to be mapped

Remarks

CLR fields and properties by string to PostgreSQL names. The translation strategy can be controlled by the nameTranslator parameter, which defaults to NpgsqlSnakeCaseNameTranslator. You can also use the PgNameAttribute on your members to manually specify a PostgreSQL name. If there is a discrepancy between the .NET type and database type while a composite is read or written, an exception will be raised.

MapEnum(Type, string?, INpgsqlNameTranslator?)

Maps a CLR enum to a PostgreSQL enum type.

INpgsqlTypeMapper MapEnum(Type clrType, string? pgName = null, INpgsqlNameTranslator? nameTranslator = null)

Parameters

clrType Type

The .NET enum type to be mapped

pgName string

A PostgreSQL type name for the corresponding enum type in the database. If null, the name translator given in nameTranslator will be used.

nameTranslator INpgsqlNameTranslator

A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to DefaultNameTranslator.

Returns

INpgsqlTypeMapper

Remarks

CLR enum labels are mapped by name to PostgreSQL enum labels. The translation strategy can be controlled by the nameTranslator parameter, which defaults to NpgsqlSnakeCaseNameTranslator. You can also use the PgNameAttribute on your enum fields to manually specify a PostgreSQL enum label. If there is a discrepancy between the .NET and database labels while an enum is read or written, an exception will be raised.

MapEnum<TEnum>(string?, INpgsqlNameTranslator?)

Maps a CLR enum to a PostgreSQL enum type.

INpgsqlTypeMapper MapEnum<TEnum>(string? pgName = null, INpgsqlNameTranslator? nameTranslator = null) where TEnum : struct, Enum

Parameters

pgName string

A PostgreSQL type name for the corresponding enum type in the database. If null, the name translator given in nameTranslator will be used.

nameTranslator INpgsqlNameTranslator

A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to DefaultNameTranslator.

Returns

INpgsqlTypeMapper

Type Parameters

TEnum

The .NET enum type to be mapped

Remarks

CLR enum labels are mapped by name to PostgreSQL enum labels. The translation strategy can be controlled by the nameTranslator parameter, which defaults to NpgsqlSnakeCaseNameTranslator. You can also use the PgNameAttribute on your enum fields to manually specify a PostgreSQL enum label. If there is a discrepancy between the .NET and database labels while an enum is read or written, an exception will be raised.

Reset()

Resets all mapping changes performed on this type mapper and reverts it to its original, starting state.

void Reset()

UnmapComposite(Type, string?, INpgsqlNameTranslator?)

Removes an existing composite mapping.

bool UnmapComposite(Type clrType, string? pgName = null, INpgsqlNameTranslator? nameTranslator = null)

Parameters

clrType Type

The .NET type to be unmapped.

pgName string

A PostgreSQL type name for the corresponding composite type in the database. If null, the name translator given in nameTranslator will be used.

nameTranslator INpgsqlNameTranslator

A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to DefaultNameTranslator.

Returns

bool

UnmapComposite<T>(string?, INpgsqlNameTranslator?)

Removes an existing composite mapping.

bool UnmapComposite<T>(string? pgName = null, INpgsqlNameTranslator? nameTranslator = null)

Parameters

pgName string

A PostgreSQL type name for the corresponding composite type in the database. If null, the name translator given in nameTranslator will be used.

nameTranslator INpgsqlNameTranslator

A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to NpgsqlSnakeCaseNameTranslator

Returns

bool

Type Parameters

T

UnmapEnum(Type, string?, INpgsqlNameTranslator?)

Removes an existing enum mapping.

bool UnmapEnum(Type clrType, string? pgName = null, INpgsqlNameTranslator? nameTranslator = null)

Parameters

clrType Type

The .NET enum type to be mapped

pgName string

A PostgreSQL type name for the corresponding enum type in the database. If null, the name translator given in nameTranslator will be used.

nameTranslator INpgsqlNameTranslator

A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to DefaultNameTranslator.

Returns

bool

UnmapEnum<TEnum>(string?, INpgsqlNameTranslator?)

Removes an existing enum mapping.

bool UnmapEnum<TEnum>(string? pgName = null, INpgsqlNameTranslator? nameTranslator = null) where TEnum : struct, Enum

Parameters

pgName string

A PostgreSQL type name for the corresponding enum type in the database. If null, the name translator given in nameTranslator will be used.

nameTranslator INpgsqlNameTranslator

A component which will be used to translate CLR names (e.g. SomeClass) into database names (e.g. some_class). Defaults to DefaultNameTranslator.

Returns

bool

Type Parameters

TEnum