Module copy 

HyperBinary COPY format support.

This module provides support for Hyper’s binary COPY format (HyperBinary), which differs from standard PostgreSQL binary COPY in several ways optimized for throughput.

Format Overview

The HyperBinary format consists of:

• Header: "HPRCPY" + 13 null bytes (19 bytes total)
• Data: Values with null indicators (1 byte each for nullable columns)
• All values are little-endian encoded
• No tuple start markers (unlike PostgreSQL)

For nullable columns: [1 byte null indicator (0=not null, 1=null)] + [value] For non-nullable columns: just [value] (no indicator)

Differences from PostgreSQL Binary COPY

Aspect	PostgreSQL	HyperBinary
Header signature	"PGCOPY\n\xff\r\n\0" (11 bytes) + flags + ext	"HPRCPY" + 13 null bytes (19 bytes)
Byte order	Big-endian (network order)	Little-endian (x86 native)
Row framing	2-byte field count per row	No per-row framing
Null encoding	-1 length prefix (4 bytes)	1-byte indicator on nullable columns only
Non-null values	4-byte length prefix + data	Raw data (fixed-size) or length-prefixed (variable)
Trailer	2-byte -1 sentinel	None

The little-endian encoding and absence of per-row framing reduce both encoding overhead and byte-swapping on x86/ARM-LE architectures, which is where Hyper is typically deployed.

Structs

CopyDataBuilder

A builder for HyperBinary COPY data.

Enums

CopyReadError

Errors that can occur when reading HyperBinary COPY data.

Constants

HYPER_BINARY_FORMAT

The HyperBinary data format identifier for Hyper’s protocol.

HYPER_BINARY_HEADER

The full HyperBinary COPY header (19 bytes).

HYPER_BINARY_HEADER_SIZE

Size of the HyperBinary header (19 bytes).

HYPER_BINARY_SIGNATURE

The HyperBinary COPY signature (“HPRCPY” + 13 null bytes).

Functions

read_data128

Reads a 128-bit value from HyperBinary format.

read_i8

Reads an i8 value from HyperBinary format (LittleEndian).

read_i16

Reads an i16 value from HyperBinary format (LittleEndian).

read_i32

Reads an i32 value from HyperBinary format (LittleEndian).

read_i64

Reads an i64 value from HyperBinary format (LittleEndian).

read_varbinary

Reads a variable-length binary value from HyperBinary format.

write_data128

Writes a 128-bit value (NUMERIC, INTERVAL) for a nullable column. Format: [not-null indicator: 1 byte (0)][value: 16 bytes LittleEndian]

write_data128_not_null

Writes a 128-bit value for a non-nullable column. Format: [value: 16 bytes LittleEndian]

write_f32

Writes an f32 value (REAL/FLOAT4) for a nullable column. Format: [not-null indicator: 1 byte (0)][value: 4 bytes LittleEndian]

write_f64

Writes an f64 value (DOUBLE PRECISION/FLOAT8) for a nullable column. Format: [not-null indicator: 1 byte (0)][value: 8 bytes LittleEndian]

write_f32_not_null

Writes an f32 value for a non-nullable column. Format: [value: 4 bytes LittleEndian]

write_f64_not_null

Writes an f64 value for a non-nullable column. Format: [value: 8 bytes LittleEndian]

write_header

Writes the HyperBinary COPY header to a buffer.

write_i8

Writes an i8 value (bool) for a nullable column. Format: [not-null indicator: 1 byte (0)][value: 1 byte]

write_i8_not_null

Writes an i8 value for a non-nullable column. Format: [value: 1 byte] (no null indicator)

write_i16

Writes an i16 value (SMALLINT) for a nullable column. Format: [not-null indicator: 1 byte (0)][value: 2 bytes LittleEndian]

write_i32

Writes an i32 value (INT) for a nullable column. Format: [not-null indicator: 1 byte (0)][value: 4 bytes LittleEndian]

write_i64

Writes an i64 value (BIGINT) for a nullable column. Format: [not-null indicator: 1 byte (0)][value: 8 bytes LittleEndian]

write_i16_not_null

Writes an i16 value for a non-nullable column. Format: [value: 2 bytes LittleEndian]

write_i32_not_null

Writes an i32 value for a non-nullable column. Format: [value: 4 bytes LittleEndian]

write_i64_not_null

Writes an i64 value for a non-nullable column. Format: [value: 8 bytes LittleEndian]

write_null

Writes a NULL value (1 byte with value 1).

write_trailer

Writes the COPY trailer (no-op for HyperBinary).

write_tuple_start

Writes a tuple start marker (no-op for HyperBinary).

write_varbinary

Writes a variable-length binary value (TEXT, BYTEA) for a nullable column. Format: [not-null indicator: 1 byte (0)][length: 4 bytes LittleEndian][data: N bytes]

write_varbinary_not_null

Writes a variable-length binary value for a non-nullable column. Format: [length: 4 bytes LittleEndian][data: N bytes]