MonetDB maintains an automatic upgrade path, so upgrading a database from an older version of MonetDB to a newer version is as simple as restarting the database with the new version. Nevertheless, there is some finer detail worth mentioning.
Major vs minor releases. The MonetDB development team produces 2 - 3 major releases (a.k.a. "feature release") per year. For each major release, we often produce 1 - 3 service packs (a.k.a. “minor releases” or "bug fix release").
Upgrade path. Each MonetDB release comes with upgrade code if needed to upgrade databases created by a previous release. By chaining up the upgrade code of several releases, we can form an upgrade path of MonetDB version X to X+1, X+2, ..., X+n. Occasionally, the upgrade code of the oldest MonetDB versions is removed from this chain to keep the upgrade path maintainable. Moreover, if a database was created by a too old version of MonetDB, it might have become faster and safer to dump-and-restore the data to create a fresh database with the new MonetDB version.
How does the upgrade path work? When a MonetDB server of version X+n is started with a database created by a MonetDB server of version X, the new MonetDB server will firs t try to upgrade the database by applying the chain of upgrade code X+1, X+2, ..., X+n to it. Hence, although MonetDB only guarantees automatic upgrade of one major version, in practice, users can jump directly over multiple major releases f their databases were created by a MonetDB version still in the upgrade path.
How to upgrade my database? Finally, a DBA should conduct the following steps:
mserver5, it suffices to stop the
mserver5process with a TERM signal.
monetdb lock <dbname>; monetdb stop <dbname>
systemctl stop monetdbd.service
monetdbd stop </path/to/dbfarm>
mserver5 --dbpath=/path/to/<dbname> [more options...]
systemctl start monetdbd.service
monetdbd start </path/to/dbfarm>
monetdb release <dbname>; monetdb start <dbname>
Q: How long does an upgrade take?
A: The time it takes to upgrade a database depends on its size and how many changes need to be applied. the changes only involve, say, updating existing functions and adding new ones, an upgrade can be done within minutes. If the changes include updating the database’s internal format, upgrading a large database (e.g. 100s GB to TBs) can take hours. The upgrade code needs to read all data, modify them and write them securely back to disk.
Q: How to validate the database after an upgrade?
A: You can check the structural soundness of your database and, to some extent, the correctness of your data in the database as follows. Each step below can be conducted independently in any order, but conducted in the order listed here, each check goes one step further.
Stop and restart the database. During the restart, mserver5 will read and check the SQL catalogue information. This is the most important check. Without a valid catalogue, the database will not be able to start up. BEWARE that restart might take some time if you have just made a lot of changes to the database (e.g. the upgrade process you have just conducted). This is because the mserver5 needs to process the write-ahead-logs (WAL). When this process takes longer than a certain time threshold, mserver5 will print some information about the percentage of the WAL logs it has processed.
Check if all definitions (users, roles, schemas, tables, etc) are present as expected. See here for information about the system tables.
Check if the sizes of all tables are as expected. You can either just run a
SELECT COUNT(*) query on each table, or consult the information in the storage tables.
SELECT COUNT(*) query might not touch the actual data in your columns, so finally you should run some queries that really use the data. For instance:
Q: Can I downgrade?
A: No! Once the upgrade of a database is completed, it will be tagged by the current MonetDB server. This process is irreversible!
Therefore, our recommendation is to
If an upgrade really must be undone, it is possible through some manual work: make a CSV dump with the new MonetDB version and reload the data into the older MonetDB version. However, beware that the newer CSV dump may not be understandable by the older version, then, some manual work is needed to adjust the CSV dump.