Skip to content

CodecRegistry

[Source]

Maps PostgreSQL type OIDs to codecs. Immutable — adding a codec, enum, composite, or array type produces a new registry.

The default constructor creates a registry with all built-in text and binary codecs. Use with_codec to register custom codecs, with_enum_type to register user-defined enum types, with_composite_type to register user-defined composite types, and with_array_type to register custom array type mappings:

let registry = CodecRegistry
  .with_codec(600, PointBinaryCodec)?       // custom point type
  .with_enum_type(12345)?                   // mood enum
  .with_composite_type(16400,               // address composite
    recover val
      [as (String, U32): ("street", 25); ("city", 25); ("zip_code", 23)]
    end)?
  .with_array_type(12350, 12345)?           // mood[]
  .with_array_type(16401, 16400)?           // address[]
let session = Session(server_info, db_info, notify where registry = registry)

class val CodecRegistry

Constructors

create

[Source]

Registry with all built-in text and binary codecs.

new val create()
: CodecRegistry val^

Returns

Public Functions

with_codec

[Source]

Returns a new registry with the given codec registered for the given OID. Supports chaining: CodecRegistry.with_codec(600, A)?.with_codec(790, B)?.

Errors if the OID is already registered (built-in or custom) or collides with a built-in or custom array OID. Use distinct OIDs for each codec.

fun val with_codec(
  oid: U32 val,
  codec: Codec val)
: CodecRegistry val ?

Parameters

Returns

with_enum_type

[Source]

Returns a new registry with text-passthrough codecs registered for the given enum OID in both text and binary formats. PostgreSQL enum types use raw UTF-8 labels on the wire in both formats, so the driver decodes them as String. Only use this for enum type OIDs — other dynamically-assigned types (composites, ranges) have different binary wire formats and would produce garbage String values.

Supports chaining: CodecRegistry.with_enum_type(12345)?.with_enum_type(12346)?.

Composes with with_array_type for enum arrays: CodecRegistry.with_enum_type(12345)?.with_array_type(12350, 12345)?.

Errors if the OID is already registered (built-in or custom) or collides with a built-in or custom array OID — same validation semantics as with_codec.

Because this registers the OID in both codec maps atomically, a subsequent with_codec(oid, ...) will error for either format. This is stricter than two separate with_codec calls (which allow independent text/binary registration for the same OID).

fun val with_enum_type(
  oid: U32 val)
: CodecRegistry val ?

Parameters

Returns

with_composite_type

[Source]

Returns a new registry with the given composite type registered. field_descriptors are (name, oid) pairs in declaration order.

Supports chaining: CodecRegistry.with_composite_type(16400, fields)?.with_array_type(16401, 16400)?.

Errors if the OID is already registered (built-in, custom codec, enum, or composite), collides with a built-in or custom array OID, or has empty field descriptors. Self-referential field OIDs (the composite's own OID in its field list) are also rejected.

Does NOT auto-register the corresponding array type — call with_array_type separately if needed.

fun val with_composite_type(
  oid: U32 val,
  field_descriptors: Array[(String val , U32 val)] val)
: CodecRegistry val ?

Parameters

Returns

with_array_type

[Source]

Returns a new registry with a custom array type mapping. This enables decode of arrays whose element type is a custom codec-registered OID. Supports chaining with with_codec: CodecRegistry.with_codec(600, PointCodec)?.with_array_type(1017, 600)?.

Errors if: - element_oid is itself an array OID (built-in or custom), which would cause unbounded recursion during decode - array_oid collides with a registered scalar or built-in array OID - array_oid is already registered as a custom array OID - array_oid is already registered as a custom element OID - array_oid == element_oid

fun val with_array_type(
  array_oid: U32 val,
  element_oid: U32 val)
: CodecRegistry val ?

Parameters

  • array_oid: U32 val
  • element_oid: U32 val

Returns

array_oid_for

[Source]

Return the array OID for a given element OID. Checks built-in mappings first, then custom mappings. Returns 0 if no mapping exists.

fun box array_oid_for(
  element_oid: U32 val)
: U32 val

Parameters

  • element_oid: U32 val

Returns

decode

[Source]

Decode result column data using the registered codec. Array and composite OIDs are intercepted before falling through to per-OID codec lookup.

Format 0 uses the text codec, format 1 uses the binary codec.

If no codec is registered for the OID, returns a fallback value: String.from_array(data) for text format, RawBytes(data) for binary.

If a codec IS registered but its decode() errors, the error propagates to the caller. This surfaces malformed data from the server (built-in codecs) and broken custom codecs instead of silently returning fallback values.

For arrays and composites, structural parsing errors (malformed wire format) fall back, but element/field codec errors propagate.

fun box decode(
  oid: U32 val,
  format: U16 val,
  data: Array[U8 val] val)
: FieldData val ?

Parameters

Returns

has_binary_codec

[Source]

Whether a binary codec is registered for this OID. Returns true for known array OIDs (built-in and custom) and composite OIDs in addition to scalar codecs.

fun box has_binary_codec(
  oid: U32 val)
: Bool val

Parameters

Returns