Melange v0.6.4

The first project-ready preview of Melange is here, featuring major performance optimizations (2-5x faster list operations), comprehensive testing, and TypeScript support.

What is Melange?

Melange is an OpenFGA-to-PostgreSQL compiler that runs authorization entirely in your database. It compiles .fga schemas into specialized SQL functions at migration time, so permission checks are simple SQL calls executed inside PostgreSQL. Authorization data comes from a melange_tuples view you define over your existing tables - no tuple sync layer needed.

Why Melange?

• Zero network hops - Authorization checks run in the same database as your data
• Predictable performance - SQL query plans instead of unpredictable graph traversal
• No sync layer - Tuples derive from your existing tables via views
• OpenFGA compatible - Standard .fga schemas work out of the box

What’s New in v0.6.4

This release focuses on performance optimization and production readiness. After five preview releases refining the architecture, v0.6.4 delivers significant performance improvements and the tooling needed for real applications.

Highlights

Performance Optimizations

List Operations: 2-5x Faster for Complex Patterns

Significant performance improvements to list_subjects operations, particularly for schemas with userset references and exclusion patterns:

• CTE-based exclusion precomputation - Exclusion predicates now use Common Table Expressions for efficient filtering
• Optimized userset checks - Reduced redundant queries when checking [group#member] style patterns
• Cardinality estimates - Added ROWS 100 hints to help PostgreSQL’s query planner

Real-world impact on the OpenFGA compatibility benchmark suite:

• DirectExclusion pattern: 1.9ms → 0.4ms (4.75x faster)
• Userset with exclusion: 3.2ms → 1.1ms (2.9x faster)
• Complex closure patterns: 2.5ms → 0.8ms (3.1x faster)

These optimizations are particularly impactful for multi-tenant applications where list operations power permission-aware UI rendering.

Performance Metrics

Benchmark results from the OpenFGA compatibility suite (10,000 tuples per test):

All optimizations maintain correctness - 100% pass rate across the full OpenFGA compatibility test suite.

Comprehensive Testing Infrastructure

Extensive testing across multiple languages:

TypeScript Test Suite

• Unit tests for all core components (Cache, Validator, Checker)
• Integration tests against real PostgreSQL instances
• Cursor pagination edge case coverage
• Caching behavior validation
• Over 90% code coverage

Multi-Language Integration Tests

• Automated testing framework for generated clients
• Cross-language compatibility verification
• Shared test fixtures across Go and TypeScript
• Testcontainers integration for reproducible environments

The testing infrastructure ensures that generated clients behave identically across languages - the same schema produces the same authorization decisions in Go and TypeScript.

TypeScript Client

TypeScript is now a first-class language for Melange with both code generation and runtime support:

• Client code generator - Generate type-safe clients from your .fga schema
• Runtime implementation - Complete Checker API with caching and pagination
• Database adapters - Support for pg and postgres.js
• Comprehensive tests - Over 90% code coverage

The TypeScript client provides the same performance characteristics as the Go runtime - all heavy lifting happens in PostgreSQL using the compiled SQL functions.

# Generate TypeScript client
melange generate client --language typescript --output ./src/generated

# Install runtime
npm install @pthm/melange

See the TypeScript client README for complete documentation.

Developer Tools

explaintest - Query Performance Analysis

New debugging tool for analyzing PostgreSQL query plans:

just explaintest <test_name>

Provides detailed insights into query execution:

• Full EXPLAIN ANALYZE output with timing
• Execution plan visualization
• Statistics on buffer usage and planning time
• Helps identify optimization opportunities

This tool was instrumental in discovering and fixing the list operation performance issues - it’s now available for debugging your own schemas.

Enhanced dump-openfga-sql

Improved SQL inspection tooling:

• View generated specialized check functions
• Inspect relation feature analysis
• Debug code generation issues
• Understand query strategy selection

Documentation Improvements

Comprehensive godoc Documentation

• Complete API documentation for the internal/sqlgen package
• Architecture decision records inline with code
• Package-level overviews explaining design patterns
• Cross-referenced examples

Testing Guide

• New TESTING.md with contributor guidance
• Test organization and naming conventions
• How to add new test cases
• Integration test setup instructions

Journey to v0.6.4

v0.1.0 - Initial Preview

• Core OpenFGA schema parsing
• Basic permission checking in PostgreSQL
• View-based tuple storage

v0.2.0 - Pattern Support

• Comprehensive OpenFGA pattern coverage (exclusion, intersection, usersets, wildcards)
• OpenFGA test suite integration (100% pass rate)
• Relation closure precomputation
• List operations (list_accessible_objects, list_users)
• 10-50x performance improvements via recursive CTEs

v0.3.0 - Code Generation

• Specialized SQL functions generated for each relation
• Eliminated runtime model tables
• Dispatcher function for routing checks
• Complete list function code generation across all patterns

v0.4.3 - Multi-Language Foundation

• Language-agnostic restructuring
• Go runtime extracted to dedicated module
• Client code generation framework
• CLI rewrite with config file support (melange.yaml)
• doctor command for health checks

v0.5.1 - SQL Generation Refactoring

• Complete SQL generation architecture rewrite (Plan → Blocks → Render)
• Cursor-based pagination for list operations
• Version traceability in generated code

v0.6.4 - Performance & Production Readiness

• 2-5x performance improvements for list operations
• TypeScript client code generation and runtime
• Comprehensive multi-language testing
• Performance profiling tools (explaintest)
• Complete godoc documentation

Migration Notes

From v0.5.1

No breaking changes - this is a fully backward-compatible release. Simply upgrade and run:

melange migrate

Your existing schemas and databases will continue to work without modification. The performance optimizations are applied automatically when you run migrations.

New Projects

For new projects:

1. Install the CLI:

   brew install pthm/melange/melange

2. Define your schema in .fga format:

   model
     schema 1.1
   
   type user
   
   type document
     relations
       define owner: [user]
       define viewer: [user] or owner

3. Run migrations:

   melange migrate

See the documentation for complete setup instructions.

What’s Changed Since v0.5.1

• CTE-based exclusion precomputation - 2-5x faster list operations for complex patterns
• TypeScript client - Code generator and runtime implementation with full test coverage
• explaintest tool - Query performance analysis and debugging
• Multi-language integration tests - Automated cross-language compatibility verification
• Enhanced benchmark infrastructure - Faster data loading with COPY FROM
• Complete godoc documentation - API documentation for internal packages
• Various bug fixes and stability improvements

Known Limitations

As a pre-1.0 release, there are some expected limitations:

• Not battle-tested at scale - While the architecture is sound, we’re seeking feedback from real-world usage
• Not recommended for existing production systems - Great for new projects, but we recommend waiting for v1.0 before migrating critical live systems
• TypeScript contextual tuples - API exists but backend support is pending
• Limited language support - Currently Go and TypeScript; more languages planned
• Documentation gaps - Some advanced scenarios not yet documented

We encourage building new projects with Melange and welcome feedback on your experience.

What’s Next

The focus for v1.0.0:

1. Real-world validation - Gathering feedback from projects built with Melange
2. More performance optimizations - Further query plan improvements and caching strategies
3. Tooling enhancements - Better CLI experience, debugging tools, and migration utilities
4. Go and TypeScript client improvements - API refinements based on real-world usage
5. Enhanced observability - Structured logging and metrics
6. Documentation expansion - More examples, patterns, and migration guides

Try It Out

Get started with Melange v0.6.4:

# Install CLI
brew install pthm/melange/melange

# Create a schema file (schema.fga)
# Run migrations
melange migrate

# For Go projects
go get github.com/pthm/melange/melange@v0.6.4

# For TypeScript projects
npm install @pthm/melange
melange generate client --language typescript

See the documentation for complete setup instructions, examples, and guides.

Feedback Welcome

This is the first preview release I consider ready for building new projects. I’m actively seeking feedback on:

• Performance characteristics - How does it perform with your data and query patterns?
• API ergonomics - Is the Go/TypeScript API intuitive for your use cases?
• Missing features - What OpenFGA patterns or capabilities are you missing?
• Documentation - What examples or guides would help you get started?
• Real-world experience - Share your experience building with Melange

Please open an issue with your feedback.