View Source 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
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
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
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
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
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
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.