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.

.. _migration-to-3.3.0:

To 3.3.0
~~~~~~~~

.. warning::

    :ref:`administration-certificate-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
:ref:`administration-certificate-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: :ref:`administration-envelope-storage`.

.. _migration-to-3.2.0:

To 3.2.3
~~~~~~~~

*After* applying this version, it is recommended to
:ref:`administration-certificate-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
:ref:`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-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:

.. code-block:: yaml

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

by this nice looking alternative:

.. code-block:: yaml

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


Database migration
------------------

From version >= 3.0.0-beta.14
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After installing the new binaries, run :ref:`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`.