Upgrade guide v0.19.x to v1.0

In v0.19.x and earlier a singleton Commanded application was used to host aggregates and support event handlers, process managers, and other infrastructure processes. For v1.0, support for multiple Commanded apps was added allowing you to define and use more than one Commanded app and to control its lifecycle. Follow the following upgrade advice to migrate your application to Commanded v1.0.

Commanded application

First you must define a Commanded application:

defmodule MyApp.Application do
  use Commanded.Application, otp_app: :my_app

  router(MyApp.Router)
end

The application needs to be configured. You can do so in application config:

# config/config.exs
config :my_app, MyApp.Application,
  event_store: [
    adapter: Commanded.EventStore.Adapters.EventStore,
    event_store: MyApp.EventStore
  ],
  pubsub: :local,
  registry: :local

Alternatively, you can include the event store, pubsub, and registry config when defining the application:

defmodule MyApp.Application do
  use Commanded.Application,
    otp_app: :my_app,
    event_store: [
      adapter: Commanded.EventStore.Adapters.EventStore,
      event_store: MyApp.EventStore
    ],
    pubsub: :local,
    registry: :local

  router(MyApp.Router)
end

Supervision

The Commanded application must be included and started somewhere in your app's supervision tree. You can include it within the top level application supervisor:

defmodule MyApp do
  use Application

  def start(_type, _args) do
    children = [
      MyApp.Application
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end  
end

Command dispatch

Previously commands were always dispatched via a router module. Now, you dispatch commands using your Commanded application:

:ok = MyApp.Application.dispatch(%DoSomething{..})

The above should be a straightforward find within your source code to replace the router module (e.g. MyApp.Router) with the new application module (e.g. MyApp.Application).

Optionally, you can dispatch a command using an existing router by configuring the router with the Commanded application:

defmodule MyApp.Router do
  use Commanded.Commands.Router, application: MyApp.Application
end

:ok = MyApp.Router.dispatch(%DoSomething{..})

It is also possible to specify the application during command dispatch:

:ok = MyApp.Router.dispatch(%DoSomething{..}, application: MyApp.Application)

Event handlers and process managers

Each handler, read model projections, and process manager needs to be provided with the additional application option:

defmodule MyApp.ExampleHandler do
  use Commanded.Event.Handler,
    application: MyApp.Application,
    name: "MyApp.ExampleHandler"
end

Upgrade Commanded supporting libraries