@antelopejs/postgres

The PostgreSQL backend of AntelopeJS. It runs the database interface's queries on PostgreSQL with native column types and indexes, and serves existing tables.

Documentation · Interfaces · All interfaces and providers

The PostgreSQL backend of AntelopeJS. It runs the queries of the database interface on PostgreSQL with the pg driver, and maps schema definitions onto relational tables with native column types and indexes. It can also serve tables that already exist in a database it does not own.

Interfaces

Interface	Documentation
@antelopejs/interface-database	Database

The database interface pages document schemas, tables, queries, change feeds and atomic mutations.

Requirements

This package requires Node.js >=22.

Install

ajs project modules add @antelopejs/postgres

The command writes the module's default configuration, the URL postgres://postgres@localhost:5432/antelopejs with migrations: "safe".

The adapter calls PostgreSQL's pg_input_is_valid function, so that a text or jsonb value that is not a parseable date yields null and does not abort the whole statement. The server must provide that function. src/test/antelope.test.ts names the PostgreSQL image that the tests run against.

Configuration

import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  name: "my-project",
  modules: {
    postgres: {
      source: {
        type: "package",
        package: "@antelopejs/postgres",
        version: ">=0.4.0 <0.5.0",
      },
      config: {
        url: "postgres://postgres@localhost:5432/my-project",
        migrations: "safe",
        pool: { max: 10 },
      },
    },
  },
  envOverrides: {
    POSTGRES_URL: "modules.postgres.config.url",
  },
});

Key	Description
mode	"owned" (default) creates and converges the tables. "external" serves existing tables without changing them.
url	PostgreSQL connection string.
migrations	"safe" (default) adds columns and indexes, and also drops or swaps indexes that the adapter owns. "destructive" also alters and drops columns. See Schema convergence.
schemaPrefix	Prefix for generated PostgreSQL schema names, for several applications sharing one database.
pool	Optional pg.Pool options, merged over the URL.

docs/configuration.md lists the options for cursors, the statement timeout and change feeds.

Quick start

In the module that stores data, add the database interface:

pnpm add @antelopejs/interface-database

Then follow the database interface guide to declare a schema and query it. The same code runs on @antelopejs/mongodb and @antelopejs/rethinkdb. Behaviour worth knowing records where the backends differ.

Storage layout

Unlike the document-store backends, this module turns schema field declarations into DDL. Each AntelopeJS schema becomes a PostgreSQL schema, each table a real table, and each declared scalar field a column with a native type and native indexes. A query compiles to a single SQL statement. Filters become WHERE clauses, joins become JOINs, and a filter or orderBy over a declared field reaches its btree index.

• One PostgreSQL schema per AntelopeJS schema id.
• Declared scalar fields become typed columns. Objects, arrays and undeclared fields live in jsonb.
• An _instance discriminator column keeps schema instances apart.
• Schema convergence adds columns and indexes, drops or swaps the indexes the adapter owns, and refuses destructive column changes unless you turn them on.
• Change feeds are a durable log plus a pull-based reader.

Documentation

• Database is the @antelopejs/interface-database contract that this module implements.
• Configuration covers module sources, config blocks and config variables in antelope.config.ts.

This repository documents what is specific to the PostgreSQL backend:

Storage and schema	What a registered schema becomes in the database, the field-type table, what reaches an index, and how registration converges
Configuration	Every option construct accepts
External mode	Reading tables the module did not create, in a database it does not own
Change feeds	changes(), its ordering guarantee, its retention contract and its blind spots
Errors and refusals	Everything the module refuses, with the message it refuses by
Behaviour worth knowing	Things that answer rather than throw, where the answer may surprise you, including where this backend differs from the MongoDB and RethinkDB ones

Compatibility

Package	Supported	Tested with
@antelopejs/interface-core	>=0.5.0 <0.6.0	0.5.1
@antelopejs/interface-database	>=0.4.0 <0.5.0	0.4.0
@antelopejs/interface-database-catalog	>=0.0.3 <0.1.0	0.0.3

CI tests every Node.js major listed under node-versions in .github/workflows/ci.yml, and .nvmrc names the version for local work. The dependencies field of package.json sets the pg driver range, and src/test/antelope.test.ts names the PostgreSQL image that the tests run against.

Contributing

The engines field of package.json sets the Node.js floor. The floor comes from Testcontainers, a dev dependency whose bundled undici calls worker_threads.markAsUncloneable, which older Node.js majors lack.

pnpm install
pnpm lint
pnpm format:check
pnpm knip
pnpm test:unit      # fast loop: this repository's unit specs, no Docker
pnpm test           # everything, against PostgreSQL: unit specs, conformance and external-mode suites

pnpm test starts PostgreSQL with Testcontainers, so it needs a Docker daemon. Besides this repository's own tests, it runs the shared conformance suites of the interfaces listed in antelopeJs.implements.

To test against an existing server instead of a container, set PG_TEST_URL. It must point to a disposable instance, because the external suite drops and recreates a fixture database and may create a role.

PG_TEST_URL=postgres://postgres:postgres@localhost:5432/antelopejs_test pnpm test

Read the contribution guidelines before opening a pull request.

Part of AntelopeJS

This package belongs to AntelopeJS, the TypeScript framework where modules depend on contracts and the application chooses the provider. The open-source back office AntelopeJS DMS is built on it.

Area	Contracts	Providers
API	interface-api · interface-api-util · interface-data-api	api
Auth	interface-auth	auth-jwt
Database	interface-database · interface-database-decorators · interface-database-catalog · interface-mongodb · interface-rethinkdb	postgres · mysql · mongodb · rethinkdb
Redis	interface-redis · interface-redis-scheduler	redis
Email	interface-email	nodemailer · brevo
File storage	interface-file-storage	file-storage-local · file-storage-s3
Payments	interface-payment · interface-subscriptions · interface-stripe	stripe · mollie · checkout-com · payment-subscriptions

License

Apache-2.0