105 lines
2.2 KiB
Markdown
105 lines
2.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
vim src/authorization.sql
|
|
```
|
|
|
|
### Build and Test
|
|
|
|
```bash
|
|
make test
|
|
```
|
|
|
|
This builds from `src/`, creates a temporary database, runs all tests, and cleans up.
|
|
|
|
### Commit Changes
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
make build
|
|
createdb mytest
|
|
psql -d mytest -f pgmorbac.sql
|
|
psql -d mytest
|
|
dropdb mytest
|
|
```
|
|
|
|
## Release Process
|
|
|
|
1. Update version in `pgmorbac.control`
|
|
2. Update `CHANGELOG.md`
|
|
3. Run `make build` and `make test`
|
|
4. Commit and tag:
|
|
|
|
```bash
|
|
git commit -m "Release vX.Y.Z"
|
|
git tag vX.Y.Z
|
|
git push origin main --tags
|
|
```
|
|
|
|
## Makefile Targets
|
|
|
|
```bash
|
|
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
|
|
|
|
1. Edit files in `src/`
|
|
2. Add tests in `tests/`
|
|
3. Update `docs/DOCUMENTATION.md`
|
|
4. Run `make test`
|
|
5. Commit source files
|
|
|
|
## Debugging
|
|
|
|
```sql
|
|
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](DOCUMENTATION.md), [PERFORMANCE.md](PERFORMANCE.md), and [ADMIN_GUIDE.md](ADMIN_GUIDE.md).
|