Installation

PgShift is organized as independent modules. Install only what you need.

Packages

Package	Description
@pgshift/search	Full-text search via TSVector and pg_trgm
@pgshift/cache	Query result caching via materialized views
@pgshift/queue	Background job processing via SKIP LOCKED
@pgshift/vector	Semantic and hybrid search via pgvector and HNSW indexes
@pgshift/cron	Recurring job scheduling via pg_cron (requires @pgshift/queue)
@pgshift/workflow	DAG-based workflow orchestration with retries and saga compensation

Install

npm

npm install @pgshift/search
npm install @pgshift/cache
npm install @pgshift/queue
npm install @pgshift/vector
npm install @pgshift/cron @pgshift/queue
npm install @pgshift/workflow

pnpm

pnpm add @pgshift/search
pnpm add @pgshift/cache
pnpm add @pgshift/queue
pnpm add @pgshift/vector
pnpm add @pgshift/cron @pgshift/queue
pnpm add @pgshift/workflow

yarn

yarn add @pgshift/search
yarn add @pgshift/cache
yarn add @pgshift/queue
yarn add @pgshift/vector
yarn add @pgshift/cron @pgshift/queue
yarn add @pgshift/workflow

Requirements

• Node.js 20 or later
• PostgreSQL 12 or later
• An existing Postgres connection string

Some modules require additional Postgres extensions:

Module	Extension	Notes
@pgshift/search	pg_trgm	Enabled automatically when fuzzy: true
@pgshift/vector	pgvector	Must be installed on the Postgres server
@pgshift/cron	pg_cron	Must be installed on the Postgres server. Not available on all providers.

Environment setup

PgShift reads your connection string directly. No ORM configuration required.

const db = createClient({
  url: process.env.DATABASE_URL,
})

A typical DATABASE_URL follows the format:

postgres://user:password@host:5432/database

SSL

Pass an ssl option when connecting to managed Postgres providers:

const db = createClient({
  url: process.env.DATABASE_URL,
  ssl: { rejectUnauthorized: false },
})

Connection pool size

The default pool size is 10 connections. Adjust with the max option:

const db = createClient({
  url: process.env.DATABASE_URL,
  max: 20,
})

Teardown

Always call db.destroy() on process exit to drain the connection pool cleanly.

process.on('SIGTERM', async () => {
  await db.destroy()
  process.exit(0)
})