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.3.0
Warning
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.
Certificates
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:
GODEBUG=x509ignoreCN=0
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.
Note
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).
Cleanup
All the extra configuration entries, ie all the lines that were added by the ‘register’ operation, can be safely removed. This includes:
account-idactors.*.account-idactors.*.idactors.*.last_seenactors.*.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.