Add bytea type conversion (#119)

PostgreSQL bytea columns (OID 17) are now decoded from hex format into
`Array[U8] val` instead of being returned as raw hex strings. Only hex
format is supported (the default since PostgreSQL 9.0).

The `FieldDataTypes` union gains `Array[U8] val` as a ninth variant.
Existing code is unaffected — Pony's match is non-exhaustive, so code
without a bytea arm continues to work.

`Field.eq()` implements element-by-element comparison for byte arrays
since Pony's `Array` uses identity comparison by default.

Design: #118

Author: SeanTAllen

.release-notes/bytea-type-conversion.md

@@ -0,0 +1,23 @@
+## Add bytea type conversion
+
+PostgreSQL `bytea` columns are now automatically decoded from hex format into `Array[U8] val`. Previously, bytea values were returned as raw hex strings (e.g., `\x48656c6c6f`). They are now decoded into byte arrays that you can work with directly.
+
+```pony
+be pg_query_result(session: Session, result: Result) =>
+  match result
+  | let rs: ResultSet =>
+    for row in rs.rows().values() do
+      for field in row.fields.values() do
+        match field.value
+        | let bytes: Array[U8] val =>
+          // Decoded bytes — e.g., [72; 101; 108; 108; 111] for "Hello"
+          for b in bytes.values() do
+            _env.out.print("byte: " + b.string())
+          end
+        end
+      end
+    end
+  end
+```
+
+Existing code is unaffected — if your `match` on `field.value` doesn't include an `Array[U8] val` arm, bytea values simply won't match any branch (Pony's match is non-exhaustive).

CLAUDE.md

@@ -98,7 +98,7 @@ Only one operation is in-flight at a time. The queue serializes execution. `quer
 - `NamedPreparedQuery` — val class wrapping a statement name + `Array[(String | None)] val` params (executes a previously prepared named statement)
 - `Result` trait — `ResultSet` (rows), `SimpleResult` (no rows), `RowModifying` (INSERT/UPDATE/DELETE with count)
 - `Rows` / `Row` / `Field` — result data. `Field.value` is `FieldDataTypes` union
-- `FieldDataTypes` = `(Bool | F32 | F64 | I16 | I32 | I64 | None | String)`
+- `FieldDataTypes` = `(Array[U8] val | Bool | F32 | F64 | I16 | I32 | I64 | None | String)`
 - `TransactionStatus` — union type `(TransactionIdle | TransactionInBlock | TransactionFailed)`. Reported via `pg_transaction_status` callback on every `ReadyForQuery`.
 - `Notification` — val class wrapping channel name, payload string, and notifying backend's process ID. Delivered via `pg_notification` callback.
 - `NoticeResponseMessage` — non-fatal PostgreSQL notice with all standard fields (same structure as `ErrorResponseMessage`). Delivered via `pg_notice` callback.
@@ -117,6 +117,7 @@ Only one operation is in-flight at a time. The queue serializes execution. `quer
 
 In `_RowsBuilder._field_to_type()`:
 - 16 (bool) → `Bool` (checks for "t")
+- 17 (bytea) → `Array[U8] val` (hex-format decode: strips `\x` prefix, parses hex pairs)
 - 20 (int8) → `I64`
 - 21 (int2) → `I16`
 - 23 (int4) → `I32`
@@ -145,6 +146,8 @@ Tests live in the main `postgres/` package (private test classes), organized acr
 - `_TestPrepareShutdownDrainsPrepareQueue` — uses a local TCP listener that auto-auths but never becomes ready; verifies pending prepare operations get `SessionClosed` failures on shutdown
 - `_TestTerminateSentOnClose` — mock server fully authenticates and becomes ready; verifies that closing the session sends a Terminate message ('X') to the server
 - `_TestZeroRowSelectReturnsResultSet` — mock server sends RowDescription + CommandComplete("SELECT 0") with no DataRows; verifies ResultSet (not RowModifying) with zero rows
+- `_TestByteaResultDecoding` — mock server sends RowDescription (bytea column, OID 17) + DataRow with hex-encoded value + CommandComplete; verifies field value is `Array[U8] val` with correct decoded bytes
+- `_TestEmptyByteaResultDecoding` — mock server sends DataRow with empty bytea (`\x`); verifies empty `Array[U8] val`
 
 **`_test_ssl.pony`** — SSL negotiation unit tests (mock servers) and SSL integration tests:
 - `_TestSSLNegotiationRefused` — mock server responds 'N' to SSLRequest; verifies `pg_session_connection_failed` fires
@@ -167,7 +170,7 @@ Tests live in the main `postgres/` package (private test classes), organized acr
 **`_test_md5.pony`** — MD5 integration tests: MD5/Authenticate, MD5/AuthenticateFailure, MD5/QueryResults
 
 **`_test_query.pony`** — Query integration tests:
-- Simple query: Query/Results, Query/AfterAuthenticationFailure, Query/AfterConnectionFailure, Query/AfterSessionHasBeenClosed, Query/OfNonExistentTable, Query/CreateAndDropTable, Query/InsertAndDelete, Query/EmptyQuery, ZeroRowSelect, MultiStatementMixedResults
+- Simple query: Query/Results, Query/ByteaResults, Query/AfterAuthenticationFailure, Query/AfterConnectionFailure, Query/AfterSessionHasBeenClosed, Query/OfNonExistentTable, Query/CreateAndDropTable, Query/InsertAndDelete, Query/EmptyQuery, ZeroRowSelect, MultiStatementMixedResults
 - Prepared query: PreparedQuery/Results, PreparedQuery/NullParam, PreparedQuery/OfNonExistentTable, PreparedQuery/InsertAndDelete, PreparedQuery/MixedWithSimple
 - Named prepared statements: PreparedStatement/Prepare, PreparedStatement/PrepareAndExecute, PreparedStatement/PrepareAndExecuteMultiple, PreparedStatement/PrepareAndClose, PreparedStatement/PrepareFails, PreparedStatement/PrepareAfterClose, PreparedStatement/CloseNonexistent, PreparedStatement/PrepareDuplicateName, PreparedStatement/MixedWithSimpleAndPrepared
 - COPY IN: CopyIn/Insert, CopyIn/AbortRollback
@@ -410,6 +413,7 @@ postgres/                         # Main package (49 files)
 assets/test-cert.pem              # Self-signed test certificate for SSL unit tests
 assets/test-key.pem               # Private key for SSL unit tests
 examples/README.md                # Examples overview
+examples/bytea/bytea-example.pony # Binary data with bytea columns
 examples/query/query-example.pony # Simple query with result inspection
 examples/ssl-query/ssl-query-example.pony # SSL-encrypted query with SSLRequired
 examples/prepared-query/prepared-query-example.pony # PreparedQuery with params and NULL

examples/README.md

@@ -2,6 +2,10 @@
 
 Each subdirectory is a self-contained Pony program demonstrating a different part of the postgres library.
 
+## bytea
+
+Binary data using `bytea` columns. Executes a SELECT that returns a bytea value, matches on `Array[U8] val` in the result, and prints the decoded bytes. Shows how the driver automatically decodes PostgreSQL's hex-format bytea representation into raw byte arrays.
+
 ## query
 
 Minimal example using `SimpleQuery`. Connects, authenticates, executes `SELECT 525600::text`, and prints the result by iterating rows and matching on `FieldDataTypes`. Start here if you're new to the library.

examples/bytea/bytea-example.pony

@@ -0,0 +1,99 @@
+"""
+Querying binary data using `bytea` columns. Executes a SELECT that returns a
+bytea value, matches on `Array[U8] val` in the result, and prints the decoded
+bytes. Shows how the driver automatically decodes PostgreSQL's hex-format
+bytea representation into raw byte arrays.
+"""
+use "cli"
+use "collections"
+use lori = "lori"
+// in your code this `use` statement would be:
+// use "postgres"
+use "../../postgres"
+
+actor Main
+  new create(env: Env) =>
+    let server_info = ServerInfo(env.vars)
+    let auth = lori.TCPConnectAuth(env.root)
+
+    let client = Client(auth, server_info, env.out)
+
+actor Client is (SessionStatusNotify & ResultReceiver)
+  let _session: Session
+  let _out: OutStream
+
+  new create(auth: lori.TCPConnectAuth, info: ServerInfo, out: OutStream) =>
+    _out = out
+    _session = Session(
+      ServerConnectInfo(auth, info.host, info.port),
+      DatabaseConnectInfo(info.username, info.password, info.database),
+      this)
+
+  be close() =>
+    _session.close()
+
+  be pg_session_authenticated(session: Session) =>
+    _out.print("Authenticated.")
+    _out.print("Sending bytea query....")
+    // The hex string \x48656c6c6f represents the ASCII bytes for "Hello".
+    let q = SimpleQuery("SELECT '\\x48656c6c6f'::bytea AS data")
+    session.execute(q, this)
+
+  be pg_session_authentication_failed(
+    s: Session,
+    reason: AuthenticationFailureReason)
+  =>
+    _out.print("Failed to authenticate.")
+
+  be pg_query_result(session: Session, result: Result) =>
+    match result
+    | let r: ResultSet =>
+      _out.print("ResultSet (" + r.rows().size().string() + " rows):")
+      for row in r.rows().values() do
+        for field in row.fields.values() do
+          _out.write(field.name + "=")
+          match field.value
+          | let v: Array[U8] val =>
+            _out.print(v.size().string() + " bytes")
+            // Print each byte's decimal value
+            for b in v.values() do
+              _out.print("  byte: " + b.string())
+            end
+          | let v: String => _out.print(v)
+          | let v: I16 => _out.print(v.string())
+          | let v: I32 => _out.print(v.string())
+          | let v: I64 => _out.print(v.string())
+          | let v: F32 => _out.print(v.string())
+          | let v: F64 => _out.print(v.string())
+          | let v: Bool => _out.print(v.string())
+          | None => _out.print("NULL")
+          end
+        end
+      end
+    | let r: RowModifying =>
+      _out.print(r.command() + " " + r.impacted().string() + " rows")
+    | let r: SimpleResult =>
+      _out.print("Query executed.")
+    end
+    close()
+
+  be pg_query_failed(session: Session, query: Query,
+    failure: (ErrorResponseMessage | ClientQueryError))
+  =>
+    _out.print("Query failed.")
+    close()
+
+class val ServerInfo
+  let host: String
+  let port: String
+  let username: String
+  let password: String
+  let database: String
+
+  new val create(vars: (Array[String] val | None)) =>
+    let e = EnvVars(vars)
+    host = try e("POSTGRES_HOST")? else "127.0.0.1" end
+    port = try e("POSTGRES_PORT")? else "5432" end
+    username = try e("POSTGRES_USERNAME")? else "postgres" end
+    password = try e("POSTGRES_PASSWORD")? else "postgres" end
+    database = try e("POSTGRES_DATABASE")? else "postgres" end

examples/crud/crud-example.pony

@@ -104,6 +104,8 @@ actor Client is (SessionStatusNotify & ResultReceiver)
             | let v: F32 => _out.write(v.string())
             | let v: F64 => _out.write(v.string())
             | let v: Bool => _out.write(v.string())
+            | let v: Array[U8] val =>
+              _out.write(v.size().string() + " bytes")
             | None => _out.write("NULL")
             end
           end

examples/named-prepared-query/named-prepared-query-example.pony

@@ -73,6 +73,8 @@ actor Client is (SessionStatusNotify & ResultReceiver & PrepareReceiver)
           | let v: F32 => _out.print(v.string())
           | let v: F64 => _out.print(v.string())
           | let v: Bool => _out.print(v.string())
+          | let v: Array[U8] val =>
+            _out.print(v.size().string() + " bytes")
           | None => _out.print("NULL")
           end
         end

examples/prepared-query/prepared-query-example.pony

@@ -58,6 +58,8 @@ actor Client is (SessionStatusNotify & ResultReceiver)
           | let v: F32 => _out.print(v.string())
           | let v: F64 => _out.print(v.string())
           | let v: Bool => _out.print(v.string())
+          | let v: Array[U8] val =>
+            _out.print(v.size().string() + " bytes")
           | None => _out.print("NULL")
           end
         end

examples/query/query-example.pony

@@ -53,6 +53,8 @@ actor Client is (SessionStatusNotify & ResultReceiver)
           | let v: F32 => _out.print(v.string())
           | let v: F64 => _out.print(v.string())
           | let v: Bool => _out.print(v.string())
+          | let v: Array[U8] val =>
+            _out.print(v.size().string() + " bytes")
           | None => _out.print("NULL")
           end
         end

examples/ssl-query/ssl-query-example.pony

@@ -77,6 +77,8 @@ actor Client is (SessionStatusNotify & ResultReceiver)
           | let v: F32 => _out.print(v.string())
           | let v: F64 => _out.print(v.string())
           | let v: Bool => _out.print(v.string())
+          | let v: Array[U8] val =>
+            _out.print(v.size().string() + " bytes")
           | None => _out.print("NULL")
           end
         end

postgres/_test.pony

@@ -26,6 +26,7 @@ actor \nodoc\ Main is TestList
     test(_TestQueryAfterConnectionFailure)
     test(_TestQueryAfterSessionHasBeenClosed)
     test(_TestQueryResults)
+    test(_TestQueryByteaResults)
     test(_TestQueryOfNonExistentTable)
     test(_TestResponseParserAuthenticationMD5PasswordMessage)
     test(_TestResponseParserAuthenticationOkMessage)
@@ -73,6 +74,8 @@ actor \nodoc\ Main is TestList
     test(_TestUnansweredQueriesFailOnShutdown)
     test(_TestPrepareShutdownDrainsPrepareQueue)
     test(_TestZeroRowSelectReturnsResultSet)
+    test(_TestByteaResultDecoding)
+    test(_TestEmptyByteaResultDecoding)
     test(_TestZeroRowSelect)
     test(_TestMultiStatementMixedResults)
     test(_TestPreparedQueryResults)