@supabase/postgrest-js

Supabase PostgREST JS SDK

Isomorphic JavaScript SDK for PostgREST with an ORM-like interface.

Guides · Reference Docs · TypeDoc

Quick start

Install

npm install @supabase/postgrest-js

Usage

import { PostgrestClient } from '@supabase/postgrest-js'

const REST_URL = 'http://localhost:3000'
const postgrest = new PostgrestClient(REST_URL)

• select()
• insert()
• update()
• delete()

Custom fetch implementation

postgrest-js uses the runtime's global fetch to make HTTP requests, but an alternative fetch implementation can be provided as an option. This is useful in environments where the global fetch is unavailable or where you want to customize request behavior:

import { PostgrestClient } from '@supabase/postgrest-js'

const REST_URL = 'http://localhost:3000'
const postgrest = new PostgrestClient(REST_URL, {
  fetch: (...args) => fetch(...args),
})

Development

This package is part of the Supabase JavaScript monorepo. To work on this package:

Building

# Build (from monorepo root)
pnpm nx build postgrest-js

# Build with watch mode for development
pnpm nx build:watch postgrest-js

# TypeScript type checking
pnpm nx type-check postgrest-js

# Generate documentation
pnpm nx docs postgrest-js

Testing

Supabase CLI Required! The postgrest-js tests use the Supabase CLI to run a local PostgreSQL database and PostgREST server.

Quick Start

# Run all tests (from monorepo root)
pnpm nx test:ci:postgrest postgrest-js

This single command automatically:

• Stops any existing Supabase CLI containers
• Starts PostgreSQL database and PostgREST server via Supabase CLI
• Resets and seeds the database
• Runs all Jest unit tests with coverage
• Cleans up containers

Individual Test Commands

# Run Jest tests with coverage (requires infrastructure running)
pnpm nx test:run postgrest-js

# Run type tests with tstyche
pnpm nx test:types postgrest-js

# Run smoke tests (CommonJS and ESM imports)
pnpm nx test:smoke postgrest-js

# Format code
pnpm nx format postgrest-js

# Check formatting
pnpm nx format:check postgrest-js

Test Infrastructure

The tests use Supabase CLI to spin up:

• PostgreSQL - Database with test schema and seed data (port 54322)
• PostgREST - REST API server that the client connects to (port 54321)

# Manually manage test infrastructure (from monorepo root)
pnpm nx test:infra postgrest-js      # Start containers
pnpm nx test:clean-pre postgrest-js  # Stop and remove containers

Or directly via Supabase CLI:

cd packages/core/postgrest-js
npx supabase --workdir ./test start        # Start all services
npx supabase --workdir ./test db reset     # Reset and seed database
npx supabase --workdir ./test stop         # Stop all services

Regenerating TypeScript Types

When the database schema changes, regenerate TypeScript types from the actual database:

# From the monorepo root
pnpm run codegen:postgrest

This command automatically:

• Cleans up any existing Supabase containers
• Starts Supabase (PostgreSQL, PostgREST, and all services)
• Generates TypeScript types from the database schema
• Post-processes the generated types (updates JSON type definitions)
• Formats the generated file with Prettier
• Cleans up Supabase containers

The generated types are written to test/types.generated.ts.

Test Types Explained

• Unit Tests - Jest tests covering all client functionality (pnpm nx test:run postgrest-js)
• Type Tests - Validates TypeScript types using tstyche (pnpm nx test:types postgrest-js)
• Smoke Tests - Basic import/require tests for CommonJS and ESM (pnpm nx test:smoke postgrest-js)

Prerequisites

• Supabase CLI must be installed (instructions) or can be used through npx (npx supabase)
• Docker must be installed and running (Supabase CLI uses Docker under the hood)
• Port 54321 - PostgREST API
• Port 54322 - PostgreSQL database
• Port 54323 - Supabase Studio (used for type generation)

PostgREST v12 Backward Compatibility Tests

We maintain backward compatibility tests for PostgREST v12 (the current Supabase CLI uses v14+). These tests ensure the SDK works correctly for users still running older PostgREST versions.

# Run v12 compatibility tests (requires Docker)
pnpm nx test:ci:v12 postgrest-js

This command:

• Starts PostgREST v12 + PostgreSQL in Docker (ports 3012/5433)
• Runs runtime tests that verify v12-specific behavior
• Cleans up containers

Type-only tests for v12 compatibility also run as part of the regular type tests:

pnpm nx test:types postgrest-js  # Includes v12-compat.test-d.ts

Note: These v12 tests will be removed when v3 ships (sometime in 2026).

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

For major changes or if you're unsure about something, please open an issue first to discuss your proposed changes.

License

This repo is licensed under MIT License.

Similar packages

Other packages similar to @supabase/postgrest-js

pg

The 'pg' package is a PostgreSQL client for Node.js. It allows you to interact with PostgreSQL databases using SQL queries. Unlike @supabase/postgrest-js, which provides a higher-level abstraction for CRUD operations and real-time subscriptions, 'pg' requires you to write raw SQL queries and manage connections manually.

knex

Knex.js is a SQL query builder for Node.js, supporting multiple database types including PostgreSQL. It provides a more flexible and powerful way to build SQL queries compared to @supabase/postgrest-js. However, it does not offer built-in real-time subscriptions and requires more setup for basic CRUD operations.

sequelize

Sequelize is a promise-based Node.js ORM for various SQL databases, including PostgreSQL. It provides a higher-level abstraction for database operations, similar to @supabase/postgrest-js, but with more features like model definitions, associations, and migrations. However, it does not natively support real-time subscriptions.