PgTypes
Binary codecs for PostgreSQL values, keyed by type OID.
Version 1 implements the binary wire format (format = 1) only; passing
format = 0 to decode is an error. Layouts follow rust-postgres'
postgres-types, including the infinity sentinels, and assume the server
was built with integer_datetimes (the only supported configuration since
PostgreSQL 10).
There is no typeof inference: an OID is always supplied, either directly
or through a constructor such as int4 that carries it.
timestamp and timestamptz values, including array elements, decode to
Date. Encoders accept Date or epoch milliseconds.
Decoding truncates to milliseconds toward zero relative to the PostgreSQL
epoch. To restore numeric decoding, override the codecs with register
or a client Registry.
infinity, -infinity and values outside the JavaScript Date range
(±8.64e15 epoch milliseconds) decode to an invalid Date. Numeric
±Infinity encodes the PostgreSQL sentinels; encoding an invalid Date fails.
The timestamp codec maps wall-clock fields to UTC fields of a Date.
Date parameters bind as timestamptz, so inserting one into a timestamp
column applies the session TimeZone. Use UTC or timestamp(value) to
preserve its UTC fields. timestamptz round trips preserve the instant
regardless of session timezone.
Constants
Type OIDs implemented by version 1 of this codec.
Signature
declare const OID: { readonly bool: 16; readonly boolArray: 1000; readonly bpchar: 1042; readonly bpcharArray: 1014; readonly bytea: 17; readonly byteaArray: 1001; readonly cidr: 650; readonly cidrArray: 651; readonly date: 1082; readonly dateArray: 1182; readonly float4: 700; readonly float4Array: 1021; readonly float8: 701; readonly float8Array: 1022; readonly inet: 869; readonly inetArray: 1041; readonly int2: 21; readonly int2Array: 1005; readonly int4: 23; readonly int4Array: 1007; readonly int8: 20; readonly int8Array: 1016; readonly json: 114; readonly jsonArray: 199; readonly jsonb: 3802; readonly jsonbArray: 3807; readonly name: 19; readonly nameArray: 1003; readonly numeric: 1700; readonly numericArray: 1231; readonly oid: 26; readonly oidArray: 1028; readonly text: 25; readonly textArray: 1009; readonly time: 1083; readonly timeArray: 1183; readonly timestamp: 1114; readonly timestampArray: 1115; readonly timestamptz: 1184; readonly timestamptzArray: 1185; readonly timetz: 1266; readonly timetzArray: 1270; readonly uuid: 2950; readonly uuidArray: 2951; readonly varchar: 1043; readonly varcharArray: 1015;}Constructors
A one-dimensional array parameter whose elements have the given OID.
Signature
declare function array(values: readonly Array<unknown> | null, elementOid: number, registry?: Registry): Result<Parameter, CodecError>A bool parameter.
Signature
declare const bool: (value: boolean | null) => ParameterA bpchar parameter.
Signature
declare const bpchar: (value: string | null) => ParameterA bytea parameter.
Signature
declare const bytea: (value: Uint8Array | null) => ParameterA cidr parameter.
Signature
declare const cidr: (value: string | null) => ParameterA date parameter, given as YYYY-MM-DD, "infinity", or "-infinity".
Signature
declare const date: (value: string | null) => ParameterA float4 parameter.
Signature
declare const float4: (value: number | null) => ParameterA float8 parameter.
Signature
declare const float8: (value: number | null) => ParameterAn inet parameter, such as "10.0.0.1" or "10.0.0.0/8".
Signature
declare const inet: (value: string | null) => ParameterAn int2 parameter.
Signature
declare const int2: (value: number | null) => ParameterAn int4 parameter.
Signature
declare const int4: (value: number | null) => ParameterAn int8 parameter.
Signature
declare const int8: (value: bigint | null) => ParameterA json parameter.
Signature
declare const json: (value: unknown) => ParameterA jsonb parameter.
Signature
declare const jsonb: (value: unknown) => ParametermakeRegistry
Creates a client-specific registry containing the built-in codecs.
Signature
declare function makeRegistry(): RegistryA name parameter.
Signature
declare const name: (value: string | null) => ParameterA numeric parameter, given as a decimal string or "NaN".
Signature
declare const numeric: (value: string | null) => ParameterAn oid parameter.
Signature
declare const oid: (value: number | null) => ParameterA text parameter.
Signature
declare const text: (value: string | null) => ParameterA time parameter, given as microseconds since midnight.
Signature
declare const time: (value: bigint | null) => ParameterA timestamp parameter from a Date or epoch milliseconds. UTC fields
become the stored wall-clock fields, regardless of session TimeZone.
Signature
declare const timestamp: (value: Date | number | null) => Parametertimestamptz
A timestamptz parameter, given as a Date or Unix epoch milliseconds.
Signature
declare const timestamptz: (value: Date | number | null) => ParameterA timetz parameter, such as "12:34:56+02:00".
Signature
declare const timetz: (value: string | null) => ParameterA uuid parameter.
Signature
declare const uuid: (value: string | null) => ParameterA varchar parameter.
Signature
declare const varchar: (value: string | null) => ParameterDecoding
Decodes the binary representation of the given OID.
Details
Only binary format (1) is supported. Unregistered OIDs decode as UTF-8
text; invalid UTF-8 fails with CodecError. See register for binary
user-defined types, including arrays.
Signature
declare function decode(bytes: Uint8Array, oid: number, format: number, registry?: Registry): Result<unknown, CodecError>makeFieldReader
Creates a field reader for PgProtocol.makeParser.
Details
Codecs are resolved once per column. SQL NULL becomes null.
Unregistered OIDs decode as UTF-8 text. Invalid UTF-8 and text-format
columns fail with CodecError.
Signature
declare function makeFieldReader(columns: readonly Array<Column>, registry?: Registry): Result<FieldReader<unknown>, CodecError>Example
import { PgProtocol, PgTypes } from "@effect/sql-pg"
const parser = PgProtocol.makeParser({ readField: Result.getOrThrow(PgTypes.makeFieldReader([])) })// on each RowDescriptiondeclare const description: PgProtocol.RowDescriptionparser.readField = Result.getOrThrow(PgTypes.makeFieldReader(description.fields))Encoding
Encodes a JavaScript value as the binary representation of the given OID.
Details
Returns a CodecError failure when the value has the wrong JavaScript type,
or when the OID is neither built in nor registered.
Signature
declare function encode(value: unknown, oid: number, registry?: Registry): Result<Uint8Array<ArrayBufferLike>, CodecError>encodeParameter
Encodes a parameter for a Bind message. SQL NULL stays null.
Signature
declare function encodeParameter(parameter: Parameter, registry?: Registry): Result<Uint8Array<ArrayBufferLike> | null, CodecError>isTextFormat
Returns whether a parameter uses the text format in a Bind message.
Untyped parameters (OID 0) use text so PostgreSQL can infer their type;
typed parameters use the binary format.
Signature
declare function isTextFormat(parameter: Parameter): booleanwriteParameter
Writes a parameter into a Bind frame.
Signature
declare function writeParameter(sink: ValueSink, parameter: Parameter, registry?: Registry): Result<void, CodecError>Errors
CodecError
Failure returned when a value cannot be encoded or decoded for its OID.
Signature
declare class CodecError extends YieldableError<this> & { readonly _tag: "PgTypesCodecError";} & Readonly<{ readonly message: string;}> { constructor(args: { readonly message: string; });}Getters
arrayOidFor
Returns the array OID whose elements have the given OID, or undefined
when there is no array type registered for it.
Signature
declare function arrayOidFor(elementOid: number, registry?: Registry): number | undefinedGuards
isParameter
Returns whether a value is a parameter created by this module.
Signature
declare function isParameter(value: unknown): value is ParameterModels
A binary codec for a single OID.
Signature
interface Codec<A> { readonly decode: (bytes: Uint8Array) => Result<A, CodecError>; readonly encode: (value: A) => Result<Uint8Array<ArrayBufferLike>, CodecError>; readonly read?: (bytes: Uint8Array, offset: number, size: number) => Result<A, CodecError>; readonly write?: (sink: ValueSink, value: A) => Result<void, CodecError>;}A result column, as RowDescription describes one.
Signature
interface Column { readonly dataTypeOid: number; readonly format: number;}A value paired with the OID it should be encoded as.
Signature
interface Parameter { readonly "~@effect/sql-pg/PgTypes/Parameter": "~@effect/sql-pg/PgTypes/Parameter"; readonly oid: number; readonly value: unknown;}RegisterOptions interface
Options for registering a codec.
Signature
interface RegisterOptions { readonly arrayOid?: number;}A client-specific set of PostgreSQL binary codecs. Each registry starts with the built-in codecs and does not affect the module-level registry.
Signature
interface Registry { readonly register: <A>(oid: number, codec: Codec<A>, options?: RegisterOptions) => void;}Registry
Registers a binary codec for an OID the built-in catalogue does not cover, or overrides a built-in one. Registered codecs take precedence.
Details
Unregistered OIDs decode as UTF-8 text. Register binary user-defined types
to avoid garbled output or codec errors, which close the connection when
reading rows. For arrays, use makeRegistry().register with
RegisterOptions.arrayOid and pass the registry as the client's types option.
Signature
declare function register<A>(oid: number, codec: Codec<A>): voidunregister
Removes a previously registered codec.
Signature
declare function unregister(oid: number): voidType IDs
ParameterTypeId
The runtime type identifier for PostgreSQL parameters.
Signature
declare const ParameterTypeId: ParameterTypeIdParameterTypeId type
The type-level identifier for PostgreSQL parameters.
Signature
type ParameterTypeId = "~@effect/sql-pg/PgTypes/Parameter"