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

Event store configuration

To use Commanded v1.0 you must also upgrade the adapter for the event store you are using.

Postgres EventStore

Use the commanded_eventstore_adapter and follow the Getting started guide.

In brief, the upgrade requires you to:

Define an event store module for your Commanded application:

 defmodule MyApp.EventStore do
   use EventStore, otp_app: :my_app
 end

Add a config entry containing the PostgreSQL database connection details for your event store module to each environment's mix config file (e.g. config/dev.exs):

 config :my_app, MyApp.EventStore,
   serializer: Commanded.Serialization.JsonSerializer,
   username: "postgres",
   password: "postgres",
   database: "eventstore",
   hostname: "localhost"

Configure the Commanded application to use the event store:

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

Event Store

Use the commanded_extreme_adapter and follow the Getting started guide.

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

You will need to upgrade to the v1.0 versions of any Commanded related library used by your application, such as the event store adapter and Ecto read model projections.

v1.2.0