Migration

This section contains information about migrating a xbus instance to a newer version.

Version specific instructions

The version specific instructions, unless told otherwise, must be applied even if a migration goes from a former version to a later version.

To 3.0.0-rc5

All the NATS subject of the API are now prefixed with “xbus.default” instead of just “xbus”, which breaks the API. Xbusd, xbus-http, xbusctl and _all_ the clients must be upgraded at the same time.

It also impacts hand-written clients only that need to adjust the subject they use.

Note

It you are curious to know why we did this change, have a look at https://bitbucket.org/orus-io/xbus/issues/5/bus-namespace

To 3.0.0-rc2

Starting with version 3.0.0-rc.2, all the xbus clients must advertise the protocol version they use. They will not be able to connect to the server if they fail to do so, or if their protocol version is not compatible with the server protocol version (compatibility is guaranteed as long as the major version number is the same).

As a consequence, when upgrading to xbus 3.0.0-rc.2 or later, all clients must be updated before they can connect to an upgraded server.

To make the upgrade process smoother, a 3.0.x client is able to connect to a pre-3.0.0-rc.2 server, allowing a progressive deployment of the clients before upgrading the server.

To 3.0.0-rc1

Starting with version 3.0.0-rc1, the client (xbusctl, xbus-client, xbus-http) configuration files are not rewritten by ‘register’. Instead, the tls configuration entries are written in a different files.

Although the old configuration files are still readable by the clients, they cannot be used for a certificate renewal operation. For this reason, it is recommended to split your client configuration files as soon as you upgrade to a version >= 3.0.0-rc.1.

Separate the tls.* entries

For each client account, remove the tls.* entries from the corresponding file, and put them in a separate file named <account-name>.certs (where <account-name> is the account name).

Cleanup

All the extra configuration entries, ie all the lines that were added by the ‘register’ operation, can be safely removed. This includes:

  • account-id
  • actors.*.account-id
  • actors.*.id
  • actors.*.last_seen
  • actors.*.status

Simplify

The actors dictionnary now accepts actor names as keys instead of numbers. It means you can replace such a content:

actors:
  "0":
    name: "myactor"
    kind: "emitter"
    ...

by this nice looking alternative:

actors:
  myactor:
    kind: "emitter"
    ...

Database migration

From version >= 3.0.0-beta.14

After installing the new binaries, run xbusd-migrate. It will automatically apply all the changes needed in the database.

From versions < 3.0.0-beta.14

After installing the new binaries, and before start xbusd, apply the migration scripts found in the ‘migration’ directory.

If you upgrade to a version >= 3.0.0-beta.14, the scripts must still be applied up to the 3.0.0-beta.14 migration script, then use xbusd migrate.