3. Upgrading your QuasarDB installation#

3.1. How QuasarDB is versionned#

3.1.1. Stable and beta#

Starting with QuasarDB 3.8, QuasarDB uses the following versionning logic:

  • Even version numbers indicate a stable version

  • Odd version numbers indicate a beta/in development version

As a beta version matures, it will eventually be branched into stable. During the development process, the beta version may introduce breaking changes, which is why running beta in production isn’t advised.

For example, 3.10 is a matured 3.9, and both are considered of the same generation. We give every engine generation the name of an ancient stoic philosopher, which is why 3.9 and 3.10 share the same name “Marcus Aurelius”.

3.2. Things to keep in mind#

Uprading is a one way process, which is why it’s very important to backup your database before doing an upgrade so that you can quickly go back should anything go wrong.

Upgrades between stable versions are supported, for example, from 3.8 to 3.10, from 3.10 to 3.12. When you are using a beta version, you accept that things may break between versions, especially at the beginning of the beta cycle. As the product matures, we do our best to prevent breaking changes, but there is no guarantee.

The longest part of the upgrading process is the upgrade of the database, when this applies, this is highly dependent on your disk speed and the amount of data stored.

3.3. Upgrading from 3.8 to 3.10#

3.3.2. Licenses#

  • The license format is unchanged.

3.3.3. Client and daemon#

Statistics are now stored differently and grouped by UID, meaning that upgrading to QuasarDB 3.10 will reset your cluster statistics.

Compaction and trimming are now two seperate commands. Trimming deletes obsolete version, compaction is a lower-level operation related to the LSM tree.

3.3.4. Persistence#

  • The backend engine has been upgraded to RocksDB Cloud 6.5.3 and backward compatibility is thus not guaranteed.

  • A 3.10 node can load the data stored by a 3.8 node.

  • A 3.8 node cannot load the data stored by a 3.10 node.

3.3.5. Network#

  • A 3.8 client cannot connect to a 3.10 cluster.

  • A 3.10 client cannot connect to a 3.8 cluster.

3.4. Upgrading from 3.7 to 3.8#

3.4.1. Recommended procedure#

  • Backup your data

  • Shutdown all nodes in the cluster

  • Upgrade each node fom 3.7 to 3.8

  • Run dbtool repair on every node

    • The repair process will perform low-level persistence schema migrations and is required to ensure optimal performance

    • You need to run the dbtool version you are upgrading to. Example: if you upgrade from 3.7.0 to 3.8.3, you need to run dbtool 3.8.3

    • You need to have as much free space as the database is currently using. Example: if your database is 100 GiB large, you need up to 100 GiB of additional free space for temporary files.

    • You can run dbtool on every node in parallel

    • QuasarDB must not be running

  • Restart the cluster after dbtool ran successfully on every node

  • Ensure each node loads up correctly and that the log displays no error

  • Upgrade clients from 3.7 to 3.8

3.4.2. Licenses#

  • The license format is unchanged.

3.4.3. Client and daemon#

QuasarDB is now built to target Haswell architectures. It was previously built with a Westemere architecture as a target. If your CPU architecture is older than Haswell, you need to use the Core2 build. Failure to do so may results in “illegal instruction” fatal error.

This applies to client and server binaries.

3.4.4. Persistence#

  • Due to a RocksDB upgrade, new database will use a new index format that cannot be read by previous QuasarDB versions.

  • A 3.8 node can load the data stored by a 3.7 node.

  • A 3.7 node cannot load the data stored by a 3.8 node.

3.4.5. Network#

  • A 3.7 client cannot connect to a 3.8 cluster.

  • A 3.8 client cannot connect to a 3.7 cluster.

3.5. Upgrading from 3.6 to 3.7#

3.5.1. Recommended procedure#

  • Backup your data

  • Shutdown all nodes in your cluster

  • Upgrade each node fom 3.6 to 3.7

  • Restart the cluster

  • Ensure each node loads up correctly and that the log displays no error

  • Upgrade clients from 3.6 to 3.7

3.5.2. Client code#

By default, the API will not longer auto retry and wait for stabilization or network to become available. This means, that you may get more network timeouts and cluster stabilization errors than before.

To get the old client behavior back, you need to call `qdb_option_set_stabilization_max_wait` (or equivalent in your API) on every handle with a value equivalent to 6 minutes (360,000 ms).

This is a client-only change, the server configuration is not impacted and does not need to be modified.

3.5.3. Licenses#

  • The license format is unchanged.

3.5.4. Persistence#

  • Blobs and strings format has changed on disk. Only new data will be written in the new format.

  • A 3.7 node can load the data stored by a 3.6 node.

  • A 3.6 node cannot load the data stored by a 3.7 node.

3.5.5. Network#

  • A 3.6 client cannot connect to a 3.7 cluster.

  • A 3.7 client cannot connect to a 3.6 cluster.

3.6. Upgrading from 3.5 to 3.6#

3.6.1. Recommended procedure#

  • Backup your data

  • Shutdown all nodes in your cluster

  • Upgrade each node fom 3.5 to 3.6

  • Restart the cluster

  • Ensure each node loads up correctly and that the log displays no error

  • Upgrade clients from 3.5 to 3.6

3.6.2. Configuration#

  • The following default values have changed

    • Client timeout has been increased from 1 minute to 5 minutes

    • Client stabilization wait interval has been increased from 5 minutes to 6 minutes

    • Client transaction retry period has been increased from 1 minute to 6 minutes

    • Server client timeout has been increased from 1 minute to 5 minutes

    • Server idle timeount has been increased from 10 minutes to 15 minutes

3.6.3. Licenses#

  • The license format is unchanged.

3.6.4. Persistence#

  • A 3.6 node can load the data stored by a 3.5 node.

  • A 3.5 node cannot load the data stored by a 3.6 node.

3.6.5. Network#

  • A 3.5 client cannot connect to a 3.6 cluster.

  • A 3.6 client cannot connect to a 3.5 cluster.