postgres-bytea

library3.0.0jsnpmunverified

The `postgres-bytea` library provides robust functionality for parsing and encoding PostgreSQL `bytea` binary strings within Node.js applications. It supports both the modern 'hex' format (prefixed with `\x`) used in PostgreSQL 9.0 and later, as well as the older 'escape' format from PostgreSQL 8 and earlier, automatically detecting the input format. The current stable version is 3.0.0. While specific release cadence is not explicitly stated, the package appears actively maintained given recent NPM activity. Its key differentiation lies in its dual approach to `bytea` handling: a direct `decode` function for quick conversions and stream-based `Decoder` and `Encoder` classes for handling larger data volumes efficiently, particularly useful with PostgreSQL's `COPY` commands.

database serialization

npm install postgres-bytea

github ↗package ↗

INSTALL

IMPORT

SIG · POSTGRES-BYTEA

postgres-bytea

databasejavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

decode

✓ import { decode } from 'postgres-bytea'

✗ import bytea from 'postgres-bytea'

While `decode` is also the default export for backward compatibility, named import is preferred in modern ESM contexts. The default export is `bytea` which aliases `decode`.

Decoder

✓ import { Decoder } from 'postgres-bytea'

✗ const Decoder = require('postgres-bytea').Decoder

Imports the stream-based decoder for processing `bytea` data in chunks. For CJS, use `require('postgres-bytea').Decoder`.

Encoder

✓ import { Encoder } from 'postgres-bytea'

✗ const Encoder = require('postgres-bytea').Encoder

Imports the stream-based encoder for converting binary data into `bytea` strings. For CJS, use `require('postgres-bytea').Encoder`.

bytea (default export)

✓ import bytea from 'postgres-bytea'

✗ import { bytea } from 'postgres-bytea'

The default export `bytea` is an alias for the `decode` function. This is primarily for backward compatibility.

This quickstart demonstrates how to decode a PostgreSQL `bytea` hex string into a Node.js Buffer and how to encode a Buffer back into a `bytea` string using the stream API. It highlights the expected string formats for direct `decode` and stream-based `Encoder`/`Decoder` operations.

import { decode, Encoder } from 'postgres-bytea'; import { pipeline } from 'stream/promises'; import { Buffer } from 'buffer'; async function runByteaExample() { // Example of a PostgreSQL bytea hex string (e.g., from a SELECT query) const hexByteaString = '\\x48656c6c6f20506f7374677265735141'; // 'Hello PostgresQA' // 1. Decoding a bytea string to a Buffer const decodedBuffer = decode(hexByteaString); console.log('Decoded Buffer:', decodedBuffer); // <Buffer 48 65 6c 6c 6f 20 50 6f 73 74 67 72 65 73 51 41> console.log('Decoded String:', decodedBuffer.toString('utf8')); // 'Hello PostgresQA' // Example binary data to encode const originalData = Buffer.from('Binary data for PostgreSQL'); let encodedBytea = ''; // 2. Encoding a Buffer to a bytea string using a stream const encoder = new Encoder(); encoder.on('data', (chunk) => { encodedBytea += chunk.toString('utf8'); }); await pipeline(Buffer.from(originalData), encoder); console.log('Original Data:', originalData.toString()); console.log('Encoded Bytea (from stream):', encodedBytea); // Expected encoded format for COPY TO/FROM would be '\\x...' or escape format // The Encoder stream emits chunks in the double-escaped hex format (e.g., \\x4269...) // if bytea_output is 'hex' and it's used with COPY operations. // The direct decode function expects single-escaped hex (\x...). // Verify decoding of the streamed output (adjusting for single vs double escaping) const cleanedEncodedBytea = encodedBytea.replace(/\\\\x/, '\\x'); // Change \\x to \x for decode function const reDecodedBuffer = decode(cleanedEncodedBytea); console.log('Re-decoded String (from stream output):', reDecodedBuffer.toString('utf8')); }

Debug

Known issues

breakingWhile `postgres-bytea` v3.0.0 has been available for some time, major version bumps often imply breaking changes from previous major versions (e.g., v2.x). Developers should consult the project's changelog on GitHub for a detailed migration guide, especially regarding module resolution or API surface adjustments if migrating from an older major version.

fix

Review the official changelog or migration guide on the GitHub repository when upgrading from previous major versions. Test your application thoroughly after upgrade.

affects: >=3.0.0

gotchaThe `decode` function expects `bytea` strings with a single backslash for the hex prefix (e.g., `\xDEADBEEF`), typically returned by `SELECT` queries. In contrast, the `Decoder` and `Encoder` streams, designed for `COPY TO` and `COPY FROM` operations, expect and produce `bytea` strings with a double backslash prefix (e.g., `\\xDEADBEEF`). Mismatching these formats will lead to incorrect parsing or encoding errors.

fix

Ensure the input `bytea` string format matches the expected format for the specific API (single `\x` for `decode`, double `\\x` for streams). If using `COPY` commands, be mindful of the `bytea_output` setting in PostgreSQL and adjust accordingly.

affects: >=1.0.0

gotchaThe library automatically detects whether the input is in hex format or the older escape format for decoding. However, encoding always produces the hex format. When dealing with legacy PostgreSQL systems that might rely solely on the escape format, manual conversion or database configuration (`SET bytea_output = 'escape'`) might be necessary, though hex is preferred for performance and compatibility.

fix

For new applications, configure PostgreSQL to use `bytea_output = 'hex'` (which is the default in modern Postgres versions). If interacting with older systems or applications expecting the escape format, ensure your database connection or queries explicitly handle the output format.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Invalid bytea input: must start with \x or a valid escape sequence

The input string passed to `decode` or a `Decoder` stream does not conform to the expected PostgreSQL bytea hex (e.g., `\x...` or `\\x...`) or escape format. This often happens if the `\x` prefix is missing, or if the string contains invalid characters for the hex format.

fix

Verify that the `bytea` string retrieved from PostgreSQL includes the correct prefix and only contains valid hexadecimal characters (0-9, a-f, A-F) after the prefix for hex format. Ensure backslashes are correctly escaped if manually constructing the string, especially when dealing with stream APIs that expect double backslashes.

TypeError: decode is not a function

This typically occurs when attempting to use `decode` as a named export but importing the default export, or vice versa, in CommonJS or hybrid module environments. For example, `const { decode } = require('postgres-bytea')` when only a default export is available, or `const bytea = require('postgres-bytea'); bytea.decode(...)` when `decode` is the direct default export.

fix

If using ES Modules, prefer `import { decode } from 'postgres-bytea';`. If using CommonJS, use `const { decode } = require('postgres-bytea');` or `const bytea = require('postgres-bytea'); const decode = bytea;` if `decode` is the default export (which it is for compatibility). Check the `package.json` `type` field if present, or test import behavior.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/bendrucker/postgres-bytea ↗

packagehttps://www.npmjs.com/package/postgres-bytea ↗