Expanded Type Conversions

[SeanTAllen]

Analysis of the expanded type conversions listed in the feature roadmap (item 11). The roadmap identified these PostgreSQL types as candidates for explicit handling:

• numeric (1700) — arbitrary precision
• date (1082) — ISO format
• timestamp (1114) / timestamptz (1184) — ISO format
• uuid (2950) — standardized format
• json (114) / jsonb (3802) — JSON text
• bytea (17) — binary data
• interval (1186) — duration
• varchar (1043) / bpchar (1042) — character strings

Current Behavior

The driver converts 7 PostgreSQL type OIDs to native Pony types (bool, int2, int4, int8, float4, float8) and falls through to String for everything else. This means all of the types listed above already work — they arrive as String values.

Design Question

Should the driver add explicit handling for these types? Three options were considered:

1. Constrained types from Pony's constrained_types stdlib package — e.g., a UUID constrained type that validates format at construction. Rejected because the data comes from PostgreSQL, which has already validated it. Re-validating server output forces callers to handle a ValidationFailure case that can't happen.

2. Lightweight wrapper classes — e.g., class val UUID wrapping a String with no validation. Gives a distinct type in FieldDataTypes so callers can match on UUID vs String. Preserves PostgreSQL type identity without re-validating.

3. Leave as String — the current behavior.

Npgsql (F# / .NET) Precedent

Npgsql's approach was studied as a reference. Key findings:

• Npgsql strongly prefers built-in .NET types over custom wrappers. It maps uuid to .NET's Guid, date/timestamp to DateTime, numeric to decimal, bytea to byte[] — all built-in platform types.
• Npgsql actively removed earlier custom types (NpgsqlDate, NpgsqlTime, NpgsqlTimestamp) because "they were problematic and seldom used." Users preferred built-in types.
• The only custom type among these is NpgsqlInterval, which exists because .NET's TimeSpan genuinely cannot represent PostgreSQL's month/year interval components.
• A PR proposing NpgsqlDecimal for arbitrary-precision numeric was rejected — "we don't want to be in the business of maintaining arbitrary-precision decimal implementations."

Decision

Follow Npgsql's principle: only add explicit type conversions when there is a representative type in the Pony standard library.

Pony does not have built-in types for UUID, date, timestamp, decimal, interval, or JSON. Creating driver-specific wrapper types for all of these would add API surface the driver has to maintain, with questionable value — Npgsql tried this and walked it back.

The driver's job is to faithfully deliver what PostgreSQL sent. Domain modeling — deciding what "2024-01-15" or "550e8400-e29b-41d4-a716-446655440000" means in the application — is the caller's responsibility at the application boundary.

Result

PostgreSQL Type	Handling	Rationale
bytea (17)	Convert to Array[U8] val	Pony has this type; it faithfully represents binary data
numeric, date, timestamp, timestamptz, uuid, json, jsonb, interval	String (existing fall-through)	No representative Pony stdlib type
varchar, bpchar	String (existing fall-through)	These are strings

bytea is the only type that gets a new conversion. FieldDataTypes gains one new variant: Array[U8] val.

[SeanTAllen]

bytea support was added in #119