Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

PgTypes unstable

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.

interval values decode to Interval, preserving calendar months, days, and signed bigint microseconds independently. No units are normalized. Convert microseconds explicitly before JSON serialization.

46 exports Since v4.0.0 Source

Constants

OID

unstable
Since v4.0.0

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 interval: 1186;
  readonly intervalArray: 1187;
  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 regclass: 2205;
  readonly regclassArray: 2210;
  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

array

unstable
Since v4.0.0

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>

bool

unstable
Since v4.0.0

A bool parameter.

Signature

declare const bool: (value: boolean | null) => Parameter

bpchar

unstable
Since v4.0.0

A bpchar parameter.

Signature

declare const bpchar: (value: string | null) => Parameter

bytea

unstable
Since v4.0.0

A bytea parameter.

Signature

declare const bytea: (value: Uint8Array | null) => Parameter

cidr

unstable
Since v4.0.0

A cidr parameter.

Signature

declare const cidr: (value: string | null) => Parameter

date

unstable
Since v4.0.0

A date parameter, given as YYYY-MM-DD, "infinity", or "-infinity".

Signature

declare const date: (value: string | null) => Parameter

float4

unstable
Since v4.0.0

A float4 parameter.

Signature

declare const float4: (value: number | null) => Parameter

float8

unstable
Since v4.0.0

A float8 parameter.

Signature

declare const float8: (value: number | null) => Parameter

inet

unstable
Since v4.0.0

An inet parameter, such as "10.0.0.1" or "10.0.0.0/8".

Signature

declare const inet: (value: string | null) => Parameter

int2

unstable
Since v4.0.0

An int2 parameter.

Signature

declare const int2: (value: number | null) => Parameter

int4

unstable
Since v4.0.0

An int4 parameter.

Signature

declare const int4: (value: number | null) => Parameter

int8

unstable
Since v4.0.0

An int8 parameter.

Signature

declare const int8: (value: bigint | null) => Parameter

interval

unstable
Since v4.0.0

An interval parameter with independent months, days, and microseconds.

Signature

declare const interval: (value: Interval | null) => Parameter

json

unstable
Since v4.0.0

A json parameter.

Signature

declare const json: (value: unknown) => Parameter

jsonb

unstable
Since v4.0.0

A jsonb parameter.

Signature

declare const jsonb: (value: unknown) => Parameter

makeRegistry

unstable
Since v4.0.0

Creates a client-specific registry containing the built-in codecs.

Signature

declare function makeRegistry(): Registry

name

unstable
Since v4.0.0

A name parameter.

Signature

declare const name: (value: string | null) => Parameter

numeric

unstable
Since v4.0.0

A numeric parameter, given as a decimal string or "NaN".

Signature

declare const numeric: (value: string | null) => Parameter

oid

unstable
Since v4.0.0

An oid parameter.

Signature

declare const oid: (value: number | null) => Parameter

text

unstable
Since v4.0.0

A text parameter.

Signature

declare const text: (value: string | null) => Parameter

time

unstable
Since v4.0.0

A time parameter, given as microseconds since midnight.

Signature

declare const time: (value: bigint | null) => Parameter

timestamp

unstable
Since v4.0.0

A 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) => Parameter

timestamptz

unstable
Since v4.0.0

A timestamptz parameter, given as a Date or Unix epoch milliseconds.

Signature

declare const timestamptz: (value: Date | number | null) => Parameter

timetz

unstable
Since v4.0.0

A timetz parameter, such as "12:34:56+02:00".

Signature

declare const timetz: (value: string | null) => Parameter

uuid

unstable
Since v4.0.0

A uuid parameter.

Signature

declare const uuid: (value: string | null) => Parameter

varchar

unstable
Since v4.0.0

A varchar parameter.

Signature

declare const varchar: (value: string | null) => Parameter

Decoding

decode

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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 RowDescription
declare const description: PgProtocol.RowDescription
parser.readField = Result.getOrThrow(PgTypes.makeFieldReader(description.fields))

Encoding

encode

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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): boolean

writeParameter

unstable
Since v4.0.0

Writes a parameter into a Bind frame.

Signature

declare function writeParameter(sink: ValueSink, parameter: Parameter, registry?: Registry): Result<void, CodecError>

Errors

CodecError

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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 | undefined

Guards

isParameter

unstable
Since v4.0.0

Returns whether a value is a parameter created by this module.

Signature

declare function isParameter(value: unknown): value is Parameter

Models

Codec

interface unstable
Since v4.0.0

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>;
}

Column

interface unstable
Since v4.0.0

A result column, as RowDescription describes one.

Signature

interface Column {
  readonly dataTypeOid: number;
  readonly format: number;
}

Interval

interface unstable
Since v4.0.0

A PostgreSQL interval with independent signed calendar and time components. Months and days are int32 values; microseconds is an int64 value.

Signature

interface Interval {
  readonly days: number;
  readonly microseconds: bigint;
  readonly months: number;
}

Parameter

interface unstable
Since v4.0.0

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 unstable
Since v4.0.0

Options for registering a codec.

Signature

interface RegisterOptions {
  readonly arrayOid?: number;
}

Registry

interface unstable
Since v4.0.0

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

register

unstable
Since v4.0.0

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>): void

unregister

unstable
Since v4.0.0

Removes a previously registered codec.

Signature

declare function unregister(oid: number): void

Type IDs

ParameterTypeId

unstable
Since v4.0.0

The runtime type identifier for PostgreSQL parameters.

Signature

declare const ParameterTypeId: ParameterTypeId

ParameterTypeId

type unstable
Since v4.0.0

The type-level identifier for PostgreSQL parameters.

Signature

type ParameterTypeId = "~@effect/sql-pg/PgTypes/Parameter"