Enum Type Support

[SeanTAllen]

Enum type support for user-defined PostgreSQL enums. Item #24 from the feature roadmap.

Problem

Users with PostgreSQL enum columns get RawBytes instead of String when using PreparedQuery (binary format). The internal text-passthrough codec handles enums correctly, but it's package-private so users can't reuse it. Today they'd have to write a duplicate codec for each enum type.

With SimpleQuery (text format), enums already decode as String via the unknown-OID fallback -- no registration needed.

Wire Protocol Facts

• Enum type OIDs are dynamically assigned by the PostgreSQL catalog (not known at compile time)
• Both text and binary wire formats send the enum label as raw UTF-8 bytes (PostgreSQL's enum_send() delegates to stringTypeSend())
• A text-passthrough codec works for enum decode in both formats

Design

Add with_enum_type(oid: U32): CodecRegistry ? to CodecRegistry. Internally registers text-passthrough codecs for both text and binary formats in one call. Returns a new CodecRegistry. Errors if the OID is already registered or collides with a known array OID -- same validation semantics as with_codec.

What changes

• One new public method: CodecRegistry.with_enum_type(oid)
• One new private constructor: CodecRegistry._with_enum_type(base, oid)
• Validation checks both text and binary codec maps (atomic dual-format registration)

What doesn't change

• FieldDataTypes (no new union members)
• _ParamEncoder (no new match arms)
• _FrontendMessage.bind() (no new encoding paths)
• Codec interface
• FieldData interface
• Session constructor

Why this shape

with_array_type set the precedent: when the driver knows the codec strategy for a class of PostgreSQL types, it provides a semantic method rather than exposing internal codecs. Enums are exactly this case -- the driver knows that enums are always text-passthrough. The method:

• Names the intent (with_enum_type) rather than the mechanism (with_codec(oid, TextPassthroughBinaryCodec))
• Registers both text and binary codecs atomically (a single with_codec call only handles one format)
• Hides internal codec identity (free to change implementation without breaking callers)
• Composes with with_array_type for enum arrays

Parameters

No parameter-side changes. String parameters with OID 0 work when PostgreSQL can infer the type from context. SQL casts ($1::mood) handle ambiguous contexts. This is the standard approach used by most PostgreSQL drivers.

Alternatives considered

• Make _TextPassthroughBinaryCodec public: Locks internal codec identity into public API. Requires two with_codec calls for both formats. Inconsistent with with_array_type precedent.
• Add PgEnum to FieldDataTypes: Disproportionate cost (expanding a closed union) for a narrow edge case with a SQL-level workaround.
• Do nothing: Users get RawBytes and must write duplicate codecs. The fix is too small to skip.

Footgun: dual-format registration

After with_enum_type(X), calling with_codec(X, ...) errors for either format because the OID is registered in both codec maps. This is stricter than two separate with_codec calls (which allow independent text/binary registration for the same OID). The asymmetry is intentional -- enum registration is atomic -- and will be documented in the method's docstring.

Usage

Register enum OIDs and query

// OID discovered via: SELECT oid FROM pg_type WHERE typname = 'mood'
let registry = CodecRegistry.with_enum_type(12345)?
let session = Session(server_info, db_info, notify where registry = registry)

// Multiple enums
let registry = CodecRegistry
  .with_enum_type(12345)?   // mood
  .with_enum_type(12346)?   // color

// Enum arrays compose with existing API
let registry = CodecRegistry
  .with_enum_type(12345)?
  .with_array_type(12350, 12345)?

Reading enum results

Enum values arrive as String in query results:

be pg_query_result(session: Session, result: Result) =>
  match result
  | let rs: ResultSet =>
    for row in rs.rows().values() do
      try
        let name = row("name")?.value
        let mood = row("mood")?.value  // String: "happy", "sad", etc.
        match mood
        | let s: String => _env.out.print(name.string() + " is " + s)
        end
      end
    end
  end

Domain modeling with union types

The driver gives you String. You model your domain however you want:

// Your domain types
primitive Happy
primitive Sad
primitive Neutral
type Mood is (Happy | Sad | Neutral)

// Convert at the application boundary
primitive MoodParser
  fun apply(value: String): Mood ? =>
    match value
    | "happy" => Happy
    | "sad" => Sad
    | "neutral" => Neutral
    else error
    end

// In your ResultReceiver
be pg_query_result(session: Session, result: Result) =>
  match result
  | let rs: ResultSet =>
    for row in rs.rows().values() do
      try
        let mood = MoodParser(row("mood")?.value.string())?
        match mood
        | Happy => _env.out.print("they're happy!")
        | Sad => _env.out.print("they're sad")
        | Neutral => _env.out.print("meh")
        end
      end
    end
  end

For users who want the driver itself to decode directly into domain types, the existing with_codec API supports that -- write a custom codec whose decode returns the domain primitives instead of String.

Passing enum parameters

// PostgreSQL infers type from column context
session.execute(PreparedQuery(
  "INSERT INTO people (name, mood) VALUES ($1, $2)",
  recover val [as FieldDataTypes: "Alice"; "happy"] end), this)

// SQL cast for ambiguous contexts
session.execute(PreparedQuery(
  "SELECT * FROM people WHERE mood = $1::mood",
  recover val [as FieldDataTypes: "happy"] end), this)

[SeanTAllen]

Implementation Plan

Classification

User-facing feature (added). Requires release notes, changelog label (changelog - added).

Relevant Principles

• It is easier to give than take away — minimal API surface (one method)
• Evaluate copied patterns — follows with_array_type precedent (semantic method for known codec strategy)
• Document public API elements — docstring on with_enum_type
• Fix what your change makes stale — package docstring, CLAUDE.md (both Codec Architecture and Public API Types sections), examples README
• Counterfactual testing — break each assertion to verify it fires

Steps

1. Add with_enum_type to CodecRegistry

File: postgres/codec_registry.pony

Add with_enum_type(oid: U32): CodecRegistry ? method after with_codec. Validation checks:

• _ArrayOidMap.is_array_oid(oid) — reject built-in array OIDs
• _custom_array_element_oids.contains(oid) — reject custom array OIDs
• _text_codecs.contains(oid) — reject if text codec already registered
• _binary_codecs.contains(oid) — reject if binary codec already registered

This is stricter than with_codec (which checks only one map per codec format). Document the asymmetry in the docstring.

Add _with_enum_type(base: CodecRegistry, oid: U32) private constructor that:

• Copies _custom_array_element_oids from base (preserves existing array mappings)
• Copies _text_codecs from base and inserts _TextPassthroughTextCodec for the OID
• Copies _binary_codecs from base and inserts _TextPassthroughBinaryCodec for the OID

Update the class docstring to mention with_enum_type alongside with_codec and with_array_type.

2. Add unit tests

File: postgres/_test_codecs.pony

All test classes use class \nodoc\ iso _TestFoo is UnitTest.

Tests follow the same patterns as _TestCodecRegistryWithCodec*:

• _TestCodecRegistryWithEnumTypeBinaryDecode — register enum OID, decode binary data, assert String result
• _TestCodecRegistryWithEnumTypeTextDecode — register enum OID, decode text data, assert String result
• _TestCodecRegistryWithEnumTypeHasBinaryCodec — has_binary_codec returns true for registered enum OID
• _TestCodecRegistryWithEnumTypeRejectsBuiltinOverride — OID 16 (bool) rejected
• _TestCodecRegistryWithEnumTypeRejectsDuplicate — same OID twice rejected
• _TestCodecRegistryWithEnumTypeRejectsArrayOid — built-in array OID rejected; custom array OID rejected
• _TestCodecRegistryWithEnumTypeChaining — register two enum OIDs, both work
• _TestCodecRegistryWithEnumTypePreservesBuiltins — built-in codecs still work after adding enum type
• _TestCodecRegistryWithEnumTypeBlocksSubsequentWithCodec — after with_enum_type(X), with_codec(X, ...) errors for both text and binary codecs
• _TestCodecRegistryWithEnumTypeComposesWithArrayType — with_enum_type(X)?.with_array_type(Y, X)? works, array of enum values decodes correctly

Register all in postgres/_test.pony.

Build and run: make unit-tests ssl=3.0.x for unit tests, make test-one t=CodecRegistry/WithEnumType ssl=3.0.x for just these tests.

3. Add integration test

File: postgres/_test_codecs.pony

This test requires two sessions because CodecRegistry is immutable and bound at Session construction. The first session (default registry) handles DDL and OID discovery; the second session (enum-aware registry) tests the actual decode.

Test actor workflow:

1. Session 1 (default CodecRegistry): SimpleQuery to CREATE TYPE test_enum_mood AS ENUM ('happy', 'sad', 'neutral')
2. Session 1: SimpleQuery to SELECT oid FROM pg_type WHERE typname = 'test_enum_mood' — parse the OID string from the ResultSet field value to U32
3. Create session 2 with CodecRegistry.with_enum_type(discovered_oid)?
4. Session 2: PreparedQuery to SELECT 'happy'::test_enum_mood AS mood — assert result field value is String "happy" (not RawBytes)
5. Session 1: SimpleQuery to DROP TYPE test_enum_mood
6. Close both sessions

Both sessions must be disposed via h.dispose_when_done().

Register in postgres/_test.pony. Use class \nodoc\ iso.

Build and run: make integration-tests ssl=3.0.x (requires postgres containers via make start-pg-containers).

4. Add enum-type example

Directory: examples/enum-type/

File: examples/enum-type/enum-type-example.pony

Real-world example demonstrating the two-session pattern:

1. Session 1: Creates a mood enum type, discovers its OID via SELECT oid FROM pg_type WHERE typname = 'mood'
2. Session 2 (with CodecRegistry.with_enum_type(oid)?): Creates a table with an enum column, inserts rows, queries them with PreparedQuery
3. Shows domain modeling: converts String result to a Mood union type (Happy | Sad | Neutral) via a MoodParser primitive
4. Cleans up (DROP TABLE, DROP TYPE)

Follow existing example structure — use relative use "../../postgres" paths.

5. Update examples/README.md

Add entry for enum-type example following the existing format.

6. Update package docstring

File: postgres/postgres.pony

Add a section between "Custom Codecs" and "Authentication" titled "## Enum Types" that documents with_enum_type usage. Keep it concise — show registration and chaining with with_array_type.

Add Enum type registration via CodecRegistry.with_enum_type() to the Supported Features list.

7. Update CLAUDE.md

Two sections need updating:

• Codec Architecture section: Document with_enum_type in the CodecRegistry description alongside with_codec and with_array_type.
• Public API Types section: Add with_enum_type(oid) to the CodecRegistry entry.

8. Create release notes

File: .release-notes/next-release.md (append to existing file)

User-facing addition: with_enum_type on CodecRegistry.

[SeanTAllen]

Implemented in #186.