pgmorbac/docs/DEVELOPMENT.md

Development Guide

Project Structure

pgmorbac/
├── src/                    # Modular SQL source files
├── tests/                  # Test files
├── tools/                  # Build and test scripts
├── docs/                   # Documentation
├── pgmorbac.control       # Version source of truth
├── pgmorbac.sql          # Generated (git-ignored)
└── Makefile               # Build automation

Version Management

Version is defined in pgmorbac.control under default_version.

Edit source files in src/ and commit them. Never edit or commit pgmorbac.sql (generated by build script).

Development Workflow

Edit Source Files

vim src/authorization.sql

Build and Test

make check

This builds from src/, creates a temporary database, runs all tests, and cleans up.

Commit Changes

git add src/authorization.sql tests/01_authorization.sql
git commit -m "Add feature X"

The build script concatenates src/ files in dependency order (header first, footer last).

Manual Testing

make build
createdb mytest
psql -d mytest -f pgmorbac.sql
psql -d mytest
dropdb mytest

Release Process

1. ./tools/bump_version.sh X.Y.Z (control file, META.json, README)
2. Update CHANGELOG.md
3. Run make build and make check
4. Commit and tag:

git commit -am "release: X.Y.Z"
git tag vX.Y.Z
git push origin master --tags

5. Signed SQL distribution, attached to the GitHub release. The release workflow does this on the tag, signing with the PGMORBAC_RELEASE_KEY repository secret. By hand:

PGMORBAC_RELEASE_KEY=<path to the Ed25519 key> GITHUB_REPOSITORY=crudylabs/pgmorbac \
  GITHUB_TOKEN=<token> npm run release

6. The npm package @crudy/pgmorbac is released from the pgmorbac-node repository, which packs the SQL of this signed release.

Makefile Targets

make build      # Build from src/ files
make check       # Build and run tests
make install    # Install to PostgreSQL
make help       # Show all targets

Code Style

SQL keywords in UPPERCASE. Identifiers in lowercase_snake_case. Always qualify with morbac. schema.

Functions use verb_noun pattern. Tables use plural nouns.

Adding Features

1. Edit files in src/
2. Add tests in tests/
3. Update docs/DOCUMENTATION.md
4. Run make check
5. Commit source files

Debugging

SELECT * FROM morbac.auth_cache ORDER BY computed_at DESC LIMIT 10;
SELECT morbac.invalidate_cache();
EXPLAIN ANALYZE SELECT morbac.is_allowed(...);
SELECT morbac.refresh_hierarchy_cache();

Resources

See DOCUMENTATION.md, PERFORMANCE.md, and ADMIN_GUIDE.md.