Melange v0.7.4

Melange v0.7.4 adds the melange generate migration command for integrating with external migration frameworks, introduces two-phase skip detection to the built-in migrator, and includes new unit tests and documentation improvements.

Highlights

melange generate migration — External Migration Framework Support

Users with existing migration systems (golang-migrate, sqlx, Flyway, etc.) can now generate versioned UP/DOWN SQL files instead of running melange migrate directly. Inspired by River Queue’s migrate-get command pattern.

# Full migration (first time or periodic snapshot)
melange generate migration \
  --schema schemas/schema.fga \
  --output db/migrations

# Diff migration against main branch (ideal for PRs)
melange generate migration \
  --schema schemas/schema.fga \
  --output db/migrations \
  --git-ref main

Three comparison modes control which functions appear in the migration:

Function-level change detection uses SHA-256 checksums to include only changed functions in diff migrations. Dispatcher functions (check_permission, list_accessible_objects, etc.) are always regenerated since they reference all relations. Orphaned functions from removed relations receive DROP FUNCTION IF EXISTS statements.

Output formats:

• Split (default) — produces TIMESTAMP_NAME.up.sql and TIMESTAMP_NAME.down.sql
• Single — produces TIMESTAMP_NAME.sql with both UP and DOWN sections
• Stdout — use --up or --down to pipe SQL directly

Generated migrations include metadata headers:

-- Melange Migration (UP)
-- Melange version: v0.7.4
-- Schema checksum: a1b2c3d4...
-- Codegen version: 1
-- Previous state: git:main
-- Changed functions: 3 of 12

See the Migrations concept guide and melange generate migration --help for full details.

Two-Phase Skip Detection in the Built-in Migrator

The built-in melange migrate command now uses two-phase skip detection to avoid unnecessary database writes:

• Phase 1 (fast path): If both the schema checksum and melange version match the last migration, skip entirely — no SQL generation needed.
• Phase 2 (smart apply): If the schema or version changed, generate SQL and compare function checksums against the last migration. If every function is identical and no orphans exist, skip re-applying and only record the new migration state.

This makes melange version upgrades efficient when the generated SQL hasn’t actually changed — no functions are re-applied, just the migration record is updated.

Improvements

Config Simplification

The configuration schema has been simplified: redundant per-subcommand schema fields have been removed in favour of a single top-level schema field. The new generate.migration config section sits alongside generate.client. Existing configurations continue to work without changes.

Documentation

• Added the Migrations concept guide covering both the built-in migrator and external migration framework integration, with example SQL output
• Documented the melange generate migration command in the CLI reference
• Fixed all broken internal links across the documentation site

Testing & Maintenance

• Added unit tests for pkg/migrator and pkg/clientgen
• Added migration system integration tests covering two-phase skip detection
• Upgraded google.golang.org/grpc from v1.78.0 to v1.79.3
• Enhanced README with Matrix chat link and contribution details

Migration Notes

From v0.7.3

No breaking changes. The built-in migrator automatically adds the function_checksums column to the melange_migrations table on the next run:

melange migrate

If you use an external migration framework, you can now generate versioned migration files:

melange generate migration \
  --schema melange/schema.fga \
  --output db/migrations \
  --git-ref main

Try It Out

# Install / upgrade CLI
brew install pthm/melange/melange

# Apply migrations
melange migrate

# Go runtime
go get github.com/pthm/melange/melange@v0.7.4

# TypeScript runtime
npm install @pthm/melange

Feedback

We welcome feedback and bug reports. Please open an issue with questions or feature requests.