Registry / database / pgx

pgx

JSON →
library0.1.11jsnpmunverified

pgx is a simple Object-Document Mapper (ODM) for PostgreSQL, built on top of the popular pg module. Version 0.1.11 is the latest stable release, though the package appears to be in early development with some unimplemented features noted in the README. It aims to make PostgreSQL feel like NoSQL by allowing flexible schemaless operations via JSON columns, while still supporting traditional relational schemas. Key differentiators include automatic creation of tables from schema definitions, support for upsert, batch insert, and join-like reads across multiple schemas. The library is designed for Node.js environments (>=0.10) and uses a callback-based async pattern. Compared to full-featured ORMs like Sequelize or TypeORM, pgx is more lightweight and focuses on quick prototyping with minimal configuration, but lacks advanced features like migrations, transactions, or TypeScript support.

database
npm install pgx
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · PGX
P
pgx
databasejavascriptv0.1.11
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.

pgx
✓ var pgx = require('pgx')(require('pg'), config.connection, schemas);
✗ var pgx = require('pgx');
pgx must be initialized with the pg module, connection config, and schemas. Failure to do so will result in runtime errors.
schemas
✓ var schemas = { mySchema: { tableName: 'my_table', fields: { id: { type: 'serial', defval: 'nextval(...)' } } } };
✗ var schemas = { mySchema: { fields: { id: 'serial' } } };
Schemas must be objects with tableName and fields nested. See README for full format.
pg
✓ var pg = require('pg');
✗ var pg = require('pgx').pg;
The pg module is a separate dependency, not re-exported by pgx.

Shows complete setup: initialize pgx with pg module, connection config, and schema definition; then boot to create tables, insert a record, and read it back.

var pg = require('pg'); var pgx = require('pgx')(pg, { conop: { user: 'myuser', password: 'mypassword', database: 'mydb', host: 'localhost', port: 5432 } }, { thing: { tableName: 'things', fields: { name: { type: 'varchar(255)' }, created: { type: 'timestamp', defval: 'now()' } } } }); pgx.boot({}, function(err, res) { if (err) return console.error(err); console.log('Tables created'); pgx.insert('thing', { name: 'hello' }, function(err, data) { if (err) return console.error(err); console.log('Inserted:', data); pgx.read('thing', { name: 'hello' }, function(err, records) { if (err) return console.error(err); console.log('Read:', records); }); }); });
Debug
Known issues
gotchaThe pgx.boot function is not idempotent; it copies data from existing tables and may cause data loss if run multiple times.
fix
Use pgx.boot only when creating or migrating schemas, and ensure backups are taken before running.
affects: >=0.1.0
gotchaAvoid naming any table or schema 'schemas', as it is reserved internally.
fix
Do not use 'schemas' as a schema name.
affects: >=0.1.0
gotchaDefault fields schemaName_hash and schemaName_xattrs are added to every table; overriding them will cause PostgreSQL errors.
fix
Do not define fields named schemaName_hash or schemaName_xattrs in your schemas.
affects: >=0.1.0
deprecatedThe pgx.schemaVerify() function is listed in documentation but not implemented.
fix
Do not rely on schemaVerify; perform verification separately.
affects: >=0.1.0
gotchaThe returning clause in options does not work for extended (xattrs) fields.
fix
Avoid using returning for xattrs; retrieve them separately.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: pgx is not a function
Calling require('pgx') without immediately invoking the returned function with pg, config, and schemas.
fix
Correct usage: var pgx = require('pgx')(require('pg'), config, schemas);
error: relation "schemas" does not exist
Using 'schemas' as a schema name in your definition, which conflicts with internal table.
fix
Rename your schema to something other than 'schemas'.
error: column "schemaName_hash" of relation "..." already exists
Manually defining schemaName_hash field in your schema, which pgx automatically adds.
fix
Remove the schemaName_hash field from your schema definition.
pgx.boot is not a function
pgx was not initialized correctly; likely missing the (pg, config, schemas) call.
fix
Ensure you call var pgx = require('pgx')(pg, config, schemas);
Upgrade
Version history
0.1.11latest on npm
Audit
Dependencies
pgrequiredRequired as the underlying PostgreSQL driver; pgx wraps pg functions.
Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/nikfrank/pgx ↗
packagepgx ↗
homepagehttp://nikfrank.com/#/works/pgx ↗
pgx — npm install pgx · libregistry