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.3.0


Renew server certificates with v3.2.3 _before_ upgrading to 3.3.0. Alternatively, start the server with the following environment variable: GODEBUG=x509ignoreCN=0.


The binaries of this version are compiled with go-1.16. In go 1.16, the x509 certificates ‘CommonName’ attribute is deprecated. Instead the SANs extension should be used.

This means certificates created with former versions of Xbus will be seen as invalid by the newer versions.

The best way to avoid this problem is to Renew server certificates prior to the migration with version 3.2.3 or later.

If this is not possible, the server still accept these certificates if the following environment variable is defined:


Envelope Storage

A new storage for envelopes is available, and switching to it is recommended. Learn more: Envelope Storage.

To 3.2.3

After applying this version, it is recommended to Renew server certificates, to make sure the future 3.3.0 update goes smoothly.

To 3.2.0

In this version we store only UTC dates in the database. The migration will convert most of the dates already stored. On a big database it can take a while, up to hours if there are several millions process with their logs and envelopes.

To speedup things we recommand to use the ‘purge’ commands (see Database Maintenance) before migrating.

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.


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

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).


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


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

    name: "myactor"
    kind: "emitter"

by this nice looking alternative:

    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.