Contents

• fsm_core
  • What it does
  • Where it is helpful
  • Requirements
  • Installation
    • Via PGXN
    • Manual
  • Reference

fsm_core

A finite state machine engine that runs entirely inside PostgreSQL.

What it does

fsm_core lets you define, run, and persist state machines as first-class database objects. States, transitions, guards, and event history all live in PostgreSQL — no application-side orchestration layer required.

A state machine is defined once as a JSON schema, compiled into the database, and then driven by sending events through SQL functions. The database enforces which transitions are valid, records every event, and keeps each instance at exactly one state at a time.

Where it is helpful

• Workflow orchestration — model multi-step business processes (approvals, onboarding, order fulfilment) entirely in the database so any client or service can participate without duplicating logic
• Audit trails — every state change and event is persisted automatically; replay or inspect the full history of any instance with a query
• Concurrency safety — advisory locks prevent two callers from advancing the same instance simultaneously, without requiring application-level coordination
• Multiple execution models — drive machines synchronously (direct call), asynchronously via a pgmq-backed worker queue, or through a promise/callback pattern — all from the same schema
• Supabase compatible — ships with RLS-aware grants and PostgREST-friendly function signatures so it works out of the box as a Supabase backend

Requirements

Dependency	Minimum version	Notes
PostgreSQL	15
ltree	1.2	bundled with PostgreSQL
pgmq	1.4.4	must be installed separately
pg_jsonschema	0.3.3	installed automatically into the fsm_core schema

Installation

Via PGXN

pgxn install fsm_core

Then in your database:

CREATE EXTENSION ltree;
CREATE EXTENSION pgmq;
CREATE EXTENSION fsm_core;

Manual

Download the PGXN zip (or build it locally with npm run pgxnBuildAndPublish) and apply the SQL files inside in version order using psql or your migration tool of choice.

Reference

• PG→TS function mapping
• Release workflow & migration naming
• Development setup
• Extension creation ADR