pg_statecharts_dev

Overview

Development tooling; server file privileges

Version

Build

You can build the RPM / DEB packages for pg_statecharts using pig build:

pig build pkg pg_statecharts         # build RPM / DEB packages

Install

You can install pg_statecharts directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install pg_statecharts;          # Install for current active PG version

pig ext install -y pg_statecharts -v 18  # PG 18
pig ext install -y pg_statecharts -v 17  # PG 17
pig ext install -y pg_statecharts -v 16  # PG 16

dnf install -y pg_statecharts_dev_18       # PG 18
dnf install -y pg_statecharts_dev_17       # PG 17
dnf install -y pg_statecharts_dev_16       # PG 16

apt install -y postgresql-18-pg-statecharts-dev   # PG 18
apt install -y postgresql-17-pg-statecharts-dev   # PG 17
apt install -y postgresql-16-pg-statecharts-dev   # PG 16

Create Extension:

CREATE EXTENSION pg_statecharts_dev CASCADE;  -- requires: pg_statecharts

Usage

Sources:

• Official source
• Official source
• Official source

pg_statecharts_dev 0.1.0 is the development companion to pg_statecharts. It imports SCXML definitions and generates Sqitch migrations. The production state-machine runtime does not need this file-access tooling.

Core Workflow

After installing the runtime and its dependency, enable the companion:

CREATE EXTENSION pg_statecharts_dev;
SELECT * FROM fsm.import_scxml_files(
  source_path => '/repo/statecharts',
  recursive => false,
  on_conflict_do_nothing => false
);

The source directory is on the database host. Statechart callbacks must exist with the expected signatures. Parse or validation failures roll back the import transaction instead of accepting part of a chart.

Migration Generation

SELECT fsm.gen_statechart_sqitch_migrations(
  source_path => '/repo/statecharts',
  sqitch_plan_file_path => '/repo/sqitch/sqitch.plan',
  recursive => false
);

Create the destination directories before generation and make them accessible to the database OS user. The generator writes deploy, revert and verify scripts, updates the plan, and can overwrite existing generated chart files. Review the changes before using them as application migrations.

Permissions and Boundaries

Server file reads require pg_read_server_files; writes require pg_write_server_files. These are broad privileges, not a sandbox restricted to the supplied path. Restrict the extension and roles to a controlled development database. It shares the fsm schema, is pure SQL and requires no preload; PostgreSQL 16–18 are the documented test targets.

Use the runtime’s current semantic-version helpers in generated migrations. For old migrations that cast to the removed semver type, follow the upstream migration guide; regenerating every historical chart can introduce callback-order failures. Deploy reviewed generated SQL to production without installing this companion there.