Migration & Compatibility

Azu provides smooth migration paths and maintains backward compatibility across versions. This section covers version upgrades, breaking changes, and compatibility guidelines.

Overview

Azu's migration features are designed for:

Smooth version upgrades with clear migration paths
Backward compatibility where possible
Breaking change documentation with migration guides
Deprecation warnings with clear upgrade instructions
Compatibility matrices for dependencies

Version Compatibility

Compatibility Matrix

Azu Version

Crystal Version

Status

End of Life

0.5.x

1.2.x+

✅ Current

0.4.x

1.1.x+

✅ Supported

2024-12-31

0.3.x

1.0.x+

⚠️ Deprecated

2024-06-30

0.2.x

0.36.x+

❌ EOL

2023-12-31

Version Upgrades

Upgrading to Azu 0.5.x

Azu 0.5.x introduces several improvements and breaking changes:

New Features

Enhanced WebSocket support with connection pooling
Improved template engine with better error handling
New middleware for rate limiting and IP spoofing protection
Better performance monitoring and metrics

Breaking Changes

Removed deprecated Azu::Handler::Session (use Azu::Handler::Session::Redis instead)
Changed WebSocket channel API for better type safety
Updated template engine configuration format
Modified response serialization interface

Migration Steps

Update Crystal Version

# Ensure you're using Crystal 1.2.x or later
crystal --version

Update Azu Version

# shard.yml
dependencies:
  azu:
    github: your-org/azu
    version: ~> 0.5.0

Update WebSocket Channels

# Before (0.4.x)
class ChatChannel < Azu::Channel
  ws "/chat"

  def on_message(message)
    # Old API
  end
end

# After (0.5.x)
class ChatChannel < Azu::Channel
  ws "/chat"

  def on_message(message : String)
    # New typed API
  end
end

Update Template Configuration

# Before (0.4.x)
Azu::Templates.configure do |config|
  config.template_path = "templates"
end

# After (0.5.x)
Azu::Configuration.configure do |config|
  config.template_path = "templates"
  config.template_cache = true
end

Learn more about Version Upgrades →

Breaking Changes

Azu 0.5.x Breaking Changes

1. WebSocket Channel API Changes

Before (0.4.x):

class ChatChannel < Azu::Channel
  def on_message(message)
    # message was untyped
  end
end

After (0.5.x):

class ChatChannel < Azu::Channel
  def on_message(message : String)
    # message is now typed as String
  end
end

2. Session Handler Removal

Before (0.4.x):

# This is no longer supported
Azu::Handler::Session.new

After (0.5.x):

# Use Redis session handler instead
Azu::Handler::Session::Redis.new(
  redis_url: ENV["REDIS_URL"]
)

3. Response Serialization Changes

Before (0.4.x):

struct UserResponse
  include Response

  def initialize(@user : User)
  end

  def render
    @user.to_json
  end
end

After (0.5.x):

struct UserResponse
  include Response

  def initialize(@user : User)
  end

  def render
    {
      id: @user.id,
      name: @user.name,
      email: @user.email
    }.to_json
  end
end

Learn more about Breaking Changes →

Deprecation Warnings

Azu provides deprecation warnings to help you identify code that needs to be updated:

Common Deprecation Warnings

1. Deprecated Handler Usage

# Warning: Azu::Handler::Session is deprecated
# Use Azu::Handler::Session::Redis instead
Azu::Handler::Session.new

2. Deprecated Template Methods

# Warning: render_template is deprecated
# Use view instead
render_template("user.html", user: user)

# Use this instead
view("user.html", user: user)

3. Deprecated Configuration

# Warning: Azu::Templates.configure is deprecated
# Use Azu::Configuration.configure instead
Azu::Templates.configure do |config|
  config.template_path = "templates"
end

Handling Deprecation Warnings

Enable Deprecation Warnings

# Enable deprecation warnings in development
Azu::Configuration.configure do |config|
  config.deprecation_warnings = true
end

Suppress Specific Warnings

# Suppress specific deprecation warnings
@[Deprecated("Use new_method instead")]
def old_method
  # Implementation
end

Update Deprecated Code

# Replace deprecated code with new API
# Old
render_template("template.html", data)

# New
view("template.html", data)

Compatibility Guidelines

1. API Compatibility

Stable APIs

Core endpoint interface
Request/response contracts
Basic middleware interface
Template rendering API

Evolving APIs

WebSocket channel API (improvements in 0.5.x)
Configuration interface (consolidated in 0.5.x)
Session handling (Redis-only in 0.5.x)

2. Dependency Compatibility

Required Dependencies

# shard.yml
dependencies:
  crystal: ">= 1.2.0"
  radix: "~> 0.1.0"
  schema: "~> 0.1.0"
  crinja: "~> 0.1.0"

Optional Dependencies

# For Redis sessions
redis: "~> 0.1.0"

# For database integration
db: "~> 0.1.0"

3. Environment Compatibility

Development Environment

# Development configuration
Azu::Environment.configure :development do |config|
  config.log_level = :debug
  config.hot_reload = true
  config.deprecation_warnings = true
end

Production Environment

# Production configuration
Azu::Environment.configure :production do |config|
  config.log_level = :info
  config.deprecation_warnings = false
  config.performance_mode = true
end

Migration Tools

1. Automated Migration Scripts

Azu provides migration scripts to help automate common upgrades:

# Run migration script for 0.4.x to 0.5.x
crystal run scripts/migrate_0_5.cr

# Check for deprecated code
crystal run scripts/check_deprecations.cr

2. Compatibility Checker

# Check compatibility with current version
Azu::Compatibility.check do |check|
  check.crystal_version(">= 1.2.0")
  check.azu_version(">= 0.5.0")
  check.dependencies
end

3. Upgrade Assistant

# Interactive upgrade assistant
crystal run scripts/upgrade_assistant.cr

Testing Migrations

1. Test Suite Updates

Update your test suite to work with new versions:

# spec/spec_helper.cr
require "spec"
require "../src/azu"

# Configure test environment for new version
Azu::Environment.configure :test do |config|
  config.log_level = :error
  config.deprecation_warnings = false
end

2. Compatibility Tests

# Test compatibility with new APIs
describe "Azu 0.5.x Compatibility" do
  it "supports new WebSocket API" do
    channel = TestChannel.new
    channel.should respond_to(:on_message)
  end

  it "supports new configuration" do
    Azu::Configuration.configure do |config|
      config.template_cache = true
    end
  end
end

Support and Resources

1. Migration Support

Migration Guide - Step-by-step upgrade instructions
Breaking Changes - Detailed breaking change documentation
GitHub Issues - Report migration issues

2. Community Resources

Discord Community - Get help with migrations
Migration Examples - Working migration examples
FAQ - Common migration questions

Next Steps

Version Upgrades - Step-by-step upgrade guides
Breaking Changes - Detailed breaking change documentation
Compatibility Matrix - Version compatibility information

Examples

Check out the migration examples for complete working examples of:

0.4.x to 0.5.x upgrades
Breaking change migrations
Compatibility testing
Automated migration scripts

Need help with migration? Start with the Version Upgrades guide for step-by-step instructions, then check Breaking Changes for detailed information about API changes.

PreviousWebSocket Testing NextVersion Upgrades

Last updated 2 days ago

Was this helpful?