postgres-bytea

postgres-bytea

Decode/encode Postgres bytea strings to Buffers

Install

npm install postgres-bytea

Usage

Decoding

To decode a bytea string into a buffer:

const bytea = require('postgres-bytea')

// bytea hex format
bytea.decode('\\x1234') // <Buffer 12 34>

// bytea escape format
bytea.decode('\\000\\100\\200') // <Buffer 00 40 80>

The decode function supports both the hex format used in Postgres 9+ and the escape format used in Postgres 8 and earlier. It automatically detects the format from the incoming data.

For backward compatibility, decode is also the default export from the package.

Decoding (Stream)

To decode a bytea hex stream into binary:

const bytea = require('postgres-bytea')

readable.pipe(new bytea.Decoder())

Decoder expects a double-escaped \\x prefix to allow reading from a COPY TO statement.

Encoding (Stream)

const bytea = require('postgres-bytea')

readable.pipe(new bytea.Encoder())

Encoder adds a double-escaped \\x prefix to allow writing to a COPY FROM statement.

API

bytea.decode(input) -> buffer

input

Required
Type: string

A Postgres bytea binary string.

new bytea.Decoder() -> stream.Transform

Creates a bytea decoder stream that emits buffer chunks.

new bytea.Encoder() -> stream.Transform

Creates a bytea encoder stream that receives buffer chunks and emits them as bytea strings.

Prefix Escaping

The “hex” format encodes binary data as 2 hexadecimal digits per byte, most significant nibble first. The entire string is preceded by the sequence \x (to distinguish it from the escape format). In some contexts, the initial backslash may need to be escaped by doubling it (see Section 4.1.2.1).

https://www.postgresql.org/docs/12/datatype-binary.html#id-1.5.7.12.9

A SELECT statement returns bytea values using the single-escaped \x prefix. The COPY TO and COPY FROM commands expect and return bytea values with the double-escaped \\x prefix.

bytea.decode expects the single-escaped prefix. The Decoder and Encoder streams expect the double-escaped prefix, since they are most useful in COPY FROM and COPY TO statements.

License

MIT © Ben Drucker