Performance

Melange is designed for high-performance permission checking at scale. This page explains the performance characteristics you can expect and how to optimize your setup.

Performance Overview

Melange achieves sub-millisecond permission checks through:

1. Specialized SQL functions: Purpose-built functions generated for each relation
2. Precomputed closures: Role hierarchies resolved at migration time, not runtime
3. Index utilization: Generated SQL optimized for efficient index scans
4. In-database execution: No network round-trips for authorization

Pattern Complexity Benchmarks

All benchmarks run on Apple M2 Pro with PostgreSQL 16. These results show performance across different authorization patterns from the OpenFGA compatibility test suite.

Performance by Pattern Type

Complex Pattern Performance

More complex patterns combining multiple features:

Expensive Operations

Some patterns have significantly higher latency:

Validation Performance

Invalid requests are rejected immediately without database queries:

Scale Benchmarks

These benchmarks test performance at different tuple volumes using a GitHub-like authorization model.

Test Schema

The scale benchmarks use a model with organizations, repositories, and pull requests:

type organization
  relations
    define owner: [user]
    define admin: [user] or owner
    define member: [user] or admin
    define can_read: member

type repository
  relations
    define org: [organization]
    define reader: [user] or can_read from org
    define writer: [user] or reader
    define can_read: reader
    define can_write: writer
    define can_review: can_read but not author

type pull_request
  relations
    define repo: [repository]
    define author: [user]
    define can_read: can_read from repo
    define can_review: can_read from repo but not author

Test Data Configuration

Tuples include: org memberships, repo→org relationships, PR→repo relationships, and PR→author relationships.

Check Operations

Check operations execute specialized SQL functions and scale with O(1) constant time regardless of tuple count:

Key insight: All check operations maintain constant time regardless of dataset size. This is achieved through specialized SQL code generation that eliminates runtime schema interpretation.

List Operations

List operations find all objects a subject can access (or all subjects with access to an object). Performance varies by relation complexity:

ListObjects (find objects a user can access):

ListSubjects (find users with access):

Why the variation? Operations on direct relations (org membership, repo writers) achieve O(1) scaling. Operations that traverse parent relationships (repo readers via org, PRs via repo→org) scale linearly with the number of potential matches because they must join across relationship hierarchies.

Parallel Operations

Permission checks are fully parallelizable since each check is independent:

At 12 parallel workers, throughput increases ~4x compared to sequential checks.

Caching

The optional in-memory cache provides dramatic speedups for repeated checks:

Enable caching in your application:

cache := melange.NewCache(
    melange.WithTTL(time.Minute),
    melange.WithMaxSize(10000),
)
checker := melange.NewChecker(db, melange.WithCache(cache))

When to use caching:

• High read-to-write ratio (permissions checked frequently, changed rarely)
• Acceptable staleness window (typically 30s-5min depending on application)
• Memory budget available for cache storage

When to skip caching:

• Permissions change frequently
• Strict real-time consistency required
• Memory-constrained environments

Optimizing Performance

1. Design Efficient Schemas

Schema design has the biggest impact on query performance. The benchmarks show clear patterns:

Performance tiers by pattern:

Minimize intersections: Intersection is the most expensive set operation, especially for ListObjects and ListUsers:

# Slower: Intersection requires evaluating multiple paths
type document
  relations
    define viewer: writer and editor

# Faster: Union is much cheaper
type document
  relations
    define viewer: writer or editor

Prefer shallow hierarchies: Deep parent traversals increase query complexity:

# Better: Direct assignment with union
type document
  relations
    define viewer: [user, team#member]

# Slower: Deep parent chain
type document
  relations
    define viewer: viewer from folder
type folder
  relations
    define viewer: viewer from workspace

Use direct relations where possible: define viewer: [user] (~155 µs) is faster than nested computed usersets (~190 µs).

Be cautious with wildcards in ListObjects/ListUsers: While Check with wildcards is fast (~155 µs), wildcard expansion for list operations can be expensive (up to 9-21 ms in worst cases).

2. Avoid Runtime Contextual Tuples

Contextual tuples add ~3ms overhead per operation due to temporary table setup. Use stored tuples when possible:

// Slow: ~3.2ms with contextual tuples
checker.Check(ctx, user, "viewer", doc,
    melange.WithContextualTuples(temporaryPermissions))

// Fast: ~160µs with stored tuples
checker.Check(ctx, user, "viewer", doc)

If you need contextual tuples frequently, consider batching multiple checks together.

3. Index Your Tuples View

Proper indexing of your melange_tuples view source tables is critical:

-- Object-based lookups (most common pattern)
CREATE INDEX idx_org_members_lookup
    ON organization_members (organization_id, role, user_id);

-- Expression indexes for text ID conversion
CREATE INDEX idx_org_members_text
    ON organization_members ((organization_id::text), (user_id::text));

Without expression indexes, PostgreSQL must perform sequential scans when your view converts integer IDs to text.

See the Tuples View documentation for complete indexing guidance.

4. Use Appropriate Scaling Strategies

See Tuples View Scaling Strategies for implementation details.

5. Batch List Operations

For list operations at scale, consider pagination or streaming:

// Stream results instead of loading all at once
objects, err := checker.ListObjects(ctx, user, "viewer", "document",
    melange.WithLimit(100),
    melange.WithCursor(lastCursor),
)

6. Monitor Query Performance

Use EXPLAIN ANALYZE to identify slow queries:

EXPLAIN ANALYZE
SELECT check_permission('user', '123', 'viewer', 'document', '456');

Look for:

• Sequential scans: Add indexes to eliminate these
• High row estimates: May indicate missing statistics (ANALYZE your tables)
• Nested loops with high iterations: Consider schema simplification

Performance Comparison

How does Melange compare to alternatives?

Melange provides the consistency guarantees of transactional SQL with performance comparable to simpler RBAC systems, while supporting the full expressiveness of Zanzibar-style authorization.

Summary

Typical performance expectations:

• Check operations: 150-250 µs for most patterns
• ListObjects: 165-300 µs for simple patterns, 300-500 µs for complex patterns
• ListUsers: 155-330 µs for most patterns
• Validation errors: ~25-30 ns (instant rejection, no database hit)
• Cache hits: ~79 ns (~2000x faster than database)

Patterns to avoid for latency-sensitive paths:

• Deep intersection chains (use union where possible)
• Contextual tuples (use stored tuples)
• Wildcard expansion in ListObjects/ListUsers
• Deeply nested TTU chains

Further Reading

• Tuples View - Detailed indexing and scaling strategies
• Contributing: Benchmarking - Run benchmarks yourself
• How It Works - Architecture details explaining performance characteristics