Melange v0.5.1 - Preview

This is likely the final preview release, featuring a complete SQL generation architecture refactoring and cursor-based pagination.

Highlights

SQL Generation Architecture Refactoring

Complete overhaul of the SQL generation system from string templates to a typed DSL with a Plan → Blocks → Render architecture:

• Plan Layer - High-level strategy selection and query planning
• Blocks Layer - Intermediate representation with typed query blocks
• Render Layer - Final SQL generation from structured blocks

This three-tier architecture improves:

• Maintainability - Clear separation of concerns between planning, structuring, and rendering
• Type Safety - Typed column references and expressions prevent SQL injection and generation errors
• Testability - Each layer can be tested independently
• Correctness - Programmatic SQL construction eliminates template bugs

The refactoring touched 286 files with over 19,000 insertions while maintaining 100% compatibility with the OpenFGA test suite.

Cursor-Based Pagination

Added efficient cursor-based pagination to list query APIs:

• list_accessible_objects - Page through objects a subject can access
• list_accessible_subjects - Page through subjects with access to an object

Cursor pagination provides:

• Consistent results - Stable pagination even when data changes
• Better performance - No OFFSET overhead for deep pages
• Simpler API - Single cursor token instead of page numbers

Version Traceability

Generated code and migrations now include version metadata:

• Generated SQL functions annotated with Melange version
• Migration metadata tracks which version created each migration
• Debugging support - Easier to identify which version generated specific code

Release Infrastructure Improvements

Enhanced release automation for better distribution:

• macOS code signing - Binaries signed with Apple Developer ID
• Notarization - macOS binaries notarized for Gatekeeper compatibility
• Automated releases - Streamlined release process with pre-flight tests

Internal Code Quality

Significant cleanup and reorganization:

• Removed legacy code - Eliminated deprecated Bob SQL builder naming and template-era code
• Package restructuring - Split internal/sqlgen into focused subpackages
• Unified analysis types - Consolidated GenerationCapabilities and ListStrategy
• Dead code removal - Deleted unused CanGenerate fields and legacy builders

Bug Fixes

• Exclusion predicates - Fixed missing exclusion predicates in list_subjects for complex closure patterns
• Lint issues - Resolved linting warnings across refactored code

Migration Notes

This release maintains full backward compatibility with v0.4.x schemas and databases. No migration steps are required beyond running melange migrate as usual.

The SQL generation refactoring is entirely internal - generated SQL functions remain functionally equivalent to previous versions while being produced through a more maintainable codebase.

What Changed Under the Hood

The SQL generation refactoring represents a complete rewrite of how Melange produces PostgreSQL functions:

Before (v0.4.x): String templates with helper functions

// String concatenation and template interpolation
sql := fmt.Sprintf("SELECT ... FROM %s WHERE ...", table)

After (v0.5.0): Typed DSL with structured builders

// Typed query construction
query := Select(
    Column("subject_type"),
    Column("subject_id"),
).From(
    Table("melange_tuples"),
).Where(
    Equal(Column("relation"), Literal("viewer")),
)

This shift eliminates an entire class of SQL generation bugs and makes the codebase significantly easier to maintain and extend.

Performance

No performance regressions - the refactoring maintains the same generated SQL structure while improving the generation process itself. Cursor-based pagination provides performance improvements for large result sets.

Testing

All changes validated against the full OpenFGA compatibility test suite with 100% pass rate across all pattern categories.

Acknowledgments

This release represents a significant engineering investment in code quality and maintainability, setting a solid foundation for a stable release.