postgres-entities

library1.1.3jsnpmunverified

A library for storing structured JSON documents with versioning, etag/last-modified tracking, and zero-downtime migration support in PostgreSQL. Current stable version is 1.1.3, under initial development. Designed as a replacement for Azure Entities, it targets Node.js >=10 and focuses on redeployability, data visibility, and reliable optimistic concurrency via automatic etag and last-modified columns. Key differentiators include a human-readable storage format, table-level stored procedures for atomic updates, and built-in migration flow supporting multiple schema versions.

database

npm install postgres-entities

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POSTGRES-ENTITIES

postgres-entities

databasejavascriptv1.1.3

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.

Entity

✓ import { Entity } from 'postgres-entities'

✗ const { Entity } = require('postgres-entities')

The library is ESM-only; using require() will fail.

defineEntity

✓ import { defineEntity } from 'postgres-entities'

✗ import defineEntity from 'postgres-entities'

defineEntity is a named export, not default.

EntitySchema

✓ import type { EntitySchema } from 'postgres-entities'

TypeScript users should import the type for schema definitions.

Shows how to define an entity schema, ensure the table exists, and create an entity.

import { defineEntity } from 'postgres-entities'; import { Pool } from 'pg'; const pool = new Pool({ connectionString: process.env.DATABASE_URL ?? 'postgres://localhost/mydb', }); const MyEntity = defineEntity({ tableName: 'my_entities', version: 1, properties: { id: { type: 'string', partitionKey: true }, name: { type: 'string' }, count: { type: 'number' }, }, }); async function main() { await MyEntity.ensureTable(pool); const entity = await MyEntity.create(pool, { id: 'abc', name: 'test', count: 42, }); console.log('Created:', entity); } main().catch(console.error);

Debug

Known issues

breakingRequires Node.js >=10.0.0; older versions will fail to run.

fix

Upgrade Node.js to version 10 or later.

affects: <10.0.0

breakingTable names are case-sensitive in PostgreSQL; mismatched casing causes errors.

fix

Use lowercase table names in defineEntity.

affects: all

gotchaETag and last-modified columns are auto-managed; manual updates may break concurrency.

fix

Do not directly update etag or last_modified columns; use library methods.

affects: all

deprecatedEntity schema versioning is required; missing version field will throw.

fix

Always include a version property in the entity definition.

affects: >=1.0.0

gotchaMigration functions must be provided for version upgrades; otherwise old entities become unreadable.

fix

Define a migration function when bumping the version.

affects: all

Errors

Common errors & fixes

Error: Cannot find module 'postgres-entities'

Package not installed or not resolved in current module context.

fix

Run `npm install postgres-entities` from the project root.

TypeError: defineEntity is not a function

Incorrect import style (default vs named).

fix

Use `import { defineEntity } from 'postgres-entities'`.

error: relation "my_entities" does not exist

Table not created before use.

fix

Call `await MyEntity.ensureTable(pool)` before CRUD operations.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client for database connections

Agent activity

4 hits · last 30 days

node

Resources

githubgithub.com:jhford/postgres-entities ↗

packagepostgres-entities ↗

homepagegithub.com:jhford/postgres-entities ↗