Registry / database / postgres-large-object

postgres-large-object

library1.0.5jsnpmunverified

Provides large object support for PostgreSQL clients using the 'postgres' npm package. Current stable version is 1.0.5. It allows streaming of large binary objects (LOBs) to and from PostgreSQL, implementing the PostgreSQL large object API. Key differentiators: lightweight, zero dependencies beyond 'postgres', TypeScript types included, and designed for the modern 'postgres' client (not 'pg'). Suitable for storing and retrieving files, images, or any large binary data in PostgreSQL.

database

npm install postgres-large-object

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POSTGRES-LARGE-OBJ

postgres-large-object

databasejavascriptv1.0.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

LargeObjectManager

✓ import { LargeObjectManager } from 'postgres-large-object'

✗ import LargeObjectManager from 'postgres-large-object'

Named import; there is no default export.

LargeObject

✓ import { LargeObject } from 'postgres-large-object'

✗ const { LargeObject } = require('postgres-large-object')

ESM-only package; dynamic require() will fail. Use import or createRequire with ESM.

LargeObjectCursor

✓ import { LargeObjectCursor } from 'postgres-large-object'

✗ import { LargeObjectCursor } from 'postgres'

Do not confuse with 'postgres' client exports; this is from the large-object package.

Shows how to create, write to, and read from a PostgreSQL large object using the postgres-large-object library with ESM imports.

import { LargeObjectManager } from 'postgres-large-object'; import postgres from 'postgres'; const sql = postgres({ host: 'localhost', port: 5432, database: 'test', user: 'user', password: process.env.PG_PASSWORD ?? '' }); const manager = new LargeObjectManager({ sql }); // Create a new large object const oid = await manager.create(); console.log('Created large object with OID:', oid); // Write data const writeStream = await manager.openWriteStream(oid); writeStream.write('Hello, large object!'); writeStream.end(); // Read data const readStream = await manager.openReadStream(oid); let data = ''; for await (const chunk of readStream) { data += chunk; } console.log('Read data:', data); await sql.end();

Debug

Known issues

breakingv1.0.0 dropped support for Node.js < 14 and CommonJS. Only ESM is supported.

fix

Upgrade to Node.js 14+ and use ESM imports (import/export) instead of require().

affects: >=1.0.0

deprecatedThe 'pg' client is not supported. Only the 'postgres' client (npm package 'postgres') is compatible.

fix

Switch from 'pg' to 'postgres' client (the newer, modern PostgreSQL client for Node.js).

affects: >=1.0.0

gotchaLargeObjectManager constructor expects an object with 'sql' property, but previous versions used 'pg' or a connection string.

fix

Pass { sql: yourPostgresClientInstance } instead of { pg: ... } or a connection string.

affects: >=1.0.0

gotchaStreaming large objects requires the database connection to remain open. Closing the connection prematurely will cause errors.

fix

Ensure the 'sql' client is kept alive until all streams are fully consumed.

affects: >=1.0.0

breakingThe 'LargeObject' class methods have been made async in v1.0 (breaking from pre-release).

fix

Await all LargeObject methods like .read(), .write(), .tell(), etc.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: LargeObjectManager is not a constructor

Using CommonJS require() or mis-importing the module (e.g., default import instead of named).

fix

Use ESM: import { LargeObjectManager } from 'postgres-large-object'

Error: The `pg` client is not supported. Please use `postgres` client.

Attempting to use the library with the 'pg' PostgreSQL client package.

fix

Install and use the 'postgres' client (npm install postgres) and pass { sql: postgresClient } to LargeObjectManager.

Error: Large object OID is not valid

Passing an invalid or non-existent large object OID to a method.

fix

Ensure the OID is from a previously created large object and is a number (not a string).

TypeError: Cannot read properties of undefined (reading 'sql')

LargeObjectManager instantiated without the required {sql} option.

fix

Instantiate with: new LargeObjectManager({ sql: yourPostgresInstance })

Upgrade

Version history

1.0.5latest on npm

Audit

Dependencies

postgresrequiredPeer dependency: the PostgreSQL client library required for database connections. Must be installed separately.

Agent activity

4 hits · last 30 days

node

Resources

githubgit://github.com/yckao/postgres-large-object ↗

packagepostgres-large-object ↗

homepagegit://github.com/yckao/postgres-large-object ↗