79fb46456f
The timescale clustering code so far has been written referring to the remote databases as 'servers'. This terminology is a bit overloaded, and in particular we don't enforce any network topology limitations that the term 'server' would suggest. In light of this we've decided to change to use the term 'node' when referring to the different databases in a distributed database. Specifically we refer to the frontend as an 'access node' and to the backends as 'data nodes', though we may omit the access or data qualifier where it's unambiguous. As the vast bulk of the code so far has been written for the case where there was a single access node, almost all instances of 'server' were references to data nodes. This change has updated the code to rename those instances.
Extension updates
This directory contains "modfiles" (SQL scripts) with modifications that are applied when updating from one version of the extension to another.
The actual update scripts are compiled from modfiles by concatenating them with the current source code (which should come at the end of the resulting update script). Update scripts can "jump" several versions by using multiple modfiles in order. There are two types of modfiles:
- Transition modfiles named
<from>-<to>.sql, wherefromandtoindicate the (adjacent) versions transitioning between. Transition modfiles are concatenated to form the lineage from an origin version to any later version. - Origin modfiles named .sql, which are included only in
update scripts that origin at the particular version given in the
name. So, for instance,
0.7.0.sqlis only included in the script moving from0.7.0to the current version, but not in, e.g., the update script for0.4.0to the current version. These files typically contain fixes for bugs that are specific to the origin version, but are no longer present in the transition modfiles.
To ensure that this update process works, there are a few principles to consider.
- Modfiles should, in most cases, only contain
ALTERorDROPcommands that change or remove objects. In some cases, modifications of metadata are also necessary. DROP FUNCTIONneeds to be idempotent. In most cases that means commands should have anIF EXISTSclause. The reason is that some modfiles might try to, e.g.,DROPfunctions that aren't present because they only exist in an intermediate version of the database, which is skipped over.- Modfiles cannot rely on objects or functions that are present in a previous version of the extension. This is because a particular modfile should work when upgrading from any previous version of the extension, where those functions or objects aren't present yet.
- The creation of new metadata tables need to be part of modfiles,
similar to
ALTERs of such tables. Otherwise, later modfiles cannot rely on those tables being present. - When creating a new aggregate, the
CREATEstatement should be added to both aggregate.sql AND an update file. aggregate.sql is run once when TimescaleDB is installed so adding a definition in an update file is the only way to ensure that upgrading users get the new function.
Notes on post_update.sql
We use a special config var (timescaledb.update_script_stage )
to notify that dependencies have been setup and now timescaledb
specific queries can be enabled. This is useful if we want to,
for example, modify objects that need timescaledb specific syntax as
part of the extension update).
The scripts in post_update.sql are executed as part of the ALTER EXTENSION stmt.
Note that modfiles that contain no changes need not exist as a
file. Transition modfiles must, however, be listed in the
CMakeLists.txt file in the parent directory for an update script to
be built for that version.