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 has no time zone on the wire and is treated as UTC in both
directions. Decoding drops sub-millisecond precision by truncating toward
zero, including for timestamps before the PostgreSQL epoch.
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, given as Unix epoch milliseconds and interpreted
as UTC.
Signature
declare const timestamp: (value: number | null) => Parametertimestamptz
A timestamptz parameter, given as Unix epoch milliseconds.
Signature
declare const timestamptz: (value: 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
format must be 1; the text format is not implemented. An OID that is
neither built in nor registered decodes to the raw bytes.
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, and columns
without a registered codec return a copy of their bytes. 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.
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"