Development Guide

Project Structure

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

Version Management

Version is defined in pg_morbac.control under default_version.

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

Development Workflow

Edit Source Files

vim src/authorization.sql

Build and Test

make test

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 pg_morbac.sql
psql -d mytest
dropdb mytest

Release Process

Update version in pg_morbac.control
Update CHANGELOG.md
Run make build and make test
Commit and tag:

git commit -m "Release vX.Y.Z"
git tag vX.Y.Z
git push origin main --tags

Makefile Targets

make build      # Build from src/ files
make test       # 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

Edit files in src/
Add tests in tests/
Update docs/DOCUMENTATION.md
Run make test
Commit source files

Debugging

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

Resources

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

2.2 KiB Raw Blame History